LOG IN SIGN UP
Documentation

This section of the API documentation covers the pragmatic configuration of your services, in complement to the web interface.

As always, if something does not work as expected or differs from the web interface, please contact us right away via our Support Desk or IRC (#fastly on Freenode, or webchat).

Authentication

Nearly all API calls require your request to be authenticated though a few do not. You will use API tokens to authenticate your requests. See our authentication page for more information.

API reference

The main entry point for the API is https://api.fastly.com/. For the sake of brevity, examples below omit this.

ACL

An ACL is a named access control list for matching against a client's IP address during VCL processing. A new ACL is empty and is attached to a working version of a service (not locked or active). The version associated with the ACL must be activated to be used. To remove an ACL from use, the ACL must be deleted from a working version (not locked or active), and that version without the ACL must be activated.

Fields

field type description
name string

Name for the ACL. Must start with alphanumeric and contain only alphanumeric, underscore, and whitespace.

Actions

GET /service/service_id/version/version/acl

List ACLs

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/2/acl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "version": "2",
    "name": "my_acl",
    "id": "6tUXdegLTf5BCig0zGFrU3",
    "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
    "created_at": "2016-04-21T18:14:32+00:00",
    "updated_at": "2016-04-21T18:14:32+00:00",
    "deleted_at": null
  },
  {
    "version": "2",
    "name": "another_acl",
    "id": "6tUXdegLTf5BCig0zGFrU3",
    "service_id": "1jlmtMz1ncwA0KC3TBGD0X",
    "created_at": "2016-04-21T18:14:32+00:00",
    "updated_at": "2016-04-21T18:14:32+00:00",
    "deleted_at": null
  }
]
GET /service/service_id/version/version/acl/name

Retrieve a single ACL by name for the version and service

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/4/acl/my_acl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "version": 4,
  "name": "my_acl",
  "service_id": "6HLRMTXCDWZl6tF3yEuKok",
  "id": "2cFflPOskFLhmnZJEKU7y6",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
POST /service/service_id/version/version/acl

Create a new ACL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/4/acl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=my_acl
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "name": "my_acl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 4,
  "id": "2cFflPOskFLhmnZJEfUake",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
PUT /service/service_id/version/version/acl/old_name

Update ACL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/4/acl/my_acl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=updated_acl
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "version": 4,
  "name": "updated_acl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "id": "2cFflPOskFLhmnZJEfUake",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
DELETE /service/service_id/version/version/acl/name

Delete an ACL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/acl/my_acl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

ACL Entry

An ACL entry holds an IP address with optional subnet to make up an entry in an ACL. ACL entries are versionless and can be modified without activating a new version. ACL entries can also be negated.

Fields

field type description
ip string

An IP address.

subnet string

An optional subnet for the IP address.

acl_id string

The ACL this entry belongs to.

negated boolean

A boolean that will negate the match if true.

comment string

A personal freeform descriptive note.

Actions

GET /service/service_id/acl/acl_id/entries

List of ACL entries given service and ACL ID

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entries HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "6yxNzlOpW1V7JfSwvLGtOc",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "acl_id": "2cFflPOskFLhmnZJEfUake",
    "ip": "127.0.0.1",
    "negated": "0",
    "subnet": null,
    "comment": "",
    "created_at": "2016-04-21T18:14:32+00:00",
    "updated_at": "2016-04-21T18:14:32+00:00",
    "deleted_at": null
  },
  {
    "id": "1ujrCmULAWHUPP7Mzjefxa",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "acl_id": "2cFflPOskFLhmnZJEfUake",
    "ip": "127.0.0.2",
    "negated": "0",
    "subnet": 8,
    "comment": "",
    "created_at": "2016-04-21T18:14:32+00:00",
    "updated_at": "2016-04-21T18:14:32+00:00",
    "deleted_at": null
  }
]
GET /service/service_id/acl/acl_id/entry/entry_id

Retrieve a single ACL entry given service, ACL ID and entry ID

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entry/1ujrCmULAWHUPP7Mzjefxa HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "1ujrCmULAWHUPP7Mzjefxa",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "acl_id": "2cFflPOskFLhmnZJEfUake",
  "ip": "127.0.0.1",
  "negated": "0",
  "subnet": 8,
  "comment": "",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
POST /service/service_id/acl/acl_id/entry

Create ACL entry given service, ACL ID and properties

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entry HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/json
Accept: application/json
{"ip": "127.0.0.1", "subnet": 8, "negated": false}
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "1ujrCmULAWHUPP7Mzjefxa",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "acl_id": "2cFflPOskFLhmnZJEfUake",
  "ip": "127.0.0.1",
  "negated": 0,
  "subnet": 8,
  "comment": "",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
DELETE /service/service_id/acl/acl_id/entry/entry_id

Delete ACL entry given service, ACL ID, and entry ID

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entry/1ujrCmULAWHUPP7Mzjefxa HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}
PATCH /service/service_id/acl/acl_id/entry/entry_id

Update ACL entry given service, ACL ID, entry ID and properties

Authentication

API token of a user with at least Engineer permissions.

Request Example
PATCH /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entry/1ujrCmULAWHUPP7Mzjefxa HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/json
Accept: application/json
{"ip": "127.0.0.2"}
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "1ujrCmULAWHUPP7Mzjefxa",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "acl_id": "2cFflPOskFLhmnZJEfUake",
  "ip": "127.0.0.2",
  "negated": "0",
  "subnet": 0,
  "comment": "",
  "created_at": "2016-04-21T18:14:32+00:00",
  "updated_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null
}
PATCH /service/service_id/acl/acl_id/entries

Update ACL entries in batch given service, ACL ID, entry ID and properties

Authentication

API token of a user with at least Engineer permissions.

Request Example
PATCH /service/SU1Z0isxPaozGVKXdv0eY/acl/2cFflPOskFLhmnZJEfUake/entries HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/json
Accept: application/json
{
  "entries": [
    {
      "op": "create",
      "ip": "192.168.0.1",
      "subnet": "8"
    },
    {
      "op": "update",
      "id": "acl_entry_id",
      "ip": "192.168.0.2",
      "subnet": "16"
    },
    {
      "op": "delete",
      "id": "acl_entry_id"
    }
  ]
}
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Backend

A backend is an address (IP or domain) from which Fastly pulls content. There can be multiple backends for a service.

Fields

field type description
address string

An hostname, IPv4, or IPv6 address for the backend.

auto_loadbalance boolean

Whether or not this backend should be automatically load balanced.

between_bytes_timeout integer

How long to wait between bytes in milliseconds.

client_cert string

Unused.

comment string

A comment.

connect_timeout integer

How long to wait for a timeout in milliseconds.

error_threshold integer

Number of errors to allow before the backend is marked as down.

first_byte_timeout integer

How long to wait for the first bytes in milliseconds.

healthcheck string

The name of the healthcheck to use with this backend. Can be empty.

hostname string

The hostname of the backend.

ipv4 string

IPv4 address of the host.

ipv6 string

IPv6 address of the host.

locked boolean

Specifies whether or not the version is locked for editing.

max_conn integer

Maximum number of connections.

max_tls_version integer

Maximum allowed TLS version on SSL connections to this backend.

min_tls_version integer

Minimum allowed TLS version on SSL connections to this backend.

name string

The name of the backend.

port integer

The port number.

request_condition string

Condition, which if met, will select this backend during a request.

service_id string

The alphanumeric string identifying a service.

shield string

The shield POP designated to reduce inbound load on this origin by serving the cached data to the rest of the network.

ssl_ca_cert string

CA certificate attached to origin.

ssl_cert_hostname string

Overrides ssl_hostname, but only for cert verification. Does not affect SNI at all.

ssl_check_cert boolean

Be strict on checking SSL certs. Setting to null will use the system default value (true).

ssl_ciphers string

