Custom HTTP header API

The VAPIX® Custom HTTP header API makes it possible to add and remove a custom HTTP header to the HTTP responses on your Axis products.

Overview

The API implements /axis-cgi/customhttpheader.cgi as its communications interface to handle custom HTTP headers to the HTTP responses and supports the following methods:

Method	Description
`list`	Lists the custom headers available on your device.
`set`	Sets a custom header to your device.
`remove`	Removes a custom header from your device.
`getSupportedVersions`	Retrieve a list of supported API versions.

Identification

API Discovery: id=customhttpheader
AXIS OS: 9.80 and later

Please note that Axis OS version 10.11 is required before you can add multiple headers at once.

Default custom HTTP headers

Some devices come with pre-installed custom HTTP headers. Use the list method to see all headers. The pre-installed headers can be removed with the remove method.

Common examples

Add a custom header

Use this example to add a custom HTTP header to your device in order to extend functionality, such as adding a header with an unique ID for the device. Standard headers that can be added includes Cross-origin Resource Sharing, X-Frame-Options and Set-Cookie.

Set CORS header

Set the Cross-Origin Resource Sharing (CORS) header. This will tell your browser/application that domains specified in the header have permission to make a cross-origin request to the server, i.e. the header allowing the browser to break the same-origin policy.
```
http://<servername>/axis-cgi/customhttpheader.cgi
```
JSON input parameters
```
{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "set",
    "params": {
        "Access-Control-Allow-Origin": "http://axis.trusted.example.server.com"
    }
}
```

The CORS header will now be included in all responses from the web server once it has been restarted.

Successful response

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "set",
    "data": {
        "Access-Control-Allow-Origin": "http://axis.trusted.example.server.com"
    }
}

Set a Cookie header. This is used when you want to send cookies from the server to your browser/application.

http://<servername>/axis-cgi/customhttpheader.cgi

JSON input parameters

{
    "apiVersion": "1.0",
    "context": "OpticalContext",
    "method": "set",
    "params": {
        "Set-Cookie": "device=123; Max-Age=200"
    }
}

The Set-Cookie header will now be included in all responses from the web server once it has been restarted.

Successful response

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "set",
    "data": {
        "Set-Cookie": "deviceId=123; Max-Age=200"
    }
}

List custom headers

Use this example to retrieve a list of all the custom headers that have been added to the device.

Request a list of custom headers.

http://<servername>/axis-cgi/customhttpheader.cgi

JSON input parameters

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "list"
}

The JSON response in this example will showcase what it will look like if you had three custom headers installed on your device.

Successful response

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "list",
    "data": {
        "Set-Cookie": "deviceId=123; Max-Age=200",
        "CustomName": "CustomValue",
        "Another-Example": "Another-value"
    }
}

Remove a custom header

Use this example to remove a custom header from your device. The header is identified by its header name, meaning that any header value is optional and can be omitted.

Remove the Set-Cookie header.

http://<servername>/axis-cgi/customhttpheader.cgi

JSON input parameters

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "remove",
    "params": {
        "Set-Cookie": "deviceId=123; Max-Age=200"
    }
}

The Set-Cookie header will not be included in the by the web server once it has restarted.

Successful response

{
    "apiVersion": "1.0",
    "context": "OptionalContext",
    "method": "remove",
    "data": {
        "Set-Cookie": "deviceId=123; Max-Age=200"
    }
}

Get supported versions

Use this example to retrieve a list of API versions that are supported by your device.

Request a list containing the supported API versions.

http://<servername>/axis-cgi/customhttpheader.cgi

JSON input parameters

{
    "context": "<ID string>",
    "method": "getSupportedVersions"
}

Parse the JSON response.

Successful response

{
    "apiVersion": "1.0",
    "context": "<ID string>",
    "method": "getSupportedVersions",
    "data": {
        "apiVersions": ["1.0", "<major>.<minor>"]
    }
}

Error response

{
    "apiVersion": "1.0",
    "context": "<ID string>",
    "method": "getSupportedVersions",
    "error": {
        "code": <error code>,
        "message": "<error message>"
    }
}

API specification

list

This API method is used when you want to retrieve a list of all custom headers that has been added to the product.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/customhttpheader.cgi

Request body syntax

