Lucee Tag Reference

<cfhttp>

Lets you execute HTTP POST and GET operations on files. Using cfhttp, you can execute standard GET operations and create a query object from a text file. POST operations lets you upload MIME file types to a server, or post cookie, form field, URL, file, or CGI variables directly to a specified server.

Body

This tag may have a body.

Example

<cfhttp
	[addtoken=boolean]
	[authtype=string]
	[autocert=boolean]
	[cachedwithin=object]
	[charset=string]
	[clientcert=string]
	[clientcertpassword=string]
	[columns=string]
	[compression=string]
	[connectiontimeout=any]
	[delimiter=string]
	[domain=string]
	[encodeurl=boolean]
	[file=string]
	[firstrowasheaders=boolean]
	[getasbinary=string]
	[method=string]
	[multipart=boolean]
	[multiparttype=string]
	[name=string]
	[password=string]
	[path=string]
	[pooling=boolean]
	[port=number]
	[preauth=boolean]
	[proxypassword=string]
	[proxyport=number]
	[proxyserver=string]
	[proxyuser=string]
	[redirect=string]
	[resolveurl=boolean]
	[result=string]
	[sockettimeout=any]
	[textqualifier=string]
	[throwonerror=boolean]
	[timeout=any]
	url=string
	[useragent=string]
	[username=string]
	[workstation=string]>
[</cfhttp>]
This tag is also supported within cfscript
<cfscript>
	http
		[addtoken=boolean]
		[authtype=string]
		[autocert=boolean]
		[cachedwithin=object]
		[charset=string]
		[clientcert=string]
		[clientcertpassword=string]
		[columns=string]
		[compression=string]
		[connectiontimeout=any]
		[delimiter=string]
		[domain=string]
		[encodeurl=boolean]
		[file=string]
		[firstrowasheaders=boolean]
		[getasbinary=string]
		[method=string]
		[multipart=boolean]
		[multiparttype=string]
		[name=string]
		[password=string]
		[path=string]
		[pooling=boolean]
		[port=number]
		[preauth=boolean]
		[proxypassword=string]
		[proxyport=number]
		[proxyserver=string]
		[proxyuser=string]
		[redirect=string]
		[resolveurl=boolean]
		[result=string]
		[sockettimeout=any]
		[textqualifier=string]
		[throwonerror=boolean]
		[timeout=any]
		url=string
		[useragent=string]
		[username=string]
		[workstation=string] {
			[...]
	}
</cfscript>

Attributes