List of OpenSSL ciphers (see https://www.openssl.org/docs/manmaster/apps/ciphers.html for details).

ssl_client_cert string

Client certificate attached to origin.

ssl_client_key string

Client key attached to origin.

ssl_hostname string

(Deprecated) Use ssl_cert_hostname and ssl_sni_hostname to configure certificate validation.

ssl_sni_hostname string

Overrides ssl_hostname, but only for SNI in the handshake. Does not affect cert validation at all.

use_ssl boolean

Whether or not to use SSL to reach the backend.

version integer

The current version number of a service.

weight integer

Weight used to load balance this backend against others.

Actions

GET /service/service_id/version/version/backend

List all backends for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "address": "127.0.0.1",
    "auto_loadbalance": false,
    "between_bytes_timeout": 10000,
    "client_cert": null,
    "comment": "",
    "connect_timeout": 1000,
    "error_threshold": 0,
    "first_byte_timeout": 15000,
    "healthcheck": null,
    "hostname": null,
    "ipv4": "127.0.0.1",
    "ipv6": null,
    "locked": true,
    "max_conn": 200,
    "max_tls_version": null,
    "min_tls_version": null,
    "name": "backend-name",
    "port": 80,
    "request_condition": "",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "shield": null,
    "ssl_ca_cert": null,
    "ssl_cert_hostname": null,
    "ssl_check_cert": true,
    "ssl_ciphers": null,
    "ssl_client_cert": null,
    "ssl_client_key": null,
    "ssl_hostname": null,
    "ssl_sni_hostname": null,
    "use_ssl": false,
    "version": 1,
    "weight": 100
  }
]
GET /service/service_id/version/version/backend/name

Get the backend for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/backend/test-backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "address": "127.0.0.1",
  "auto_loadbalance": false,
  "between_bytes_timeout": 10000,
  "client_cert": null,
  "comment": "",
  "connect_timeout": 1000,
  "error_threshold": 0,
  "first_byte_timeout": 15000,
  "healthcheck": null,
  "hostname": null,
  "ipv4": "127.0.0.1",
  "ipv6": null,
  "locked": true,
  "max_conn": 200,
  "max_tls_version": null,
  "min_tls_version": null,
  "name": "backend-name",
  "port": 80,
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "ssl_ca_cert": null,
  "ssl_cert_hostname": null,
  "ssl_check_cert": true,
  "ssl_ciphers": null,
  "ssl_client_cert": null,
  "ssl_client_key": null,
  "ssl_hostname": null,
  "ssl_sni_hostname": null,
  "use_ssl": false,
  "version": 1,
  "weight": 100
}
POST /service/service_id/version/version/backend

Create a backend for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
ipv4=127.0.0.1&name=backend-name&port=80
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "address": "127.0.0.1",
  "auto_loadbalance": false,
  "between_bytes_timeout": 10000,
  "client_cert": null,
  "comment": "",
  "connect_timeout": 1000,
  "error_threshold": 0,
  "first_byte_timeout": 15000,
  "healthcheck": null,
  "hostname": null,
  "ipv4": "127.0.0.1",
  "ipv6": null,
  "locked": true,
  "max_conn": 200,
  "max_tls_version": null,
  "min_tls_version": null,
  "name": "backend-name",
  "port": 80,
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "ssl_ca_cert": null,
  "ssl_cert_hostname": null,
  "ssl_check_cert": true,
  "ssl_ciphers": null,
  "ssl_client_cert": null,
  "ssl_client_key": null,
  "ssl_hostname": null,
  "ssl_sni_hostname": null,
  "use_ssl": false,
  "version": 1,
  "weight": 100
}
PUT /service/service_id/version/version/backend/old_name

Update the backend for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the backend (used to select the correct backend if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/backend/backend-name HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=updated-backend-name
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "address": "127.0.0.1",
  "auto_loadbalance": false,
  "between_bytes_timeout": 10000,
  "client_cert": null,
  "comment": "",
  "connect_timeout": 1000,
  "error_threshold": 0,
  "first_byte_timeout": 15000,
  "healthcheck": null,
  "hostname": null,
  "ipv4": "127.0.0.1",
  "ipv6": null,
  "locked": true,
  "max_conn": 200,
  "max_tls_version": null,
  "min_tls_version": null,
  "name": "updated-backend-name",
  "port": 80,
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "ssl_ca_cert": null,
  "ssl_cert_hostname": null,
  "ssl_check_cert": true,
  "ssl_ciphers": null,
  "ssl_client_cert": null,
  "ssl_client_key": null,
  "ssl_hostname": null,
  "ssl_sni_hostname": null,
  "use_ssl": false,
  "version": 1,
  "weight": 100
}
DELETE /service/service_id/version/version/backend/name

Delete the backend for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/backend/backend-name HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Cache Settings

Controls how caching is performed on Fastly. When used in conjunction with Conditions the Cache Settings provide you with fine grain control over how long content persists in the cache.

Fields

field type description
action string

Allows for termination of execution and either cache, pass, or restart.

cache_condition string

Name of the condition used to test whether this settings object should be used.

name string

Name for the cache settings object.

stale_ttl integer

Sets the max "Time To Live" for stale (unreachable) objects.

ttl integer

Sets the "Time To Live".

Actions

GET /service/service_id/version/version/cache_settings

Get a list of all cache settings for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/cache_settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
  "action": "cache",
  "cache_condition": "",
  "name": "testcache",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "stale_ttl": "1200",
  "ttl": "3600",
  "version": "1"
  }
]
GET /service/service_id/version/version/cache_settings/name

Get a specific cache settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/cache_settings/testcache HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "cache",
  "cache_condition": "",
  "name": "testcache",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "stale_ttl": "1200",
  "ttl": "3600",
  "version": "1"
}
POST /service/service_id/version/version/cache_settings

Create a cache settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/cache_settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=testcache&stale_ttl=1000&ttl=1000&action=cache
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "cache",
  "cache_condition": "",
  "name": "testcache",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "stale_ttl": "1200",
  "ttl": "3600",
  "version": "1"
}
PUT /service/service_id/version/version/cache_settings/old_name

Update a specific cache settings object.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the cache settings object (used to select the correct cache settings object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/cache_settings/testcache HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
stale_ttl=2000&ttl=1000
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "cache",
  "cache_condition": "",
  "name": "testcache",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "stale_ttl": "2000",
  "ttl": "1000",
  "version": "1"
}
DELETE /service/service_id/version/version/cache_settings/name

Delete a specific cache settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/cache_settings/testcache HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Condition

Conditions are used to control when and how other objects are used in a service configuration. They contain a statement that evaluates to either true or false and is used to determine whether the condition is met.

Depending on the type of the condition, the statement field can make reference to the Varnish Variables req, resp, and/or beresp.

Fields

field type description
comment string
name string

Name of the condition.

priority integer

Priority assigned to condition. Order executes from 1 to 10, with 1 being first and 10 being last.

service_id string

The alphanumeric string identifying a service.

statement string

The statement used to determine if the condition is met.

type string

Type of the condition, either "REQUEST" (req), "RESPONSE" (req, resp), or "CACHE" (req, beresp).

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/condition

Gets all conditions for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/condtion HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "comment": "",
    "name": "testcondition",
    "priority": "10",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "statement": "req.url~ \"index.html\"",
    "type": "CACHE",
    "version": "1"
  }
]
GET /service/service_id/version/version/condition/name

Gets the specified condition.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/condition/testcondition HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "testcondition",
  "priority": "10",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "statement": "req.url~ \"index.html\"",
  "type": "CACHE",
  "version": "1"
}
POST /service/service_id/version/version/condition

Creates a new condition.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/condition HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=testcondition&statement=req.url~+\"index.html\"&priority=10
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "testcondition",
  "priority": "10",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "statement": "req.url~ \"index.html\"",
  "type": "CACHE",
  "version": "1"
}
PUT /service/service_id/version/version/condition/old_name

Updates the specified condition.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the condition object (used to select the correct condition object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/condition/testcondition HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
statement=req.url~+\"index.html\"&priority=10
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "testcondition",
  "priority": "10",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "statement": "req.url~ \"index.html\"",
  "type": "CACHE",
  "version": "1"
}
DELETE /service/service_id/version/version/condition/name

Deletes the specified condition.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/condition/testcondition HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Dictionary

A Dictionary is a table that stores key value pairs accessible to VCL functions during VCL processing. A new dictionary is empty and attached to a working version of a service (not locked/active). In order for the dictionary to appear in generated VCL, the version associated with the dictionary must be activated. To remove a dictionary, the dictionary must be deleted on a working version (not locked/active), and that version without the dictionary then must be activated.

Fields

field type description
created_at string

Time-stamp (GMT) when the dictionary was created.

deleted_at string

Time-stamp (GMT) when the dictionary was deleted.

id string

The alphanumeric string identifying a dictionary.

name string

Name for the Dictionary.

service_id string

The alphanumeric string identifying a service.

updated_at string

Time-stamp (GMT) when the dictionary was updated.

version integer

The current version of a service.

write_only boolean

Determines if items in the dictionary are readable or not.

Actions

GET /service/service_id/version/version/dictionary

