Akamai Versions API

openapi: 3.0.0
info:
  title: 'Akamai: API Endpoint Definition Access tokens Versions API'
  version: '2'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{hostname}/api-definitions/v2
tags:
- name: Versions
paths:
  /endpoints/{apiEndPointId}/versions:
    parameters:
    - description: The unique identifier for the endpoint.
      example: '{{apiEndPointId}}'
      in: path
      name: apiEndPointId
      required: true
      schema:
        example: 1
        type: integer
      x-akamai:
        file-path: parameters/apiEndPointId-path.yaml
    get:
      description: Returns versions of an endpoint, with results optionally paginated, sorted, and filtered.
      operationId: get-endpoint-versions
      summary: List versions
      tags:
      - Versions
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/get-endpoint-versions
      responses:
        '200':
          description: Lists API endpoint versions you have access to in this account.
          content:
            application/json:
              example:
                apiEndPointId: 492375
                apiEndPointName: Bookstore API
                page: 1
                pageSize: 25
                totalSize: 50
                apiVersions:
                - apiEndPointVersionId: 599104
                  basePath: /bookstore2
                  basedOn: 1
                  createDate: 2019-06-17T07:22:29+0000
                  createdBy: mrossi
                  description: An API for bookstore users allowing them to retrieve book items, add new items (admin users), and modify existing items.
                  hidden: false
                  isVersionLocked: false
                  lockVersion: 2
                  productionDate: null
                  productionStatus: null
                  stagingDate: null
                  stagingStatus: null
                  updateDate: 2019-06-17T07:23:11+0000
                  updatedBy: bookstore_admin
                  versionNumber: 2
                  availableActions:
                  - ACTIVATE_ON_PRODUCTION
                  - VIEW_AAG_SETTINGS
                  - COMPARE_RAPID_SETTINGS
                  - EDIT_AAG_SETTINGS
                  - HIDE_VERSION
                  - CLONE_VERSION
                  - EDIT_ENDPOINT_DEFINITION
                  - COMPARE_ENDPOINT
                  - RESOURCES
                  - ACTIVATE_ON_STAGING
                  - DELETE
                - apiEndPointVersionId: 574127
                  basePath: /bookstore
                  basedOn: null
                  createDate: 2019-06-12T13:06:52+0000
                  createdBy: szhang
                  description: An API for bookstore users allowing them to retrieve book items, add new items (admin users), and modify existing items.
                  hidden: false
                  isVersionLocked: false
                  lockVersion: 0
                  productionDate: null
                  productionStatus: null
                  stagingDate: null
                  stagingStatus: null
                  updateDate: 2019-06-12T13:06:52+0000
                  updatedBy: bookstore_admin
                  versionNumber: 1
                  availableActions:
                  - VIEW_AAG_SETTINGS
                  - EDIT_AAG_SETTINGS
                  - EDIT_ENDPOINT_DEFINITION
                  - DELETE
                  - ACTIVATE_ON_STAGING
                  - COMPARE_RAPID_SETTINGS
                  - ACTIVATE_ON_PRODUCTION
                  - COMPARE_ENDPOINT
                  - CLONE_VERSION
                  - RESOURCES
                  - HIDE_VERSION
              schema:
                additionalProperties: false
                description: Contains information about all versions of an endpoint.
                type: object
                required:
                - apiEndpointId
                properties:
                  apiEndPointId:
                    description: The unique identifier for the endpoint.
                    type: integer
                  apiEndPointName:
                    description: The name of the endpoint, unique within the account.
                    type: string
                  apiVersions:
                    description: Contains information about each endpoint version within a collection.
                    type: array
                    items:
                      additionalProperties: false
                      type: object
                      required:
                      - lockVersion
                      - versionNumber
                      properties:
                        apiEndPointVersionId:
                          description: The unique identifier for the endpoint version.
                          type: integer
                        availableActions:
                          description: The collection of available actions that you can perform on the version depending on the version's activation status.
                          type: array
                          items:
                            type: string
                            enum:
                            - CLONE_ENDPOINT
                            - CLONE_VERSION
                            - DELETE
                            - RESOURCES
                            - COMPARE_ENDPOINT
                            - COMPARE_AAG_SETTINGS
                            - COMPARE_RESOURCE_PURPOSES
                            - COMPARE_RAPID_SETTINGS
                            - VIEW_AAG_SETTINGS
                            - EDIT_AAG_SETTINGS
                            - EDIT_ENDPOINT_DEFINITION
                            - ACTIVATE_ON_STAGING
                            - ACTIVATE_ON_PRODUCTION
                            - DEACTIVATE_ON_STAGING
                            - DEACTIVATE_ON_PRODUCTION
                            - HIDE_VERSION
                            - SHOW_VERSION
                        basePath:
                          description: The URL path that serves as a root prefix for all resources' `resourcePath` values. This is `/` if empty. Don't append a `/` character to the path. If you specify `null` in the request or omit this member from the object, the JSON response reflects it as an empty string.
                          type: string
                        basedOn:
                          description: For cloned versions, the unique identifier for the source version.
                          nullable: true
                          type: integer
                        createDate:
                          description: The ISO 6801 timestamp indicating when you created the endpoint version.
                          format: date-time
                          type: string
                        createdBy:
                          description: The identifier for the user who created the version.
                          type: string
                        description:
                          description: The description of the endpoint version. If you specify `null` in the request or omit this member from the object, the JSON response reflects it as an empty string.
                          type: string
                        hidden:
                          description: Indicates whether the endpoint version is hidden. You cannot activate or delete hidden versions. If you want to do so, you first need to reveal the version by running the [Show a version](https://techdocs.akamai.com/api-definitions/reference/post-version-show) operation.
                          type: boolean
                        isVersionLocked:
                          description: Whether the endpoint version is read-only.
                          type: boolean
                        lockVersion:
                          description: The identifier for the last modification of an endpoint version, used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                          type: integer
                        productionDate:
                          description: The ISO 6801 timestamp indicating when you activated the endpoint version on the production network.
                          format: date-time
                          nullable: true
                          type: string
                        productionStatus:
                          description: The version activation status on the production network, either `PENDING` if the version contains changes that are being propagated to the network, `ACTIVE` if the version is active, `DEACTIVATED` if the version was once active but is deactivated, or `FAILED` if an activation or deactivation attempt for this version has failed. The value is `null` for versions that have never been activated on this network.
                          nullable: true
                          type: string
                          enum:
                          - PENDING
                          - ACTIVE
                          - DEACTIVATED
                          - FAILED
                        stagingDate:
                          description: The ISO 6801 timestamp indicating when you activated the endpoint version on the staging network.
                          format: date-time
                          nullable: true
                          type: string
                        stagingStatus:
                          description: The version activation status on the staging network, either `PENDING` if the version contains changes that are being propagated to the network, `ACTIVE` if the version is active, `DEACTIVATED` if the version was once active but is deactivated, or `FAILED` if an activation or deactivation attempt for this version has failed. The value is `null` for versions that have never been activated on this network.
                          nullable: true
                          type: string
                          enum:
                          - PENDING
                          - ACTIVE
                          - DEACTIVATED
                          - FAILED
                        updateDate:
                          description: The ISO 6801 timestamp indicating when you last modified the endpoint version.
                          format: date-time
                          type: string
                        updatedBy:
                          description: The identifier for the user who last modified the version.
                          type: string
                        versionNumber:
                          description: The endpoint version number.
                          type: integer
                  page:
                    default: 1
                    description: The number of the current page with results.
                    minimum: 1
                    type: integer
                  pageSize:
                    default: 2147483647
                    description: The number of endpoint versions on each page with results.
                    type: integer
                  totalSize:
                    description: The total number of endpoint versions available in the returned set.
                    type: integer
                x-akamai:
                  file-path: schemas/apiEndpointVersionListDto.yaml
        '403':
          description: You don't have permission to retrieve the API endpoint versions list.
          content:
            application/problem+json:
              schema:
                additionalProperties: false
                description: Contains debugging information for error responses.
                type: object
                properties:
                  detail:
                    description: The detailed error message.
                    type: string
                  errors:
                    description: The collection of nested error responses.
                    type: array
                    items:
                      additionalProperties: false
                      description: A further nested problem detail object.
                      type: object
                      x-akamai:
                        file-path: schemas/httpProblemDetails-recurse.yaml
                  instance:
                    description: The non-referenceable URL for the error instance.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 404
                    type: integer
                  title:
                    description: The title of the error.
                    example: Not Found
                    type: string
                  type:
                    description: The URL for the error type.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-types/NOT-FOUND
                    type: string
                x-akamai:
                  file-path: schemas/httpProblemDetails.yaml
      parameters:
      - description: The page number index, starting at the default value of `1`.
        example: '{{page}}'
        in: query
        name: page
        schema:
          default: 1
          type: integer
        x-akamai:
          file-path: parameters/page-query.yaml
      - description: The number of endpoint versions on each page of results.
        example: '{{pageSize}}'
        in: query
        name: pageSize
        schema:
          default: 2147483647
          example: 50
          type: integer
      - description: __Enum__ The field to sort endpoint versions by.
        example: '{{sortBy}}'
        in: query
        name: sortBy
        schema:
          default: versionNumber
          example: updateDate
          type: string
          enum:
          - versionNumber
          - description
          - updateDate
          - updatedBy
          - basedOn
          - stagingStatus
          - productionStatus
      - description: __Enum__ The sort order, either `asc` for ascending or the default `desc` for descending.
        example: '{{sortOrder}}'
        in: query
        name: sortOrder
        schema:
          default: desc
          example: desc
          type: string
          enum:
          - asc
          - desc
      - description: __Enum__ The type of endpoint versions to return based on their visibility status. By default the API returns `ALL` endpoint version. You can instead decide to return `ONLY_VISIBLE` endpoint versions, or `ONLY_HIDDEN` endpoint versions. Run the [Show a version](https://techdocs.akamai.com/api-definitions/reference/post-version-show) and [Hide a version](https://techdocs.akamai.com/api-definitions/reference/post-endpoint-version-hide) operations to control which endpoint versions are listed.
        example: '{{show}}'
        in: query
        name: show
        schema:
          default: ALL
          example: ONLY_VISIBLE
          type: string
          enum:
          - ALL
          - ONLY_VISIBLE
          - ONLY_HIDDEN
      - description: For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).
        example: '{{accountSwitchKey}}'
        in: query
        name: accountSwitchKey
        required: false
        schema:
          example: 1-5C0YLB:1-8BYUX
          type: string
  /endpoints/{apiEndPointId}/versions/{versionNumber}:
    parameters:
    - description: The unique identifier for the endpoint version.
      example: '{{versionNumber}}'
      in: path
      name: versionNumber
      required: true
      schema:
        example: 1
        type: integer
      x-akamai:
        file-path: parameters/versionNumber-path.yaml
    - description: The unique identifier for the endpoint.
      example: '{{apiEndPointId}}'
      in: path
      name: apiEndPointId
      required: true
      schema:
        example: 1
        type: integer
      x-akamai:
        file-path: parameters/apiEndPointId-path.yaml
    get:
      description: Returns a summary for a specific endpoint version. The summary is for purely informational purposes, and you shouldn't use this operation's response in the corresponding [Edit a version](https://techdocs.akamai.com/api-definitions/reference/put-endpoint-version) PUT request. For the PUT request, use the response object of [Get a version](https://techdocs.akamai.com/api-definitions/reference/get-endpoint-version-resource).
      operationId: get-endpoint-version
      summary: Get a version summary
      tags:
      - Versions
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/get-endpoint-version
      responses:
        '200':
          description: API Endpoint version summary defined by API Endpoint ID and Version Number.
          content:
            application/json:
              example:
                apiVersionId: 574127
                basePath: /bookstore
                description: An API for bookstore users allowing them to retrieve book items, add new items (admin users), and modify existing items.
                hidden: false
                productionStatus: ACTIVE
                source: null
                stagingStatus: ACTIVE
                apiCategoryIds: []
                apiEndPointHosts:
                - bookstore.api.akamai.com
                apiResourceNames:
                - book
                - user
                - magazine
                availableActions:
                - ACTIVATE_ON_STAGING
                - VIEW_AAG_SETTINGS
                - ACTIVATE_ON_PRODUCTION
                - COMPARE_RAPID_SETTINGS
                - DELETE
                - HIDE_VERSION
                - CLONE_VERSION
                - EDIT_AAG_SETTINGS
                - EDIT_ENDPOINT_DEFINITION
                - RESOURCES
                - COMPARE_ENDPOINT
              schema:
                additionalProperties: false
                description: Contains summary information about a specific endpoint version.
                type: object
                properties:
                  apiCategoryIds:
                    description: The category identifiers that apply to the endpoint. The value is `null` for uncategorized endpoints.
                    type: array
                    items:
                      type: integer
                  apiEndPointHosts:
                    description: The hostname strings that may receive traffic for the endpoint.
                    type: array
                    items:
                      type: string
                  apiEndPointVersionId:
                    description: The unique identifier for the endpoint version.
                    type: integer
                  apiResourceNames:
                    description: The collection of resource names defined for the endpoint. The value is `null` for endpoints without any resources.
                    type: array
                    items:
                      type: string
                  availableActions:
                    description: The collection of available actions that you can perform on the version depending on the version's activation status.
                    type: array
                    items:
                      type: string
                      enum:
                      - CLONE_ENDPOINT
                      - CLONE_VERSION
                      - DELETE
                      - RESOURCES
                      - COMPARE_ENDPOINT
                      - COMPARE_AAG_SETTINGS
                      - COMPARE_RAPID_SETTINGS
                      - COMPARE_RESOURCE_PURPOSES
                      - VIEW_AAG_SETTINGS
                      - EDIT_AAG_SETTINGS
                      - EDIT_ENDPOINT_DEFINITION
                      - ACTIVATE_ON_STAGING
                      - ACTIVATE_ON_PRODUCTION
                      - DEACTIVATE_ON_STAGING
                      - DEACTIVATE_ON_PRODUCTION
                      - HIDE_VERSION
                      - SHOW_VERSION
                  basePath:
                    description: The URL path that serves as a root prefix for all resources' `resourcePath` values. This is `/` if empty. Do not append a `/` character to the path. If you specify `null` in the request or omit this member from the object, the JSON response reflects it as an empty string.
                    type: string
                  description:
                    description: The description of the endpoint.
                    type: string
                  productionStatus:
                    description: The version activation status in the production network, either `PENDING` if the version contains changes that are being propagated to the network, `ACTIVE` if the version is active, `DEACTIVATED` if the version was once active but is deactivated, or `FAILED` if an activation or deactivation attempt for this version has failed. The value is `null` for versions that have never been activated in this network.
                    type: string
                    enum:
                    - PENDING
                    - ACTIVE
                    - DEACTIVATED
                    - FAILED
                  stagingStatus:
                    description: The version activation status in the staging network, either `PENDING` if the version contains changes that are being propagated to the network, `ACTIVE` if the version is active, `DEACTIVATED` if the version was once active but now inactive, or `FAILED` if an activation or deactivation attempt for this version has failed. The value is `null` for versions that have never been activated in this network.
                    type: string
                    enum:
                    - PENDING
                    - ACTIVE
                    - DEACTIVATED
                    - FAILED
                x-akamai:
                  file-path: schemas/apiVersionSummaryDto.yaml
        '403':
          description: You don't have access to the endpoint.
          content:
            application/problem+json:
              schema:
                additionalProperties: false
                description: Contains debugging information for error responses.
                type: object
                properties:
                  detail:
                    description: The detailed error message.
                    type: string
                  errors:
                    description: The collection of nested error responses.
                    type: array
                    items:
                      additionalProperties: false
                      description: A further nested problem detail object.
                      type: object
                      x-akamai:
                        file-path: schemas/httpProblemDetails-recurse.yaml
                  instance:
                    description: The non-referenceable URL for the error instance.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 404
                    type: integer
                  title:
                    description: The title of the error.
                    example: Not Found
                    type: string
                  type:
                    description: The URL for the error type.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-types/NOT-FOUND
                    type: string
                x-akamai:
                  file-path: schemas/httpProblemDetails.yaml
        '404':
          description: The API endpoint is not found.
          content:
            application/problem+json:
              schema:
                additionalProperties: false
                description: Contains debugging information for error responses.
                type: object
                properties:
                  detail:
                    description: The detailed error message.
                    type: string
                  errors:
                    description: The collection of nested error responses.
                    type: array
                    items:
                      additionalProperties: false
                      description: A further nested problem detail object.
                      type: object
                      x-akamai:
                        file-path: schemas/httpProblemDetails-recurse.yaml
                  instance:
                    description: The non-referenceable URL for the error instance.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                    type: string
                  status:
                    description: The HTTP status code.
                    example: 404
                    type: integer
                  title:
                    description: The title of the error.
                    example: Not Found
                    type: string
                  type:
                    description: The URL for the error type.
                    example: https://problems.luna.akamaiapis.net/api-definitions/error-types/NOT-FOUND
                    type: string
                x-akamai:
                  file-path: schemas/httpProblemDetails.yaml
      parameters:
      - description: For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).
        example: '{{accountSwitchKey}}'
        in: query
        name: accountSwitchKey
        required: false
        schema:
          example: 1-5C0YLB:1-8BYUX
          type: string
    put:
      description: Updates details about an endpoint version that has never been activated on the staging or production network. You can configure the endpoint's security settings and other top-level metadata, or modify the endpoint's entire set of resources as an alternative to separate calls to [Edit a resource](https://techdocs.akamai.com/api-definitions/reference/put-version-resource). Note that the corresponding [Get a version](https://techdocs.akamai.com/api-definitions/reference/get-endpoint-version-resource) operation you need to run to GET the data uses a different URL.
      operationId: put-endpoint-version
      summary: Edit a version
      tags:
      - Versions
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/put-endpoint-version
      requestBody:
        required: true
        content:
          application/json:
            example:
              akamaiSecurityRestrictions: null
              apiEndPointId: 492375
              apiEndPointLocked: false
              apiEndPointName: Bookstore API
              apiEndPointScheme: http/https
              apiEndPointVersion: 574127
              apiGatewayEnabled: true
              basePath: /bookstore
              caseSensitive: true
              clonedFromVersion: null
              consumeType: any
              contractId: K-0N7RAK7
              createDate: 2019-06-12T13:06:52+0000
              createdBy: alfulani
              description: An API for bookstore users allowing them to retrieve book items and modify existing items.
              endpointHidden: false
              graphQL: false
              groupId: 44681
              isGraphQL: false
              lockVersion: 0
              positiveConstrainsEnabled: true
              productionStatus: null
              protectedByApiKey: true
              responseConstraintsEnabled: false
              source: null
              stagingStatus: null
              updateDate: 2019-06-12T13:06:55+0000
              updatedBy: bookstore_admin
              versionHidden: false
              versionNumber: 1
              apiCategoryIds: []
              apiEndPointHosts:
              - bookstore.api.akamai.com
              availableActions:
              - DELETE
              - CLONE_ENDPOINT
              - ACTIVATE_ON_PRODUCTION
              - HIDE_ENDPOINT
              - EDIT_ENDPOINT_DEFINITION
              - ACTIVATE_ON_STAGING
              discoveredPiiIds:
              - 455976
              productionVersion:
                lastError: null
                status: null
                timestamp: null
                versionNumber: null
              securityScheme:
                securitySchemeType: apikey
                securitySchemeDetail:
                  apiKeyLocation: header
                  apiKeyName: apikey
              stagingVersion:
                lastError: null
                status: null
                timestamp: null
                versionNumber: null
              apiResources:
              - apiResourceClonedFromId: null
                apiResourceId: 2926712
                apiResourceLogicId: 118435
                apiResourceName: books
                createDate: 2019-06-12T13:06:52+0000
                createdBy: szhang
                description: A book item within the bookstore API.
                link: null
                lockVersion: 0
                private: false
                resourcePath: /books/{bookId}
                updateDate: 2019-06-12T13:06:52+0000
                updatedBy: bookstore_admin
                apiResourceMethods:
                - apiResourceMethod: GET
                  apiResourceMethodId: 341591
                  apiResourceMethodLogicId: 184404
                  apiParameters:
                  - apiParamLogicId: 578116
                    apiParameterId: 1212945
                    apiParameterLocation: path
                    apiParameterName: bookId
                    apiParameterNotes: null
                    apiParameterRequired: true
                    apiParameterRestriction: null
                    apiParameterType: string
                    apiResourceMethParamId: 494448
                    array: false
                    pathParamLocationId: 3
                    response: false
                    apiChildParameters: []
                - apiResourceMethod: POST
                  apiResourceMethodId: 341592
                  apiResourceMethodLogicId: 184405
                  apiParameters:
                  - apiParamLogicId: 578117
                    apiParameterId: 1212946
                    apiParameterLocation: path
                    apiParameterName: bookId
                    apiParameterNotes: null
                    apiParameterRequired: true
                    apiParameterType: string
                    apiResourceMethParamId: 494449
                    array: false
                    pathParamLocationId: 3
                    response: false
                    apiChildParameters: []
                    apiParameterRestriction:
                      apiParameterType: json
                      array: true
                      numberRangeRestriction: null
                      rangeRestriction: null
                      xmlConversionRule: null
                      arrayRestriction:
                        maxItems: 200
                        minItems: 100
                      responseRestriction:
                        maxBodySize: SIZE_6K
                        statusCodes:
                        - 200
                        - 201
            schema:
              additionalProperties: false
              description: Contains information about an endpoint and its associated resources.
              type: object
              required:
              - api

# --- truncated at 32 KB (477 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/akamai/refs/heads/main/openapi/akamai-versions-api-openapi.yml