{
    "apiVersion": "<major>.<minor>",
    "context": "<ID string>",
    "method": "list"
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that should be used in the request.
`context=<string>`	The user sets this value and the application echoes it back in the response (optional).
`method="list"`	The operation that should be performed.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": "<ID string>",
  "method": "list",
  "data": {
    "<CustomHeaderName>": "<CustomHeaderValue>"
    ...
  }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="list"`	The operation that was performed.
`data.CustomHeaderName`	The name of the header
`data.CustomHeaderValue`	The content of the header.

Return value - Failure

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": "<ID string>",
  "method": "list",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="list"`	The operation that was performed.
`error.code`	The code representing the error that occurred in the request.
`error.message`	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

set

This API method is used when you want to set a custom header on your product.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/customhttpheader.cgi

Request body syntax

{
    "apiVersion": "<major>.<minor>",
    "context": "<ID string>",
    "method": "set",
    "params": {
        "<CustomHeaderName>": "<CustomHeaderValue>"
    }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that should be used in the request.
`context=<string>`	The user sets this value and the application echoes it back in the response (optional).
`method="set"`	The operation that should be performed.
`params.CustomHeaderName`	The name of the header.
`params.CustomHeaderValue`	The content of the header.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
    "apiVersion": "<major>.<minor>",
    "context": "<ID string>",
    "method": "set",
    "data": {
        "<CustomHeaderName>": "<CustomHeaderValue>"
    }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="set"`	The operation that was performed.
`data.CustomHeaderName`	The name of the header
`data.CustomHeaderValue`	The content of the header.

Return value - Failure

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": "<ID string>",
  "method": "set",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="set"`	The operation that was performed.
`error.code`	The code representing the error that occurred in the request.
`error.message`	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

remove

This API method is used when you want to remove a custom header on your product.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/customhttpheader.cgi

Request body syntax

{
    "apiVersion": "<major>.<minor>",
    "context": "<ID string>",
    "method": "remove",
    "params": {
        "<CustomHeaderName>": "<CustomHeaderValue>"
    }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that should be used in the request.
`context=<string>`	The user sets this value and the application echoes it back in the response (optional).
`method="remove"`	The operation that should be performed.
`params.CustomHeaderName`	The name of the header.
`params.CustomHeaderValue`	The content of the header.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
    "apiVersion": "<major>.<minor>",
    "context": "<ID string>",
    "method": "remove",
    "data": {
        "<CustomHeaderName>": "<CustomHeaderValue>"
    }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="remove"`	The operation that was performed.
`data.CustomHeaderName`	The name of the header
`data.CustomHeaderValue`	The content of the header.

Return value - Failure

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "<major>.<minor>",
  "context": "<ID string>",
  "method": "remove",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="remove"`	The operation that was performed.
`error.code`	The code representing the error that occurred in the request.
`error.message`	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

getSupportedVersions

This API method is used when you want to retrieve the supported API versions.

Request

Security level: Admin
Method: POST

http://<servername>/axis-cgi/customhttpheader.cgi

Request body syntax

{
    "context": "<ID string>",
    "method": "getSupportedVersions"
}

Parameter	Description
`context=<string>`	The user sets this value and the application echoes it back in the response (optional).
`method="remove"`	The operation that should be performed.

Return value - Success

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
    "apiVersion": "1.0",
    "context": "<ID string>",
    "method": "getSupportedVersions",
    "data": {
        "apiVersions": ["1.0", "<major>.<minor>"]
    }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="remove"`	The operation that was performed.
`data.apiVersions`	Response specific data.

Return value - Failure

HTTP Code: 200 OK
Content-Type: application/json

Response body syntax

{
  "apiVersion": "1.0",
  "context": "<ID string>",
  "method": "getSupportedVersions",
  "error": {
    "code": <error code>,
    "message": "<error message>"
  }
}

Parameter	Description
`apiVersion:"<major>.<minor>"`	The API version that was used in the request.
`context=<string>`	The context that was used the request was made (optional).
`method="remove"`	The operation that was performed.
`error.code`	The code representing the error that occurred in the request.
`error.message`	Explains the error that occurred.

Error codes

See Error codes for a complete list of potential error codes for this API.

Error codes

The following error codes are used by all API methods:

Code	Description
`1100`	Internal error. Refer to message field or logs.
`2100`	API version not supported.
`2101`	Invalid JSON format.
`2102`	Method does not exist.

Overview​

Identification​

Default custom HTTP headers​

Common examples​

Add a custom header​

Set CORS header​

Set a Cookie header​

List custom headers​

Remove a custom header​

Get supported versions​

API specification​

list​

set​

remove​

getSupportedVersions​

Error codes​

Overview

Identification

Default custom HTTP headers

Common examples

Add a custom header

Set CORS header

Set a Cookie header

List custom headers

Remove a custom header

Get supported versions

API specification

list

set

remove

getSupportedVersions

Error codes