List all dictionaries for the version of the service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/dictionary HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "created_at": "2016-04-29T22:16:23+00:00",
    "deleted_at": null,
    "id": "3vjTN8v1O7nOAY7aNDGOL",
    "name": "my_dictionary",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "updated_at": "2016-04-29T22:16:23+00:00",
    "version": 1,
    "write_only": false
  }
]
GET /service/service_id/version/version/dictionary/name

Retrieve a single dictionary by name for the version and service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/dictionary/my_dictionary HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "created_at": "2016-05-03T16:11:41+00:00",
  "deleted_at": null,
  "id": "5clCytcTJrnvPi8wjqPH0q",
  "name": "my_dictionary",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "updated_at": "2016-05-03T16:20:35+00:00",
  "version": 1,
  "write_only": false
}
POST /service/service_id/version/version/dictionary

Create named dictionary for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/dictionary HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=my_dictionary
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "created_at": "2016-05-03T16:11:41+00:00",
  "deleted_at": null,
  "id": "5clCytcTJrnvPi8wjqPH0q",
  "name": "my_dictionary",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "updated_at": "2016-05-03T16:11:41+00:00",
  "version": 1,
  "write_only": false
}
PUT /service/service_id/version/version/dictionary/old_name

Update named dictionary for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the dictionary object (used to select the correct dictionary object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/dictionary/my_dictionary HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=updated_dictionary
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "created_at": "2016-05-03T16:11:41+00:00",
  "deleted_at": null,
  "id": "5clCytcTJrnvPi8wjqPH0q",
  "name": "updated_dictionary",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "updated_at": "2016-05-03T16:11:41+00:00",
  "version": 1,
  "write_only": false
}
DELETE /service/service_id/version/version/dictionary/name

Delete named dictionary for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/dictionary/my_dictionary HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Dictionary Item

A DictionaryItem holds a key and value that make up an entry in a Dictionary. DictionaryItems are versionless so they can be modified without activating a new version.

Fields

field type description
created_at string

Time-stamp (GMT) when the dictionary was created.

deleted_at string

Time-stamp (GMT) when the dictionary was deleted.

dictionary_id string

The dictionary for this Item.

item_key string

Key for the DictionaryItem.

item_value string

Value for the DictionaryItem.

service_id string

The service the Dictionary belongs to.

updated_at string

Time-stamp (GMT) when the dictionary was updated.

Actions

GET /service/service_id/dictionary/dictionary_id/items

List of DictionaryItems given service and dictionary ID.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/items HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "dictionary_id": "5clCytcTJrnvPi8wjqPH0q",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "item_key": "some_key",
    "item_value": "some_value",
    "created_at": "2016-04-21T18:14:32+00:00",
    "deleted_at": null,
    "updated_at": "2016-04-21T18:14:32+00:00"
  }
]
GET /service/service_id/dictionary/dictionary_id/item/item_key

Retrieve a single DictionaryItem given service, dictionary ID and item key.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/item/some_key HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "dictionary_id": "5clCytcTJrnvPi8wjqPH0q",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "item_key": "some_key",
  "item_value": "some_value",
  "created_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null,
  "updated_at": "2016-04-21T18:14:32+00:00"
}
POST /service/service_id/dictionary/dictionary_id/item

Create DictionaryItem given service, dictionary ID, item key, and item value.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/item HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
item_key=some_key&item_value=some_value
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "dictionary_id": "5clCytcTJrnvPi8wjqPH0q",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "item_key": "some_key",
  "item_value": "some_value",
  "created_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null,
  "updated_at": "2016-04-21T18:14:32+00:00"
}
PUT /service/service_id/dictionary/dictionary_id/item/item_key

Upsert DictionaryItem given service, dictionary ID, item key, and item value.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/item/some_key HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
item_value=new_value
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "dictionary_id": "5clCytcTJrnvPi8wjqPH0q",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "item_key": "some_key",
  "item_value": "new_value",
  "created_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null,
  "updated_at": "2016-04-21T18:14:32+00:00"
}
PATCH /service/service_id/dictionary/dictionary_id/item/item_key

Update DictionaryItem given service, dictionary ID, item key, and item value.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PATCH /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/item/some_key HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
item_value=new_value
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "dictionary_id": "5clCytcTJrnvPi8wjqPH0q",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "item_key": "some_key",
  "item_value": "new_value",
  "created_at": "2016-04-21T18:14:32+00:00",
  "deleted_at": null,
  "updated_at": "2016-04-21T18:14:32+00:00"
}
PATCH /service/service_id/dictionary/dictionary_id/items

Update DictionaryItem in batch for given service, dictionary ID and key/value pairs for items.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PATCH /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/items HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/json
Accept: application/json
{
  "items": [
    {
      "op": "create",
      "item_key": "some_key",
      "item_value": "new_value"
    },
    {
      "op": "update",
      "item_key": "some_key",
      "item_value": "new_value"
    },
    {
      "op": "delete",
      "item_key": "some_key",
    },
  ]
}
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}
DELETE /service/service_id/dictionary/dictionary_id/item/item_key

Delete DictionaryItem given service, dictionary ID, and item key.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/dictionary/5clCytcTJrnvPi8wjqPH0q/item/some_key HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Diff

See the changes in configuration between two different versions of a service.

Fields

field type description
from integer

The version number being diffed from.

to integer

The version number being diffed to.

format string

The format the diff is being returned in (text, html or html_simple).

diff string

The differences between two specified versions.

Actions

GET /service/service_id/diff/from/from/to/to

Get diff between two versions

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
from integer

The version to diff from. Can either be a positive number from 1 to your maximum version or a negative number from -1 down (-1 is latest version etc)

to integer

The version to diff to. Uses same numbering scheme as from.

format string

Optional method to format the diff field. Can either be text (default), html or html_simple.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/diff/from/1/to/2 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
    "from": 1,
    "to": 2,
    "format": "text",
    "diff": "
 backends:
 - name: My Backend
   address: backend.example.com
   auto_loadbalance: '0'
   between_bytes_timeout: 10000
   client_cert:
   comment: ''
   connect_timeout: 1000
   error_threshold: 0
   first_byte_timeout: 15000
   healthcheck:
   hostname: www.example.com
   ipv4:
   ipv6:
   max_conn: 200
   port: 80
   request_condition: ''
   shield:
   ssl_ca_cert:
   ssl_client_cert:
   ssl_client_key:
   ssl_hostname:
   use_ssl: false
   weight: 100
 cache_settings: []
 comment: ''
 conditions: []
 deployed:
 directors: []
 domains:
 - name: www.example.com
   comment: ''
 gzips: []
-headers: []
+headers:
+- name: Debug
+  action: set
+  cache_condition:
+  dst: http.X-Test
+  ignore_if_set: '0'
+  priority: '10'
+  regex: ''
+  request_condition:
+  response_condition:
+  src: '\"testing\"'
+  substitution: ''
+  type: request
 healthchecks: []
 origins: []
 request_settings: []
 response_objects: []
 service_id: SU1Z0isxPaozGVKXdv0eY
 settings:
   general.default_host: ''
   general.default_ttl: 3600
 snippets: []
 staging:
 syslogs: []
 testing:
 vcls: []
 wordpress: []"
}

Director

A Director is responsible for balancing requests among a group of Backends. In addition to simply balancing, Directors can be configured to attempt retrying failed requests. Additionally, Directors have a quorum setting which can be used to determine when the Director as a whole is considered "up", in order to prevent "server whack-a-mole" following an outage as servers come back up.

Fields

field type description
backends array

List of backend associated with this director.

capacity integer

Load balancing weight for the backends.

comment string

Description field.

created_at string

Time-stamp (GMT) when the Director was created.

deleted_at string

Time-stamp (GMT) when the Director was deleted.

name string

Name for the Director.

quorum integer

The percentage of capacity that needs to be up for a director to be considered up. Integer, 0 to 100 (default: 75)

service_id string

The alphanumeric string identifying a service.

shield string

Selected POP to serve as a "shield" for origin servers.

type integer

What type of load balance group to use. Integer, 1 to 4. Values: 1=random, 2=round-robin, 3=hash, 4=client. (default: 1)

updated_at string

Time-stamp (GMT) when the Director was updated.

retries integer

How many backends to search if it fails. (default: 5)

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/director

List the directors for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/director HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "backends": [],
    "capacity": 100,
    "comment": "",
    "created_at": "2016-05-04T21:19:41+00:00",
    "deleted_at": null,
    "name": "test-director",
    "quorum": 75,
    "retries": 20,
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "shield": null,
    "type": 1,
    "updated_at": "2016-05-04T21:29:15+00:00",
    "version": 1
  }
]
GET /service/service_id/version/version/director/name