The attributes for this tag are fixed. Except for the following attributes no other attributes are allowed.
Name Type Required Description
addtoken boolean No if yes add urlToken as cookie 
authtype string No authentication type for a request with username and password, valid values are "BASIC" (default) and "NTLM" 
autocert boolean No When set to true, this attribute enables the automatic installation of SSL certificates for HTTPS connections,
ensuring the request can proceed without SSL certificate errors.
This is particularly useful for environments where certificates may not be pre-installed or are dynamically updated. 
cachedwithin any No possible values are:
String "request": If original content was created within the current request, cached content data is used.
a timeSpan (created with function CreateTimeSpan): If original content date falls within the time span, cached content data is used.
To use cached data, the tag must be called with the exact same arguments. 
charset string No set the charset for the call. 
clientcert string No The full path to a PKCS12 format file that contains the client certificate for the request. 
clientcertpassword string No Password used to decrypt the client certificate. 
columns string No Specifies the column names for a query when creating a query as a result of a cfhttp GET. 
compression string No Informs the target webserver to disable compression for the response. Possible values are:
  • true (default): compression enabled
  • false: compression disabled
  • none (deprecated): use "false" instead 
    		•
    connectiontimeout any No **Connection establishment timeout** in seconds or as a TimeSpan object. Controls how long to wait while establishing the initial TCP connection to the server.
    This timeout triggers during the TCP handshake phase, before any HTTP data is sent. Useful when the target server is unreachable, experiencing network issues, or is overwhelmed and not accepting new connections.
    If not specified, falls back to the `timeout` attribute value. 
    delimiter string No Used only when creating a query from an http request that returns data in a CSV format. This
    value specifies the Field delimiter for the CSV data. Only the first character is used. Default is a comma. 
    domain string No The domain to authenticate within. this attribute is only used when authentication type is "NTLM" 
    encodeurl boolean No Specifies whether to URL encode the the URL.
    If not set at all (auto mode), it only encodes when necessary to avoid double encoding.
    If set to true it encodes the URL, if set to false it does not touch it.
    This setting has no influence on the values from httpparam type="url", for this use the attribute "encoded" from httpparam 
    file string No The filename to be used for the file that is accessed. For GET operations, defaults to the name
    specified in url. Enter path information in the path attribute. 
    firstrowasheaders boolean No sets if first row of csv is file 
    getasbinary string No Controls how response content is handled:
  • **false** (default): Auto-detect content type - convert to CFML object if not recognized as text
  • **auto**: Convert unrecognized content to binary data
  • **true**: Always return content as binary data, even for text responses
    Affects the `filecontent` key in the result struct. 
    		•
    method string No HTTP method to use for the request. Supported methods:
  • **GET**: Download content or create queries from text files
  • **POST**: Send data to server (requires cfhttpparam tags)
  • **HEAD**: Retrieve headers only, no body content
  • **PUT**: Upload/replace resource on server
  • **DELETE**: Remove resource from server
  • **OPTIONS**: Get allowed methods for resource
  • **TRACE**: Diagnostic method for request/response chain
  • **PATCH**: Partially update existing resource
    Default is GET. 
    		•
    multipart boolean No Tells Lucee to send all data specified by cfhttpparam type="formField" tags as multipart form data, with a Content-Type of multipart/form-data. 
    multiparttype string No This Attribute is deprecated 
    name string No The name to assign to a query if the a query is constructed from a file. 
    password string No When required by a server, a valid password. 
    path string No The path to the directory in which a file is to be stored. If a path is not specified in a POST
    or GET operation, a variable is created (cfhttp.fileContent) that you can use to display the results
    of the POST operation in a cfoutput. 
    pooling boolean No Flag allowing to disable connection reuse on one off requests. 
    port number No The port number on the server from which the object is requested. Default is 80. When used with
    resolveURL, the URLs of retrieved documents that specify a port number are automatically resolved to
    preserve links in the retrieved document. If a port number is specified in the url attribute, the port
    value overrides the value of the port attribute. 
    preauth boolean No if set to true (default), Lucee sends the basic authentication (username password) always (Preemptive Basic Authentication),
    if set to false the authentication is only send when the server ask for it (status code 401). 
    proxypassword string No When required by a proxy server, a valid password. 
    proxyport number No The port number on the proxy server from which the object is requested. Default is 80. When
    used with resolveURL, the URLs of retrieved documents that specify a port number are automatically
    resolved to preserve links in the retrieved document. 
    proxyserver string No Host name or IP address of a proxy server. 
    proxyuser string No When required by a proxy server, a valid username. 
    redirect string No Boolean indicating whether to redirect execution or stop execution. The default is Yes. If set
    to No and throwOnError = "yes", execution stops if cfhttp fails, and the status code and associated
    error message are returned in the variable cfhttp.statusCode. To see where execution would have been
    redirected, use the variable cfhttp.responseHeader[LOCATION]. The key LOCATION identifies the path of
    redirection. Lucee will follow up to five redirections on a request. if this limit is exceeded,
    Lucee behaves as if redirect = "no".
    If set to "Lax", filecontent for redirects for POST and DELETE requests will be returned, since 7.0.0.208 
    resolveurl boolean No Yes or No. Default is No. For GET and POST operations, if Yes, page reference returned into the
    fileContent internal variable has its internal URLs fully resolved, including port number, so that
    links remain intact. 
    result string No return variable name, default "cfhttp" 
    sockettimeout any No **Socket read timeout** in seconds or as a TimeSpan object. Controls how long to wait for data between consecutive data packets after the connection is established.
    This timeout triggers while waiting for the server's response or if the server stops sending data mid-response. Different from connection timeout as it applies to data transfer, not connection establishment.
    If not specified, falls back to the `timeout` attribute value. 
    textqualifier string No Required for creating a query. Indicates the start and finish of a column. Should be
    appropriately escaped when embedded in a column. For example, if the qualifier is a double quotation
    mark, it should be escaped as """". If there is no text qualifier in the file, specify it as " ".
    Default is the double quotation mark ("). 
    throwonerror boolean No Whether to throw an exception on HTTP errors that can be caught with `cftry`/`cfcatch`.
    When **true**: Throws exceptions for connection failures, lookup errors, or non-2xx status codes.
    When **false** (default): Populates the result struct with error information instead.
    The result struct always contains an `ERROR` key indicating if an error occurred, regardless of this setting. 
    timeout any No **General timeout value** in seconds or as a TimeSpan object that serves as a fallback for connection and socket timeouts.
    When `connectionTimeout` or `socketTimeout` are not specified, this value is used for those timeouts.
    If no timeout is set, Lucee uses the **remaining request timeout** from the current page context.
    The request will always timeout at or before the page timeout, using whichever is smaller: the specified timeout or remaining request time. 
    url string Yes Full URL of the host name or IP address of the server on which the file resides. The URL must be
    an absolute URL, including the protocol (http or https) and hostname. It may optionally contain a port
    number. Port numbers specified in the url attribute override the port attribute. 
    useragent string No User agent request header. 
    username string No When required by a server, a valid username. 
    workstation string No The workstation the authentication request is originating from. Essentially, the computer name for this machine. this attribute is only used when authentication type is "NTLM"