openapi: 3.1.0 info: title: Fastly VCL Services API description: >- The Fastly VCL Services API provides programmatic access to configure Varnish Configuration Language (VCL) objects that power most Fastly services. Developers can upload custom VCL code or use the API to generate VCL through configuration objects including backends, conditions, cache settings, request settings, response objects, headers, and VCL snippets. This API is central to defining how Fastly processes, routes, and caches HTTP requests at the edge. version: '1.0' contact: name: Fastly Support url: https://support.fastly.com termsOfService: https://www.fastly.com/terms externalDocs: description: Fastly VCL Services API Documentation url: https://www.fastly.com/documentation/reference/api/vcl-services/ servers: - url: https://api.fastly.com description: Fastly API Production Server tags: - name: Backend description: >- Operations for managing backends (origin servers) that a Fastly service routes requests to. - name: Cache Settings description: >- Operations for managing cache settings that control cache lifetimes and behavior at the edge. - name: Condition description: >- Operations for managing conditions that control when configuration objects are applied during request processing. - name: Custom VCL description: >- Operations for uploading and managing full custom VCL files. - name: Header description: >- Operations for managing header manipulation rules that add, modify, or remove HTTP headers during request and response processing. - name: Request Settings description: >- Operations for managing request settings that modify inbound requests at the edge. - name: Response Object description: >- Operations for managing synthetic response objects that can be served directly from the edge without contacting an origin. - name: VCL Snippet description: >- Operations for managing VCL snippets, which are small pieces of VCL code that can be inserted into specific subroutines. security: - apiKeyAuth: [] paths: /service/{service_id}/version/{version_id}/backend: get: operationId: listBackends summary: List backends description: >- Retrieves a list of all backends configured for a specific version of a Fastly service. tags: - Backend parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of backends. content: application/json: schema: type: array items: $ref: '#/components/schemas/Backend' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createBackend summary: Create a backend description: >- Creates a new backend for a specific version of a Fastly service. Backends define the origin servers that Fastly routes requests to. tags: - Backend parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Backend' responses: '200': description: Successfully created the backend. content: application/json: schema: $ref: '#/components/schemas/Backend' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/backend/{backend_name}: get: operationId: getBackend summary: Get a backend description: >- Retrieves the details of a specific backend for a version of a Fastly service. tags: - Backend parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' - $ref: '#/components/parameters/backendName' responses: '200': description: Successfully retrieved the backend. content: application/json: schema: $ref: '#/components/schemas/Backend' '401': description: Unauthorized. The API token is missing or invalid. '404': description: Backend not found. put: operationId: updateBackend summary: Update a backend description: >- Updates a specific backend for a version of a Fastly service. tags: - Backend parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' - $ref: '#/components/parameters/backendName' requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Backend' responses: '200': description: Successfully updated the backend. content: application/json: schema: $ref: '#/components/schemas/Backend' '401': description: Unauthorized. The API token is missing or invalid. '404': description: Backend not found. delete: operationId: deleteBackend summary: Delete a backend description: >- Deletes a specific backend from a version of a Fastly service. tags: - Backend parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' - $ref: '#/components/parameters/backendName' responses: '200': description: Successfully deleted the backend. content: application/json: schema: type: object properties: status: type: string description: >- Confirmation status of the deletion. '401': description: Unauthorized. The API token is missing or invalid. '404': description: Backend not found. /service/{service_id}/version/{version_id}/condition: get: operationId: listConditions summary: List conditions description: >- Retrieves a list of all conditions configured for a specific version of a Fastly service. tags: - Condition parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of conditions. content: application/json: schema: type: array items: $ref: '#/components/schemas/Condition' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createCondition summary: Create a condition description: >- Creates a new condition for a specific version of a Fastly service. Conditions use VCL syntax to define when configuration objects should be applied during request processing. tags: - Condition parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Condition' responses: '200': description: Successfully created the condition. content: application/json: schema: $ref: '#/components/schemas/Condition' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/cache_settings: get: operationId: listCacheSettings summary: List cache settings description: >- Retrieves a list of all cache settings configured for a specific version of a Fastly service. tags: - Cache Settings parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of cache settings. content: application/json: schema: type: array items: $ref: '#/components/schemas/CacheSettings' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createCacheSettings summary: Create cache settings description: >- Creates new cache settings for a specific version of a Fastly service. Cache settings configure cache lifetime for objects stored in the Fastly cache, overriding cache freshness information from HTTP headers. tags: - Cache Settings parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CacheSettings' responses: '200': description: Successfully created the cache settings. content: application/json: schema: $ref: '#/components/schemas/CacheSettings' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/header: get: operationId: listHeaders summary: List header objects description: >- Retrieves a list of all header manipulation rules configured for a specific version of a Fastly service. tags: - Header parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of headers. content: application/json: schema: type: array items: $ref: '#/components/schemas/Header' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createHeader summary: Create a header object description: >- Creates a new header manipulation rule for a specific version of a Fastly service. Header objects add, modify, or remove HTTP headers during request and response processing. tags: - Header parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Header' responses: '200': description: Successfully created the header object. content: application/json: schema: $ref: '#/components/schemas/Header' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/snippet: get: operationId: listSnippets summary: List VCL snippets description: >- Retrieves a list of all VCL snippets configured for a specific version of a Fastly service. tags: - VCL Snippet parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of VCL snippets. content: application/json: schema: type: array items: $ref: '#/components/schemas/Snippet' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createSnippet summary: Create a VCL snippet description: >- Creates a new VCL snippet for a specific version of a Fastly service. Snippets are small pieces of VCL code that can be inserted into specific VCL subroutines. tags: - VCL Snippet parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Snippet' responses: '200': description: Successfully created the VCL snippet. content: application/json: schema: $ref: '#/components/schemas/Snippet' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/vcl: get: operationId: listCustomVcl summary: List custom VCL files description: >- Retrieves a list of all custom VCL files uploaded for a specific version of a Fastly service. tags: - Custom VCL parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of custom VCL files. content: application/json: schema: type: array items: $ref: '#/components/schemas/CustomVcl' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createCustomVcl summary: Upload custom VCL description: >- Uploads a full custom VCL file for a specific version of a Fastly service. tags: - Custom VCL parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CustomVcl' responses: '200': description: Successfully uploaded the custom VCL file. content: application/json: schema: $ref: '#/components/schemas/CustomVcl' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/request_settings: get: operationId: listRequestSettings summary: List request settings description: >- Retrieves a list of all request settings configured for a specific version of a Fastly service. tags: - Request Settings parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of request settings. content: application/json: schema: type: array items: $ref: '#/components/schemas/RequestSettings' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createRequestSettings summary: Create request settings description: >- Creates new request settings for a specific version of a Fastly service. Request settings modify inbound requests at the edge before they are processed or forwarded to origin. tags: - Request Settings parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/RequestSettings' responses: '200': description: Successfully created the request settings. content: application/json: schema: $ref: '#/components/schemas/RequestSettings' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. /service/{service_id}/version/{version_id}/response_object: get: operationId: listResponseObjects summary: List response objects description: >- Retrieves a list of all response objects configured for a specific version of a Fastly service. tags: - Response Object parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' responses: '200': description: Successfully retrieved the list of response objects. content: application/json: schema: type: array items: $ref: '#/components/schemas/ResponseObject' '401': description: Unauthorized. The API token is missing or invalid. post: operationId: createResponseObject summary: Create a response object description: >- Creates a new response object for a specific version of a Fastly service. Response objects allow serving synthetic responses directly from the edge without contacting an origin server. tags: - Response Object parameters: - $ref: '#/components/parameters/serviceId' - $ref: '#/components/parameters/versionId' requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/ResponseObject' responses: '200': description: Successfully created the response object. content: application/json: schema: $ref: '#/components/schemas/ResponseObject' '400': description: Bad request. Missing or invalid parameters. '401': description: Unauthorized. The API token is missing or invalid. components: securitySchemes: apiKeyAuth: type: apiKey in: header name: Fastly-Key description: >- API token used to authenticate requests to the Fastly API. parameters: serviceId: name: service_id in: path required: true description: >- The alphanumeric string identifying the Fastly service. schema: type: string versionId: name: version_id in: path required: true description: >- The integer identifying the service version. schema: type: integer backendName: name: backend_name in: path required: true description: >- The name of the backend. schema: type: string schemas: Backend: type: object description: >- A backend represents an origin server that a Fastly service routes requests to for content that is not cached at the edge. properties: name: type: string description: >- The name of the backend. address: type: string description: >- The hostname or IPv4 address of the backend. port: type: integer description: >- The port number on the backend. default: 80 use_ssl: type: boolean description: >- Whether to use SSL/TLS to connect to the backend. ssl_hostname: type: string description: >- The hostname to verify for SSL certificate validation. ssl_cert_hostname: type: string description: >- The hostname to use when checking the backend certificate. ssl_sni_hostname: type: string description: >- The SNI hostname to use for the backend connection. shield: type: string description: >- The data center to use as a shield POP. weight: type: integer description: >- The weight assigned to this backend for load balancing. minimum: 1 maximum: 100 connect_timeout: type: integer description: >- Maximum duration in milliseconds to wait for a connection. first_byte_timeout: type: integer description: >- Maximum duration in milliseconds to wait for the first byte. between_bytes_timeout: type: integer description: >- Maximum duration in milliseconds to wait between bytes. max_conn: type: integer description: >- Maximum number of connections to the backend. healthcheck: type: string description: >- The name of the healthcheck to use with the backend. auto_loadbalance: type: boolean description: >- Whether to auto-load-balance this backend. request_condition: type: string description: >- The name of a condition to apply to route requests to this backend. comment: type: string description: >- A freeform descriptive note about the backend. Condition: type: object description: >- A condition uses VCL syntax to define when a configuration object should be applied during request processing. properties: name: type: string description: >- The name of the condition. statement: type: string description: >- A VCL conditional expression that defines when the condition evaluates to true. type: type: string description: >- The type of condition, determining when it is evaluated. enum: - REQUEST - CACHE - RESPONSE - PREFETCH priority: type: integer description: >- The priority of the condition, with lower numbers evaluated first. default: 10 comment: type: string description: >- A freeform descriptive note about the condition. CacheSettings: type: object description: >- Cache settings configure cache lifetime for objects stored in the Fastly cache, overriding cache freshness information from HTTP response headers. properties: name: type: string description: >- The name of the cache settings rule. action: type: string description: >- The action to take when the cache settings are applied. enum: - pass - cache - restart - deliver ttl: type: integer description: >- The maximum time in seconds that the object should be cached. stale_ttl: type: integer description: >- The maximum time in seconds that a stale object can be served. cache_condition: type: string description: >- The name of the condition that triggers these cache settings. RequestSettings: type: object description: >- Request settings modify inbound requests at the edge before they are processed or forwarded to origin servers. properties: name: type: string description: >- The name of the request settings rule. action: type: string description: >- The action to take when request settings are applied. enum: - lookup - pass force_miss: type: boolean description: >- Whether to force a cache miss for matching requests. force_ssl: type: boolean description: >- Whether to force SSL for matching requests. bypass_busy_wait: type: boolean description: >- Whether to disable collapsed forwarding for matching requests. max_stale_age: type: integer description: >- The maximum stale age in seconds. hash_keys: type: string description: >- A list of items to use as the cache hash key. xff: type: string description: >- How to handle the X-Forwarded-For header. enum: - clear - leave - append - append_all - overwrite timer_support: type: boolean description: >- Whether to inject Fastly-specific timing headers. geo_headers: type: boolean description: >- Whether to add geographic headers based on client IP. default_host: type: string description: >- Sets the host header sent to the backend. request_condition: type: string description: >- The name of the condition that triggers these request settings. ResponseObject: type: object description: >- A response object allows serving synthetic responses directly from the edge without contacting an origin server. properties: name: type: string description: >- The name of the response object. status: type: integer description: >- The HTTP status code for the synthetic response. minimum: 100 maximum: 599 response: type: string description: >- The HTTP status text for the synthetic response. content: type: string description: >- The content body to return in the synthetic response. content_type: type: string description: >- The MIME type of the content body. request_condition: type: string description: >- The name of the condition that triggers the response object. cache_condition: type: string description: >- The name of the condition that determines caching. Header: type: object description: >- A header object manipulates HTTP headers during request and response processing at the edge. properties: name: type: string description: >- The name of the header rule. action: type: string description: >- The action to take on the header. enum: - set - append - delete - regex - regex_repeat type: type: string description: >- The type of header manipulation. enum: - request - fetch - cache - response dst: type: string description: >- The name of the header to modify. src: type: string description: >- A variable expression used to derive the value. regex: type: string description: >- A regular expression used for regex-based actions. substitution: type: string description: >- The substitution string for regex-based actions. priority: type: integer description: >- The priority of the header rule. default: 100 ignore_if_set: type: boolean description: >- Whether to skip the header rule if the header is already set. request_condition: type: string description: >- The name of the condition that triggers the header rule. response_condition: type: string description: >- The name of the condition that triggers the header rule on responses. cache_condition: type: string description: >- The name of the condition that triggers the header rule on cache. Snippet: type: object description: >- A VCL snippet is a small piece of VCL code that can be inserted into a specific VCL subroutine without uploading a full custom VCL file. properties: name: type: string description: >- The name of the VCL snippet. content: type: string description: >- The VCL code for the snippet. type: type: string description: >- The VCL subroutine to insert the snippet into. enum: - init - recv - hash - hit - miss - pass - fetch - error - deliver - log - none dynamic: type: integer description: >- Whether this snippet is dynamic (0 = versioned, 1 = dynamic). enum: - 0 - 1 priority: type: integer description: >- The priority of the snippet, determining its order of execution. default: 100 CustomVcl: type: object description: >- A full custom VCL file uploaded for a service version. properties: name: type: string description: >- The name of the custom VCL file. content: type: string description: >- The VCL source code. main: type: boolean description: >- Whether this is the main VCL file for the service version.