Get the director for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "backends": [],
  "capacity": 100,
  "comment": "",
  "created_at": "2016-05-04T21:19:41+00:00",
  "deleted_at": null,
  "name": "test-director",
  "quorum": 75,
  "retries": 10,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "type": 1,
  "updated_at": "2016-05-04T21:29:15+00:00",
  "version": 1
}
POST /service/service_id/version/version/director

Create a director for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/director HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=test-director
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "backends": [],
  "capacity": 100,
  "comment": "",
  "created_at": "2016-05-04T21:16:22+00:00",
  "deleted_at": null,
  "name": "test-director",
  "quorum": 75,
  "retries": 5,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "type": 1,
  "updated_at": "2016-05-04T21:16:22+00:00",
  "version": 1
}
PUT /service/service_id/version/version/director/name

Update the director for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
id=updated-director&retries=10
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "backends": [],
  "capacity": 100,
  "comment": "",
  "created_at": "2016-05-04T21:19:41+00:00",
  "deleted_at": null,
  "name": "test-director",
  "quorum": 75,
  "retries": 10,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "shield": null,
  "type": 1,
  "updated_at": "2016-05-04T21:19:41+00:00",
  "version": 1
}
DELETE /service/service_id/version/version/director/name

Delete the director for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Director Backend

Maps and relates backends as belonging to directors. Backends can belong to any number of directors but directors can only hold one reference to a specific backend.

Fields

field type description
backend_name string

Name of the backend to map to the specified director.

created_at string

Time-stamp (GMT) when the relationship was created.

deleted_at string

Time-stamp (GMT) when the relationship was deleted.

director string

Name of the director.

service_id string

The alphanumeric string identifying a service.

updated_at string

Time-stamp (GMT) when the relationship was updated.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/director/director_name/backend/backend_name

Returns the relationship between a Backend and a Director. If the Backend has been associated with the Director, it returns a simple record indicating this. Otherwise, returns a 404.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
director_name string

The director name.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director/backend/test-backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  "backend_name": "test-backend",
  "created_at": "2016-05-05T20:26:56+00:00",
  "deleted_at": null,
  "director_name": "test-director",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "updated_at": "2016-05-05T20:26:56+00:00",
  "version": 1
}
POST /service/service_id/version/version/director/director_name/backend/backend_name

Establishes a relationship between a Backend and a Director. The Backend is then considered a member of the Director and can be used to balance traffic onto.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
director_name string

The director name.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director/backend/test-backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  "backend_name": "test-backend",
  "created_at": "2016-05-05T20:24:29+00:00",
  "deleted_at": null,
  "director_name": "test-director",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "updated_at": "2016-05-05T20:24:29+00:00",
  "version": 1
}
DELETE /service/service_id/version/version/director/director_name/backend/backend_name

Deletes the relationship between a Backend and a Director. The Backend is no longer considered a member of the Director and thus will not have traffic balanced onto it from this Director.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
director_name string

The director name.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/director/test-director/backend/test-backend HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
  "status": "ok"
}

Domain

A domain represents the domain name through which visitors will retrieve content. There can be multiple domains for a service.

Fields

field type description
comment string

A personal freeform descriptive note.

name string

The name of the domain or domains associated with this service.

service_id string

The alphanumeric string identifying a service.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/domain/check_all

Checks the status of all domains' DNS records for a Service Version. Returns an array of 3 items. The first is the details for the domain, the second is the current CNAME of the domain, and the third is a boolean indicating whether or not it has been properly setup to use Fastly.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain/check_all HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  [
    {
      "comment": "",
      "name": "www.example.com",
      "service_id": "SU1Z0isxPaozGVKXdv0eY",
      "version": 1
    },
    "global.prod.fastly.net.",
    true
  ]
]
GET /service/service_id/version/version/domain/name/check

Checks the status of a specific domain's DNS record for a Service Version. Returns an array in the same format as domain/check_all.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain/www.example.com/check HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "comment": "",
    "name": "www.example.com",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": 1
  },
  "global.prod.fastly.net.",
  true
]
GET /service/service_id/version/version/domain

List all the domains for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "comment": "",
    "name": "www.example.com",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": 1
  }
]
GET /service/service_id/version/version/domain/name

Get the domain for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain/www.example.com HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "www.example.com",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
POST /service/service_id/version/version/domain

Create a domain for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=www.example.com
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "www.example.com",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
PUT /service/service_id/version/version/domain/old_name

Update the domain for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the domain object (used to select the correct domain object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain/www.example.com HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=www.updated-example.com
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "name": "www.updated-example.com",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
DELETE /service/service_id/version/version/domain/name

Delete the domain for a particular service and versions

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/domain/test-domain HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Gzip

Gzip configuration allows you to choose resources to automatically compress.

Fields

field type description
cache_condition string

The CACHE condition controlling when this gzip configuration applies. This field is optional.

content_types string

Space-separated list of content types to compress. If you omit this field a default list will be used.

extensions string

Space-separated list of file extensions to compress. If you omit this field a default list will be used.

name string

The name of the gzip configuration.

service_id string

The alphanumeric string identifying a service.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/gzip

List all gzip configurations for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/2/gzip HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "cache_condition": "",
    "content_types": "text/html text/css application/javascript",
    "extensions": "html css js",
    "name": "gzip-config-name",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": "1"
  }
]
GET /service/service_id/version/version/gzip/name

Get the gzip configuration for a particular service, version, and name.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
name string

Name of the gzip object

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/2/gzip/fonts HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content_types": "text/html text/css application/javascript",
  "extensions": "html css js",
  "name": "gzip-config-name",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1"
}
POST /service/service_id/version/version/gzip

Create a named gzip configuration on a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/2/gzip HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
name=gzip-config-name \
  &cache_condition= \
  &extensions=html%20css%20js \
  &content_types=text/html%20text/css%20application/javascript
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content_types": "text/html text/css application/javascript",
  "extensions": "html css js",
  "name": "gzip-config-name",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1"
}
PUT /service/service_id/version/version/gzip/old_name

Update a named gzip configuration on a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the gzip object (used to select the correct gzip object if the name has been changed).

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/2/gzip HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
cache_condition= \
  &extensions=html%20css%20js \
  &content_types=text/html%20text/css%20application/javascript
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content_types": "text/html text/css application/javascript",
  "extensions": "html css js",
  "name": "gzip-config-name",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1"
}
DELETE /service/service_id/version/version/gzip/name

Delete a named gzip configuration on a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
name string

Name of the gzip object

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/2/gzip HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Header objects are used to add, modify, or delete headers from requests and responses. The header content can be simple strings or be derived from variables inside Varnish. Regular expressions can be used to customize the headers even further.

Fields

field type description
action string

Accepts a string value, one of:

set -

Sets (or resets) a header

append -

Appends to an existing header

delete -

Delete a header

regex -

Perform a single regex replacement on a header

regex_repeat -

Perform a global regex replacement on a header

cache_condition string

Optional name of a CacheCondition to apply.

dst string

Header to set.

ignore_if_set integer

Don't add the header if it is added already. (Only applies to 'set' action)

name string

A handle to refer to this Header object.

priority integer

Lower priorities execute first. (Default: 100.)

regex string

Regular expression to use (Only applies to 'regex' and 'regex_repeat' actions).

request_condition string

Optional name of a RequestCondition to apply.

response_condition string

Optional name of a ResponseCondition to apply.

service_id string

The alphanumeric string identifying a service.

src string

Variable to be used as a source for the header content. (Does not apply to 'delete' action)

substitution string

Value to substitute in place of regular expression. (Only applies to 'regex' and 'regex_repeat')

type string

Accepts a string value, one of:

request -

Performs on the request before lookup occurs

fetch -

Performs on the request to the origin server

cache -

Performs on the response before it's stored in the cache

response -

Performs on the response before delivering to the client

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/header

Retrieves all Header objects for a particular Version of a Service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/header HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "action": "set",
    "cache_condition": null,
    "dst": "http.foo",
    "ignore_if_set": 0,
    "name": "testheader",
    "priority": "10",
    "regex": "",
    "request_condition": null,
    "response_condition": null,
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "src": "client.ip",
    "substitution": "",
    "type": "request",
    "version": "1"
  }
]
GET /service/service_id/version/version/header/name

