Fastly Services API

openapi: 3.1.0
info:
  title: Fastly Services API
  description: >-
    The Fastly Services API allows developers to create, configure, and manage
    Fastly CDN services and their versions programmatically. Services are the
    primary organizational unit in Fastly, representing a configuration that
    maps domains to backends. The API supports creating service versions,
    activating and deactivating configurations, cloning versions, and managing
    the complete lifecycle of a CDN service deployment.
  version: '1.0'
  contact:
    name: Fastly Support
    url: https://support.fastly.com
  termsOfService: https://www.fastly.com/terms
externalDocs:
  description: Fastly Services API Documentation
  url: https://www.fastly.com/documentation/reference/api/services/
servers:
  - url: https://api.fastly.com
    description: Fastly API Production Server
tags:
  - name: Service Version
    description: >-
      Operations for managing versions of a Fastly service. Each change to a
      service configuration creates a new version that can be activated or
      deactivated independently.
security:
  - apiKeyAuth: []
paths:
  /service:
    get:
      operationId: listServices
      summary: List services
      description: >-
        Retrieves a list of all services associated with the authenticated
        account. Returns basic information about each service including its
        name, ID, and current active version.
      tags: []
      parameters:
        - $ref: '#/components/parameters/pageNumber'
        - $ref: '#/components/parameters/perPage'
        - name: sort
          in: query
          description: >-
            The field to sort results by.
          schema:
            type: string
            enum:
              - created
              - name
              - updated
        - name: direction
          in: query
          description: >-
            The direction to sort results in.
          schema:
            type: string
            enum:
              - ascend
              - descend
      responses:
        '200':
          description: Successfully retrieved list of services.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '403':
          description: Forbidden. The API token does not have the required permissions.
    post:
      operationId: createService
      summary: Create a service
      description: >-
        Creates a new Fastly service. A service represents the configuration
        for a website, application, API, or other resource to be served
        through Fastly's edge network.
      tags: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  description: >-
                    The name of the service.
                comment:
                  type: string
                  description: >-
                    An optional comment about the service.
                type:
                  type: string
                  description: >-
                    The type of service, either vcl or wasm.
                  enum:
                    - vcl
                    - wasm
      responses:
        '200':
          description: Successfully created the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Bad request. Missing or invalid parameters.
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '403':
          description: Forbidden. The API token does not have the required permissions.
  /service/{service_id}:
    get:
      operationId: getService
      summary: Get a service
      description: >-
        Retrieves detailed information about a specific Fastly service
        identified by its service ID.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Successfully retrieved the service details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
    put:
      operationId: updateService
      summary: Update a service
      description: >-
        Updates the details of a specific Fastly service, such as its name
        or comment.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: >-
                    The name of the service.
                comment:
                  type: string
                  description: >-
                    An optional comment about the service.
      responses:
        '200':
          description: Successfully updated the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '400':
          description: Bad request. Missing or invalid parameters.
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
    delete:
      operationId: deleteService
      summary: Delete a service
      description: >-
        Permanently deletes a specific Fastly service. This action cannot be
        undone and the service must be deactivated before deletion.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Successfully deleted the service.
          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: Service not found.
  /service/{service_id}/details:
    get:
      operationId: getServiceDetails
      summary: Get service details
      description: >-
        Retrieves detailed information about a specific service including all
        of its versions and their associated settings.
      tags: []
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Successfully retrieved detailed service information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDetail'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
  /service/search:
    get:
      operationId: searchService
      summary: Search for a service by name
      description: >-
        Searches for a service by its name and returns the matching service
        details.
      tags: []
      parameters:
        - name: name
          in: query
          required: true
          description: >-
            The name of the service to search for.
          schema:
            type: string
      responses:
        '200':
          description: Successfully found the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
  /service/{service_id}/version:
    get:
      operationId: listServiceVersions
      summary: List versions of a service
      description: >-
        Retrieves a list of all versions associated with a specific Fastly
        service.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Successfully retrieved the list of service versions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
    post:
      operationId: createServiceVersion
      summary: Create a service version
      description: >-
        Creates a new version of a specific Fastly service. New versions are
        created as drafts that can be configured and then activated.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
      responses:
        '200':
          description: Successfully created a new service version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service not found.
  /service/{service_id}/version/{version_id}:
    get:
      operationId: getServiceVersion
      summary: Get a service version
      description: >-
        Retrieves the details of a specific version of a Fastly service.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/versionId'
      responses:
        '200':
          description: Successfully retrieved the service version details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service version not found.
    put:
      operationId: updateServiceVersion
      summary: Update a service version
      description: >-
        Updates a specific version of a Fastly service, such as changing its
        comment or locking status.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/versionId'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: >-
                    A comment describing the version.
      responses:
        '200':
          description: Successfully updated the service version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service version not found.
  /service/{service_id}/version/{version_id}/activate:
    put:
      operationId: activateServiceVersion
      summary: Activate a service version
      description: >-
        Activates a specific version of a Fastly service, making it the live
        configuration that handles traffic for the service.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/versionId'
      responses:
        '200':
          description: Successfully activated the service version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service version not found.
  /service/{service_id}/version/{version_id}/deactivate:
    put:
      operationId: deactivateServiceVersion
      summary: Deactivate a service version
      description: >-
        Deactivates a specific version of a Fastly service, removing it from
        active traffic handling.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/versionId'
      responses:
        '200':
          description: Successfully deactivated the service version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service version not found.
  /service/{service_id}/version/{version_id}/clone:
    put:
      operationId: cloneServiceVersion
      summary: Clone a service version
      description: >-
        Creates a new version of a Fastly service by cloning an existing
        version, including all of its configuration settings.
      tags:
        - Service Version
      parameters:
        - $ref: '#/components/parameters/serviceId'
        - $ref: '#/components/parameters/versionId'
      responses:
        '200':
          description: Successfully cloned the service version.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceVersion'
        '401':
          description: Unauthorized. The API token is missing or invalid.
        '404':
          description: Service version not found.
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Fastly-Key
      description: >-
        API token used to authenticate requests to the Fastly API. Tokens
        can be created in the Fastly web interface or via the 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
    pageNumber:
      name: page
      in: query
      description: >-
        The page number to return.
      schema:
        type: integer
        minimum: 1
    perPage:
      name: per_page
      in: query
      description: >-
        The number of items to return per page.
      schema:
        type: integer
        minimum: 1
        maximum: 100
  schemas:
    Service:
      type: object
      description: >-
        A Fastly service represents the configuration for a website, app,
        API, or anything else to be served through Fastly.
      properties:
        id:
          type: string
          description: >-
            The alphanumeric string identifying the service.
        name:
          type: string
          description: >-
            The name of the service.
        customer_id:
          type: string
          description: >-
            The alphanumeric string identifying the customer.
        comment:
          type: string
          description: >-
            A freeform descriptive note about the service.
        type:
          type: string
          description: >-
            The type of this service, either vcl or wasm.
          enum:
            - vcl
            - wasm
        created_at:
          type: string
          format: date-time
          description: >-
            The date and time in ISO 8601 format when the service was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The date and time in ISO 8601 format when the service was last updated.
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The date and time in ISO 8601 format when the service was deleted.
        active_version:
          type: integer
          nullable: true
          description: >-
            The currently active version number for the service.
        versions:
          type: array
          description: >-
            A list of version objects associated with the service.
          items:
            $ref: '#/components/schemas/ServiceVersion'
    ServiceDetail:
      allOf:
        - $ref: '#/components/schemas/Service'
        - type: object
          description: >-
            Extended service information including all associated versions and
            their configuration details.
          properties:
            active_version:
              type: object
              description: >-
                The full version object for the currently active version.
              nullable: true
    ServiceVersion:
      type: object
      description: >-
        A version of a Fastly service. Versions represent distinct
        configurations that can be activated or deactivated independently.
      properties:
        number:
          type: integer
          description: >-
            The version number.
        service_id:
          type: string
          description: >-
            The alphanumeric string identifying the service.
        active:
          type: boolean
          description: >-
            Whether this version is currently active.
        locked:
          type: boolean
          description: >-
            Whether this version is locked and cannot be modified.
        deployed:
          type: boolean
          description: >-
            Whether this version has been deployed.
        staging:
          type: boolean
          description: >-
            Whether this version is in the staging environment.
        testing:
          type: boolean
          description: >-
            Whether this version is in the testing environment.
        comment:
          type: string
          description: >-
            A freeform descriptive note about the version.
        created_at:
          type: string
          format: date-time
          description: >-
            The date and time in ISO 8601 format when the version was created.
        updated_at:
          type: string
          format: date-time
          description: >-
            The date and time in ISO 8601 format when the version was last updated.
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            The date and time in ISO 8601 format when the version was deleted.