Retrieves a Header object by name.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/header/testheader HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "set",
  "cache_condition": null,
  "dst": "http.foo",
  "ignore_if_set": 0,
  "name": "testheader",
  "priority": "10",
  "regex": "",
  "request_condition": null,
  "response_condition": null,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "src": "client.ip",
  "substitution": "",
  "type": "request",
  "version": "1"
}
POST /service/service_id/version/version/header

Creates a new Header object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/header HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=testheader&type=request&action=set&dst=http.foo&src=client.ip&ignore_if_set=0&priority=10
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "set",
  "cache_condition": null,
  "dst": "http.foo",
  "ignore_if_set": 0,
  "name": "testheader",
  "priority": "10",
  "regex": "",
  "request_condition": null,
  "response_condition": null,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "src": "client.ip",
  "substitution": "",
  "type": "request",
  "version": "1"
}
PUT /service/service_id/version/version/header/old_name

Modifies an existing Header object by name.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the header object (used to select the correct header object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/header/testheader HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=updatedtestheader&type=fetch&action=append&dst=http.foo&src=client.ip&ignore_if_set=0&priority=10
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "append",
  "cache_condition": null,
  "dst": "http.foo",
  "ignore_if_set": 0,
  "name": "updatedtestheader",
  "priority": "10",
  "regex": "",
  "request_condition": null,
  "response_condition": null,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "src": "client.ip",
  "substitution": "",
  "type": "fetch",
  "version": "1"
}
DELETE /service/service_id/version/version/header/name

Deletes a Header object by name.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/header/testheader HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Healthcheck

Healthchecks are used to customize the way Fastly checks on your Backends. If an origin server is marked unhealthy due to health checks, Fastly will stop attempting to send requests to it. If all origin servers are marked unhealthy, Fastly will attempt to serve stale. If no stale object is available, a 503 will be returned to the client.

Fields

field type description
check_interval integer

How often to run the healthcheck in milliseconds.

comment string

A comment.

expected_response integer

The status code expected from the host.

host string

Which host to check.

http_version integer

Whether to use version 1.0 or 1.1 HTTP.

initial integer

When loading a config, the initial number of probes to be seen as OK.

method string

Which HTTP method to use.

name string

The name of the healthcheck.

path string

The path to check.

service_id string

The alphanumeric string identifying a service.

threshold integer

How many healthchecks must succeed to be considered healthy.

timeout integer

Timeout in milliseconds.

version integer

The current version of a service.

window integer

The number of most recent healthcheck queries to keep for this healthcheck.

Actions

GET /service/service_id/version/version/healthcheck

List all of the healthchecks for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/healthcheck HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "check_interval": 5000,
    "comment": "",
    "expected_response": 200,
    "host": "example.com",
    "http_version": "1.1",
    "initial": 2,
    "method": "HEAD",
    "name": "example-healthcheck",
    "path": "/test.txt",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "threshold": 3,
    "timeout": 500,
    "version": 1,
    "window": 5
  }
]
GET /service/service_id/version/version/healthcheck/name

Get the healthcheck for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/healthcheck/example-healthcheck HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "check_interval": 5000,
  "comment": "",
  "expected_response": 200,
  "host": "example.com",
  "http_version": "1.1",
  "initial": 2,
  "method": "HEAD",
  "name": "example-healthcheck",
  "path": "/test.txt",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "threshold": 3,
  "timeout": 500,
  "version": 1,
  "window": 5
}
POST /service/service_id/version/version/healthcheck

Create a healthcheck for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/healthcheck HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencod
Accept: application/json
name=example-healthcheck&host=example.com&path=/test.txt
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "check_interval": 5000,
  "comment": "",
  "expected_response": 200,
  "host": "example.com",
  "http_version": "1.1",
  "initial": 2,
  "method": "HEAD",
  "name": "example-healthcheck",
  "path": "/test.txt",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "threshold": 3,
  "timeout": 500,
  "version": 1,
  "window": 5
}
PUT /service/service_id/version/version/healthcheck/old_name

Update the healthcheck for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the healthcheck object (used to select the correct healthcheck object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/healthcheck/example-healthcheck HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencode
Accept: application/json
name=updated-healthcheck
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "check_interval": 5000,
  "comment": "",
  "expected_response": 200,
  "host": "example.com",
  "http_version": "1.1",
  "initial": 2,
  "method": "HEAD",
  "name": "updated-healthcheck",
  "path": "/test.txt",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "threshold": 3,
  "timeout": 500,
  "version": 1,
  "window": 5
}
DELETE /service/service_id/version/version/healthcheck/name

Delete the healthcheck for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/healthcheck/test-healthcheck HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Request Settings

Settings used to customize Fastly's request handling. When used with Conditions the Request Settings object allows you to fine tune how specific types of requests are handled.

Fields

field type description
action string

Allows you to terminate request handling and immediately perform an action. When set it can be lookup or pass (ignore the cache completely).

bypass_busy_wait boolean

Disable collapsed forwarding, so you don't wait for other objects to origin.

default_host string

Sets the host header.

force_miss boolean

Allows you to force a cache miss for the request. Replaces the item in the cache if the content is cacheable.

force_ssl boolean

Forces the request use SSL (redirects a non-SSL to SSL).

geo_headers boolean

Injects Fastly-Geo-Country, Fastly-Geo-City, and Fastly-Geo-Region into the request headers.

hash_keys string

Comma separated list of varnish request object fields that should be in the hash key.

max_stale_age integer

How old an object is allowed to be to serve stale-if-error or stale-while-revalidate.

name string

Name for the request settings.

request_condition string

Name of condition object used to test whether or not these settings should be used.

service_id string

The alphanumeric string identifying a service.

timer_support boolean

Injects the X-Timer info into the request for viewing origin fetch durations.

version integer

The current version of a service.

xff string

Short for X-Forwarded-For, should be clear, leave, append, append_all, or overwrite.

Actions

GET /service/service_id/version/version/request_settings

Returns a list of all Request Settings objects for the given service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/request_settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "action": "lookup",
    "bypass_busy_wait": "0",
    "default_host": null,
    "force_miss": "0",
    "force_ssl": "1",
    "geo_headers": "1",
    "hash_keys": "null",
    "max_stale_age": "60",
    "name": "testrequest",
    "request_condition": "",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "timer_support": "0",
    "version": "1",
    "xff": "append"
  }
]
GET /service/service_id/version/version/request_settings/name

Gets the specified Request Settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/request_settings/testrequest HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "lookup",
  "bypass_busy_wait": "0",
  "default_host": null,
  "force_miss": "0",
  "force_ssl": "1",
  "geo_headers": "1",
  "hash_keys": "null",
  "max_stale_age": "60",
  "name": "testrequest",
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "timer_support": "0",
  "version": "1",
  "xff": "append"
}
POST /service/service_id/version/version/request_settings

Creates a new Request Settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/request_settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
hash_keys=null&action=lookup&xff=append&force_miss=0&timer_support=0&force_ssl=1&geo_headers=1&name=testrequest&bypass_busy_wait=0&max_stale_age=60
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "lookup",
  "bypass_busy_wait": 0,
  "default_host": null,
  "force_miss": 0,
  "force_ssl": 1,
  "geo_headers": 1,
  "hash_keys": "null",
  "max_stale_age": "60",
  "name": "testrequest",
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "timer_support": 0,
  "version": "1",
  "xff": "append"
}
PUT /service/service_id/version/version/request_settings/old_name

Updates the specified Request Settings object.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the Request Settings object (used to select the correct Request Settings object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/request_settings/testrequest HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
hash_keys=null&action=lookup&xff=append&force_miss=0&timer_support=0&force_ssl=1&geo_headers=1&name=updated-testrequest&bypass_busy_wait=0&max_stale_age=60
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "action": "lookup",
  "bypass_busy_wait": 0,
  "default_host": null,
  "force_miss": 0,
  "force_ssl": 1,
  "geo_headers": 1,
  "hash_keys": "null",
  "max_stale_age": "60",
  "name": "updated-testrequest",
  "request_condition": "",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "timer_support": 0,
  "version": "1",
  "xff": "append"
}
DELETE /service/service_id/version/version/request_settings/name

Removes the specified Request Settings object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/request_settings/testrequest HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Response Object

Allows you to create synthetic responses that exist entirely on the varnish machine. Useful for creating error or maintenance pages that exists outside the scope of your datacenter. Best when used with Condition objects.

Fields

field type description
cache_condition string

Name of the condition checked after we have retrieved an object. If the condition passes then deliver this Request Object instead.

content string

The content to deliver for the response object, can be empty.

content_type string

The MIME type of the content, can be empty.

name string

Name that identifies the Response Object.

status string

The HTTP Status Code, defaults to 200.

response string

The HTTP Response, defaults to "Ok"

request_condition string

Name of the condition to be checked during the request phase. If the condition passes then this object will be delivered.

service_id string

The alphanumeric string identifying a service.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/response_object

Returns all Response Objects for the specified service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/response_object HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "cache_condition": "",
    "content": "this message means all is okay",
    "content_type": "text/plain",
    "name": "testresponse",
    "request_condition": "",
    "response": "Ok",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "status": "200",
    "version": "1"
  }
]
GET /service/service_id/version/version/response_object/name

Gets the specified Response Object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/response_object/testresponse HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content": "this message means all is okay",
  "content_type": "text/plain",
  "name": "testresponse",
  "request_condition": "",
  "response": "Ok",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "status": "200",
  "version": "1"
}
POST /service/service_id/version/version/response_object

Creates a new Response Object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/response_object HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
status=200&response=Ok&name=testresponse&content=this+message+means+all+is+okay
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content": "this message means all is okay",
  "content_type": null,
  "name": "testresponse1",
  "request_condition": "",
  "response": "Ok",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "status": "200",
  "version": "1"
}
PUT /service/service_id/version/version/response_object/old_name

Updates the specified Response Object.

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the Response object (used to select the correct Response object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/response_object/testresponse HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
status=200&response=Ok&name=testresponse&content=THIS+MESSAGE+MEANS+ALL+IS+OKAY
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "cache_condition": "",
  "content": "THIS MESSAGE MEANS ALL IS OKAY",
  "content_type": null,
  "name": "testresponse",
  "request_condition": "",
  "response": "Ok",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "status": "200",
  "version": "1"
}
DELETE /service/service_id/version/version/response_object/name

Deletes the specified Response Object.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/response_object/testresponse HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Service

A Service represents the configuration for a website, app, API, or anything else to be served through Fastly. A Service can have many Versions, through which Backends, Domains, and more can be configured.

Fields

field type description
active boolean

Indicates if the version is active for this service.

active_version array

List of configuration for active version of a service.

backends array

List of backend associated to this service.

cache_settings array

List of cache_settings associated to this service.

comment string

Description field.

conditions array

List of conditions associated to this service.

customer_id string

Which customer this service belongs to.

deployed boolean

Indicates if the version has been deployed.

directors array

List of directors associated to this service.

domain array

List of domains associated to this service.

gzips array

List of gzip rules associated to this service.

headers array

List of headers associated to this service.

healthchecks array

List of healthchecks associated to this service.

locked boolean

Indicates if this version is locked and uneditable.

logging_syslog array

List of logging services associated to this service.

number integer

Current version number of this service.

request_settings array

List of request_settings for this service.

response_objects array

List of response_objects for this service.

name string

The name of this service.

publish_key string

What key to use for the publish streams.

service_id string

The alphanumeric string identifying a service.

settings array

List of default settings for this service.

staging boolean

Unused at this time.

testing boolean

Unused at this time.

vcls array

List of VCL for this service.

version integer

The current version of this service.

versions array

A list of versions associated with this service.

wordpress array

A list of wordpress rules with this service.

Actions

GET /service

List Services

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "comment": "",
    "customer_id": "x4xCwxxJxGCx123Rx5xTx",
    "id": "SU1Z0isxPaozGVKXdv0eY",
    "name": "test service",
    "version": 1,
    "versions": [
      {
        "active": null,
        "comment": "",
        "created_at": "2016-04-27T19:40:49",
        "deleted_at": null,
        "deployed": null,
        "locked": "1",
        "number": "1",
        "service": "SU1Z0isxPaozGVKXdv0eY",
        "service_id": "SU1Z0isxPaozGVKXdv0eY",
        "staging": null,
        "testing": null,
        "updated_at": "2016-05-09T16:27:00"
      }
    ]
  }
]
GET /service/id/details

List detailed information on a specified service

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/details HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "acls": [],
  "active_version": {
    "active": true,
    "backends": [],
    "cache_settings": [],
    "comment": "",
    "conditions": [],
    "deployed": true,
    "dictionaries": [],
    "directors": [],
    "domains": [],
    "gzips": [],
    "headers": [],
    "healthchecks": [],
    "locked": true,
    "number": 1,
    "request_settings": [],
    "response_objects": [],
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "settings": {
        "general.default_host": "",
        "general.default_pci": 0,
        "general.default_ttl": 3600
    },
    "staging": true,
    "testing": true,
    "vcls": [],
    "wordpress": []
  },
  "comment": "",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "test service"
}
GET /service/search

Get a specific service by name

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/search?name=test-service HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "test-service",
  "versions": [
    {
      "active": "1",
      "backend": [],
      "cache_settings": [],
      "comment": "",
      "condition": [],
      "created": "2016-04-27 19:40:52",
      "deleted": "0000-00-00 00:00:00",
      "deployed": "1",
      "director": [],
      "domain": [],
      "gzip": [],
      "header": [],
      "healthcheck": [],
      "locked": "1",
      "logging_syslog": [],
      "number": "2",
      "request_settings": [],
      "response_object": [],
      "service_id": "SU1Z0isxPaozGVKXdv0eY",
      "settings": {
          "general.default_host": "",
          "general.default_pci": 0,
          "general.default_ttl": 3600
      },
      "staging": "1",
      "testing": "1",
      "updated": "2016-05-09 16:28:18",
      "vcl": [],
      "waf": [],
      "wordpress": []
    }
  ]
}
GET /service/id

Get a specific service by id

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "created_at": "2016-04-27T19:40:49+00:00",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "deleted_at": null,
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "test-service",
  "publish_key": "3c18bd0f5ada8f0cf54724d86c514a8eac4c9b75",
  "updated_at": "2016-04-27T19:40:49+00:00",
  "versions": [
    {
      "active": null,
      "backend": 1,
      "comment": "",
      "created_at": "2016-04-27T19:40:49",
      "deleted_at": null,
      "deployed": null,
      "locked": "1",
      "number": "1",
      "service": "SU1Z0isxPaozGVKXdv0eY",
      "service_id": "SU1Z0isxPaozGVKXdv0eY",
      "staging": null,
      "testing": null,
      "updated_at": "2016-05-09T16:27:00"
    }
  ]
}
GET /service/id/domain

List the domains within a service

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/domain HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "comment": "",
    "locked": true,
    "name": "www.example.com",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": 1
  }
]
POST /service

Create a service

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=test-service
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "created_at": "2016-05-09T20:46:46+00:00",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "deleted_at": null,
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "test-service",
  "publish_key": "6c8a846405a7293dd13c0c7291ebf011fa4354e3",
  "updated_at": "2016-05-09T20:46:46+00:00",
  "versions": [
    {
      "active": null,
      "backend": 0,
      "comment": "",
      "created_at": "2016-05-09T20:46:46",
      "deleted_at": null,
      "deployed": null,
      "locked": "0",
      "number": "1",
      "service": "SU1Z0isxPaozGVKXdv0eY",
      "service_id": "SU1Z0isxPaozGVKXdv0eY",
      "staging": null,
      "testing": null,
      "updated_at": "2016-05-09T20:46:46"
    }
  ]
}
PUT /service/id

Update a service

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=updated-service-name
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "comment": "",
  "created_at": "2016-05-09T20:46:46+00:00",
  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
  "deleted_at": null,
  "id": "SU1Z0isxPaozGVKXdv0eY",
  "name": "updated-test-service",
  "publish_key": "6c8a846405a7293dd13c0c7291ebf011fa4354e3",
  "updated_at": "2016-05-09T20:46:46+00:00",
  "versions": [
    {
      "active": null,
      "backend": 0,
      "comment": "",
      "created_at": "2016-05-09T20:46:46",
      "deleted_at": null,
      "deployed": null,
      "locked": "0",
      "number": "1",
      "service": "SU1Z0isxPaozGVKXdv0eY",
      "service_id": "SU1Z0isxPaozGVKXdv0eY",
      "staging": null,
      "testing": null,
      "updated_at": "2016-05-09T20:46:46"
    }
  ]
}
DELETE /service/id

Delete a service

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Settings

Handles default settings for a particular version of a service.

Fields

field type description
general.default_host string

The default host name for the version.

general.default_ttl integer

The default Time-to-live (TTL) for the version.

service_id string

The alphanumeric string identifying a service.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/settings

Get the settings for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "general.default_host": "",
  "general.default_ttl": 3600,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
PUT /service/service_id/version/version/settings

Update the settings for a particular service and version.
NOTE: If you override TTLs with custom VCL, any general.default_ttl value will not be honored and the expected behavior may change.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/settings HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
general.default_ttl=4242&general.default_host=www.example.com
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "general.default_host": "www.example.com",
  "general.default_ttl": 7200,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}

Stats

Stats give you information on the usage and performance of your Service. They can be request by Service and over a particular time span. Stats are broken down per datacenter, giving you information on how your Services are being used across the world. There is now a more flexible, and fully featured Stats API available

Fields

field type description
start_time integer

Epoch timestamp for period request

end_time integer

Epoch timestamp for period request

year integer

Summarize a specific Y/M (requires month)

month integer

Summarize a specific month (requires year)

Actions

GET /service/service_id/stats/summary

Get the stats from a service for a block of time. This lists all stats by PoP location, starting with AMS. This call requires parameters to select block of time to query. Use either a timestamp range (using start_time and end_time) or a specified month/year combo (using month and year)

Authentication

API token.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/stats/summary?year=2013&month=7 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "stats": {
    "AMS": {
      "attack_block": 0,
      "attack_body_size": 0,
      "attack_header_size": 0,
      "attack_synth": 0,
      "blacklist": 0,
      "body_size": 47156,
      "header_size": 2548,
      "hits": 0,
      "hits_time": 0.0,
      "http2": 0,
      "imgopto": 0,
      "ipv6": 0,
      "log": 0,
      "miss": 0,
      "miss_time": 0.0,
      "orig_req_body_size": 0,
      "orig_req_header_size": 0,
      "orig_resp_body_size": 0,
      "orig_resp_header_size": 0,
      "otfp": 0,
      "pass": 3,
      "pci": 0,
      "pipe": 0,
      "requests": 3,
      "shield": 0,
      "status_1xx": 0,
      "status_200": 3,
      "status_204": 0,
      "status_2xx": 3,
      "status_301": 0,
      "status_302": 0,
      "status_304": 0,
      "status_3xx": 0,
      "status_4xx": 0,
      "status_503": 0,
      "status_5xx": 0,
      "synth": 0,
      "tls": 0,
      "uncacheable": 0,
      "video": 0
    },
    "additional_data_centers": {}
  }
}
GET /service/service_id/stats/type

Get the stats from a service. This call is deprecated. Please use the summary call above. If type is either of "all" or "minutely", you must use specify a block of time using the fields above

Authentication

API token.

Parameters
parameter type description
type string

Granularity of stats requested. one of: all, minutely, hourly, daily

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/stats/daily HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "stats": {
    "AMS": {
      "attack_block": 0,
      "attack_body_size": 0,
      "attack_header_size": 0,
      "attack_synth": 0,
      "blacklist": 0,
      "body_size": 47156,
      "header_size": 2548,
      "hits": 0,
      "hits_time": 0.0,
      "http2": 0,
      "imgopto": 0,
      "ipv6": 0,
      "log": 0,
      "miss": 0,
      "miss_time": 0.0,
      "orig_req_body_size": 0,
      "orig_req_header_size": 0,
      "orig_resp_body_size": 0,
      "orig_resp_header_size": 0,
      "otfp": 0,
      "pass": 3,
      "pci": 0,
      "pipe": 0,
      "requests": 3,
      "shield": 0,
      "status_1xx": 0,
      "status_200": 3,
      "status_204": 0,
      "status_2xx": 3,
      "status_301": 0,
      "status_302": 0,
      "status_304": 0,
      "status_3xx": 0,
      "status_4xx": 0,
      "status_503": 0,
      "status_5xx": 0,
      "synth": 0,
      "tls": 0,
      "uncacheable": 0,
      "video": 0
    },
    "additional_data_centers": {}
  }
}

VCL

A VCL is a Varnish configuration file used to customize the configuration for a Service.

Fields

field type description
content string

The VCL code to be included.

main boolean

Set to true when this is the main VCL, otherwise false.

name string

The name of this VCL.

service_id string

The alphanumeric string identifying a service.

version integer

The current version of a service.

Actions

GET /service/service_id/version/version/vcl

List the uploaded VCLs for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9092\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
    "main": false,
    "name": "test-vcl",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": 1
  }
]
GET /service/service_id/version/version/boilerplate

Return boilerplate VCL with the service's TTL from the settings.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/boilerplate HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: text/html;charset=utf8
*VCL*
GET /service/service_id/version/version/vcl/name

Get the uploaded VCL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
no_content boolean

Omit VCL content (default 0)

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9092\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
  "main": false,
  "name": "test-vcl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
GET /service/service_id/version/version/vcl/name/content

Get the uploaded VCL for a particular service and version with HTML syntax highlighting Include line numbers by sending lineno=true as a request parameter

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl/content HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
    "content": "<div class=\"highlight\"><pre>  <span class=\"n\">backend</span> <span class=\"n\">default</span> <span class=\"p\">{</span>\n    <span class=\"o\">.</span><span class=\"n\">host</span> <span class=\"o\">=</span> <span class=\"s\">&quot;127.0.0.1&quot;</span><span class=\"p\">;</span>\n    <span class=\"o\">.</span><span class=\"n\">port</span> <span class=\"o\">=</span> <span class=\"s\">&quot;80&quot;</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n  \n  <span class=\"k\">sub </span><span class=\"nf\">vcl_recv</span> <span class=\"p\">{</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">backend</span> <span class=\"o\">=</span> <span class=\"n\">default</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n  \n  <span class=\"k\">sub </span><span class=\"nf\">vcl_hash</span> <span class=\"p\">{</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">url</span><span class=\"p\">;</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">http</span><span class=\"o\">.</span><span class=\"n\">host</span><span class=\"p\">;</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"s\">&quot;0&quot;</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n</pre></div>\n"
}
GET /service/service_id/version/version/vcl/name/download

Download the specified VCL

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl/download HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Response Example
HTTP/1.1 200 OK
Content-Type: text/plain
*VCL*
GET /service/service_id/version/version/generated_vcl

Display the generated VCL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/generated_vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9093\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
  "main": false,
  "name": "c46e2d848a9d3d9e86b85bd1b71616b7",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1"
}
GET /service/service_id/version/version/generated_vcl/content

Display the content of generated VCL with HTML syntax highlighting Include line numbers by sending lineno=true as a request parameter

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/generated_vcl/content HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "<div class=\"highlight\"><pre>  <span class=\"n\">backend</span> <span class=\"n\">default</span> <span class=\"p\">{</span>\n    <span class=\"o\">.</span><span class=\"n\">host</span> <span class=\"o\">=</span> <span class=\"s\">&quot;127.0.0.1&quot;</span><span class=\"p\">;</span>\n    <span class=\"o\">.</span><span class=\"n\">port</span> <span class=\"o\">=</span> <span class=\"s\">&quot;80&quot;</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n  \n  <span class=\"k\">sub </span><span class=\"nf\">vcl_recv</span> <span class=\"p\">{</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">backend</span> <span class=\"o\">=</span> <span class=\"n\">default</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n  \n  <span class=\"k\">sub </span><span class=\"nf\">vcl_hash</span> <span class=\"p\">{</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">url</span><span class=\"p\">;</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">http</span><span class=\"o\">.</span><span class=\"n\">host</span><span class=\"p\">;</span>\n      <span class=\"n\">set</span> <span class=\"n\">req</span><span class=\"o\">.</span><span class=\"n\">hash</span> <span class=\"o\">+=</span> <span class=\"s\">&quot;0&quot;</span><span class=\"p\">;</span>\n  <span class=\"p\">}</span>\n</pre></div>\n"
}
POST /service/service_id/version/version/vcl

Upload a VCL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=test-vcl&content=<URL-encoded VCL code>
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9092\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
  "main": false,
  "name": "test-vcl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
PUT /service/service_id/version/version/vcl/name/main

Set the specified VCL as the main

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl/main HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9092\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
  "main": true,
  "name": "test-vcl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
PUT /service/service_id/version/version/vcl/old_name

Update the uploaded VCL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Parameters
parameter type description
old_name string

Old name of the VCL object (used to select the correct VCL object if the name has been changed).

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
content=<URL-encoded VCL code>
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "content": "backend default {\n  .host = \"127.0.0.1\";\n  .port = \"9092\";\n}\n\nsub vcl_recv {\n    set req.backend = default;\n}\n\nsub vcl_hash {\n    set req.hash += req.url;\n    set req.hash += req.http.host;\n    set req.hash += \"0\";\n}",
  "main": false,
  "name": "test-vcl",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": 1
}
DELETE /service/service_id/version/version/vcl/name

Delete the uploaded VCL for a particular service and version

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/vcl/test-vcl HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

VCL Snippets

VCL Snippets are blocks of VCL logic inserted into your service's configuration that don't require custom VCL.

Fields

field type description
name string

The name for the snippet.

dynamic integer

Sets the snippet version to regular (0) or dynamic (1).

type string

The location in generated VCL where the snippet should be placed.

init -

Place the snippet above all subroutines.

recv -

Place the snippet within the vcl_recv subroutine but below the boilerplate VCL and above any objects.

hit -

Place the snippet within the vcl_hit subroutine.

miss -

Place the snippet within the vcl_miss subroutine.

pass -

Place the snippet within the vcl_pass subroutine.

fetch -

Place the snippet within the vcl_fetch subroutine.

error -

Place the snippet within the vcl_error subroutine.

deliver -

Place the snippet within the vcl_deliver subroutine.

log -

Place the snippet within the vcl_log subroutine.

none -

Don't render the snippet in VCL so it can be manually included in custom VCL.

content string

The VCL code that specifies exactly what the snippet does.

priority integer

Priority determines the ordering for multiple snippets. Lower numbers execute first.

Actions

GET /service/service_id/snippet/snippet_id

Get a single dynamic snippet for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/snippet/SU1Z0isxPaozGVKXdv0eY HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "snippet_id": "3SjAjcCc6e5gXkxBc44fIB",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "content": "{}",
  "created_at": "2016-08-15T09:37:10+00:00",
  "updated_at": "2016-08-15T09:37:10+00:00"
}
GET /service/service_id/version/version/snippet

List all snippets for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/snippet HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "id": "62Yd1WfiCBPENLloXfXmlO",
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "version": "1",
    "name": "my_snippet",
    "priority": "100",
    "dynamic": "1",
    "type": "hit",
    "content": null,
    "created_at": "2016-08-15T09:37:10+00:00",
    "updated_at": "2016-08-15T09:37:10+00:00",
    "deleted_at": null
  }
]
GET /service/service_id/version/version/snippet/name

Get a single snippet for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/snippet/my_snippet HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "62Yd1WfiCBPENLloXfXmlO",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1",
  "name": "my_snippet",
  "priority": "100",
  "dynamic": "1",
  "type": "hit",
  "content":null,
  "created_at": "2016-08-15T09:37:10+00:00",
  "updated_at": "2016-08-15T09:37:10+00:00",
  "deleted_at": null
}
POST /service/service_id/version/version/snippet

Create a snippet for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version/1/snippet HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=my_snippet&dynamic=1&type=hit&content={}
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "62Yd1WfiCBPENLloXfXmlO",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1",
  "name": "my_snippet",
  "priority": "100",
  "dynamic": "1",
  "type": "hit",
  "content":null,
  "created_at": "2016-08-15T09:37:10+00:00",
  "updated_at": "2016-08-15T09:37:10+00:00",
  "deleted_at": null
}
PUT /service/service_id/snippet/snippet_id

Update a dynamic snippet for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/snippet/62Yd1WfiCBPENLloXfXmlO HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
content="backend new_backend {}"
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "snippet_id": "62Yd1WfiCBPENLloXfXmlO",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "content": "backend new_backend {}",
  "created_at": "2016-08-15T09:37:10+00:00",
  "updated_at": "2016-08-15T09:42:10+00:00"
}
PUT /service/service_id/version/version/snippet/old_name

Update a specific snippet for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/snippet/my_snippet HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
name=new_snippet_name
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "62Yd1WfiCBPENLloXfXmlO",
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "version": "1",
  "name": "new_snippet_name",
  "priority": "100",
  "dynamic": "1",
  "type": "hit",
  "content": null,
  "created_at": "2016-08-15T09:37:10+00:00",
  "updated_at": "2016-08-15T09:47:10+00:00",
  "deleted_at": null
}
DELETE /service/service_id/version/version/snippet/name

Delete a specific snippet for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
DELETE /service/SU1Z0isxPaozGVKXdv0eY/version/1/snippet/my_snippet HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}

Version

A Version represents a specific instance of the configuration for a service. A Version can be cloned, locked, activated, or deactivated.

Fields

field type description
active boolean

Whether this is the active version or not.

comment string

A comment.

created_at string

Time-stamp (GMT) when the version was created.

deleted_at string

Time-stamp (GMT) when the version was deleted.

deployed boolean

Whether or not this version is deployed.

locked boolean

Whether this version is locked or not. Objects can not be added or edited on locked versions.

number integer

The number of this version.

service_id string

The alphanumeric string identifying a service.

staging boolean

Whether or not this version is for staging.

testing boolean

Whether or not this version is for testing.

updated_at string

Time-stamp (GMT) when the version was updated.

Actions

GET /service/service_id/version

List the versions for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
[
  {
    "active": true,
    "comment": "",
    "created_at": "2016-05-01T19:40:49+00:00",
    "deleted_at": null,
    "deployed": null,
    "locked": true,
    "number": 1,
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "staging": null,
    "testing": null,
    "updated_at": "2016-05-09T16:19:09+00:00"
  }
]
GET /service/service_id/version/number

Get the version for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
    "active": true,
    "comment": "",
    "created_at": "2016-05-01T19:40:49+00:00",
    "deleted_at": null,
    "deployed": null,
    "locked": true,
    "number": 1,
    "service_id": "SU1Z0isxPaozGVKXdv0eY",
    "staging": null,
    "testing": null,
    "updated_at": "2016-05-09T16:19:09+00:00"
}
GET /service/service_id/version/number/validate

Validate the version for a particular service and version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
GET /service/SU1Z0isxPaozGVKXdv0eY/version/1/validate HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "status": "ok"
}
POST /service/service_id/version

Create a version for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
POST /service/SU1Z0isxPaozGVKXdv0eY/version HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "number":1,
  "service_id": "SU1Z0isxPaozGVKXdv0eY"
}
PUT /service/service_id/version/number

Update a particular version for a particular service.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1 HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
deployed=true&staging=true&testing=true
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "active": null,
  "comment": "",
  "created_at": "2016-05-01T19:40:51+00:00",
  "deleted_at": null,
  "deployed": true,
  "locked": false,
  "number": 1,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "staging": true,
  "testing": true,
  "updated_at": "2016-05-09T16:19:09+00:00"
}
PUT /service/service_id/version/number/activate

Activate the current version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/activate HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "active": true,
  "comment": "",
  "created_at": "2016-05-01T19:40:51+00:00",
  "deleted_at": null,
  "deployed": true,
  "locked": true,
  "number": 1,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "staging": true,
  "testing": true,
  "updated_at": "2016-05-09T16:19:09+00:00"
}
PUT /service/service_id/version/number/deactivate

Deactivate the current version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/3/deactivate HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "active": false,
  "comment": "",
  "created_at": "2016-05-01T19:40:51+00:00",
  "deleted_at": null,
  "deployed": false,
  "locked": true,
  "number": 1,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "staging": true,
  "testing": true,
  "updated_at": "2016-05-09T16:19:09+00:00"
}
PUT /service/service_id/version/number/clone

Clone the current configuration into a new version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/clone HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "active": false,
  "comment": "",
  "created_at": "2016-05-01T19:40:51+00:00",
  "deleted_at": null,
  "deployed": false,
  "locked": false,
  "number": 2,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "staging": true,
  "testing": true,
  "updated_at": "2016-05-09T16:19:09+00:00"
}
PUT /service/service_id/version/number/lock

Locks the specified version.

Authentication

API token of a user with at least Engineer permissions.

Request Example
PUT /service/SU1Z0isxPaozGVKXdv0eY/version/1/lock HTTP/1.1
Fastly-Key: YOUR_FASTLY_TOKEN
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Response Example
HTTP/1.1 200 OK
Content-Type: application/json
{
  "active": false,
  "comment": "",
  "created_at": "2016-05-01T19:40:51+00:00",
  "deleted_at": null,
  "deployed": false,
  "locked": true,
  "number": 1,
  "service_id": "SU1Z0isxPaozGVKXdv0eY",
  "staging": true,
  "testing": true,
  "updated_at": "2016-05-09T16:19:09+00:00"
}