openapi: 3.0.0
info:
  title: 'Akamai: API Endpoint Definition Access tokens Rate limits API'
  version: '2'
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  description: Groups operations that let you control rate limits.
servers:
- url: https://{hostname}/api-definitions/v2
tags:
- description: Groups operations that let you control rate limits.
  name: Rate limits
paths:
  /rate-limit-status/{purge-type}:
    parameters:
    - description: __Enum__ A single item within a purge request that identifies the content you want to purge. You can identify your content by a URL or ARL (Akamai resource locator), content provider (CP) code, or cache tag.
      in: path
      name: purge-type
      required: true
      schema:
        enum:
        - cpcode
        - tag
        - url
        example: cpcode
        type: string
      x-akamai:
        file-path: parameters/purge-type.yaml
    x-akamai:
      file-path: paths/rate-limit-status.yaml
      path-info: /rate-limit-status/{purge-type}
    post:
      description: 'The Fast Purge API uses a token bucket model for [rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) to protect itself from inadvertent or malicious overuse. For each Akamai account, there''s a rate limit shared by all object types (CP codes, cache tags, and URL/ARLs), and three separate resource limits for each object type. Each purge request uses one rate limit token from the requests bucket. Each purge object in a request takes up a token from the resource bucket.

        This operation fetches information on the remaining number of requests and objects for a specific account. You can use these details to monitor the request consumption or throttle requests to prevent exceeding the limits, which results in the [429](https://techdocs.akamai.com/purge-cache/reference/429) error.'
      externalDocs:
        description: See documentation for this operation in Akamai's Fast Purge API
        url: https://techdocs.akamai.com/purge-cache/reference/post-rate-limit-status
      operationId: post-rate-limit-status
      parameters: []
      responses:
        '201':
          content:
            application/json:
              example:
                detail: Request accepted
                estimatedSeconds: 5
                httpStatus: 201
                purgeId: edcp-NZbXzFpHBjcJeryhw6PVgG
                supportId: edcp-NZbXzFpHBjcJeryhw6PVgG
              schema:
                additionalProperties: true
                description: Rate limit status response.
                properties:
                  describedBy:
                    description: A URL that describes the API's error response.
                    type: string
                  detail:
                    description: Detailed information about the HTTP status code returned with the response.
                    type: string
                  httpStatus:
                    description: The HTTP code that indicates the status of the rate limit status request. Successful requests yield a 201 response code.
                    type: integer
                  rateLimit:
                    description: The maximum number of requests allowed each second per account. Unlike the response header, this JSON response body field only appears if the request exceeded the rate limit and got rejected with the [429](https://techdocs.akamai.com/purge-cache/reference/429) error.
                    type: integer
                  rateLimitCurrentRequestSize:
                    description: The size of the request. For the request limit, this usually equals 1. For the resource limit, this depends on the number of purge objects included in the request, such as CP codes, cache tags, and URL/ARLs. Unlike the response header, this JSON response body field only appears if a request exceeded the rate limit and was rejected with the [429](https://techdocs.akamai.com/purge-cache/reference/429) error.
                    type: integer
                  rateLimitRemaining:
                    description: The number of requests or objects remaining in the token bucket before the rate limit is exceeded. Unlike the response header, this field only appears if a request exceeded the rate limit and was rejected with the [429](https://techdocs.akamai.com/purge-cache/reference/429) error.
                    type: integer
                  supportId:
                    description: Identifier to provide Akamai Technical Support if issues arise.
                    type: string
                  title:
                    description: Describes the response type, for example, `Rate Limit exceeded`.
                    type: string
                required:
                - httpStatus
                - supportId
                - detail
                type: object
                x-akamai:
                  file-path: schemas/rate-limit-status-response.yaml
          description: Successful POST of a rate limit status request.
          headers:
            X-Ratelimit-Limit:
              description: The burst limit that specifies how many requests you can make in excess of the imposed rate limit. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 100
                type: integer
              x-akamai:
                file-path: headers/x-ratelimit-limit.yaml
            X-Ratelimit-Limit-Objects:
              description: The burst limit that specifies how many objects you can add to a request in excess of the imposed rate limit. This depends on the object type in the given request. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 10000
                type: integer
              x-akamai:
                file-path: headers/x-ratelimit-limit-objects.yaml
            X-Ratelimit-Limit-Per-Second:
              description: Maximum sustainable number of requests allowed each second per account. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 50
                type: number
              x-akamai:
                file-path: headers/x-ratelimit-limit-per-second.yaml
            X-Ratelimit-Limit-Per-Second-Objects:
              description: Maximum sustainable number of objects allowed each second per request. This depends on the object type in the given request. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 200
                type: number
              x-akamai:
                file-path: headers/x-ratelimit-limit-per-second-objects.yaml
            X-Ratelimit-Remaining:
              description: The number of requests left before exceeding the limit, which results in the [429](https://techdocs.akamai.com/purge-cache/reference/429) error. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 99
                type: integer
              x-akamai:
                file-path: headers/x-ratelimit-remaining.yaml
            X-Ratelimit-Remaining-Objects:
              description: The number of objects left before exceeding the limit, which results in the [429](https://techdocs.akamai.com/purge-cache/reference/429) error. This depends on the object type in the given request. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 10000
                type: integer
              x-akamai:
                file-path: headers/x-ratelimit-remaining-objects.yaml
            X-Ratelimit-Seconds-To-Refresh-Limit:
              description: The minimum number of seconds to wait before you can send a request burst of size `X-Ratelimit-Limit`. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 0.02
                type: number
              x-akamai:
                file-path: headers/x-ratelimit-seconds-to-refresh-limit.yaml
            X-Ratelimit-Seconds-To-Refresh-Limit-Objects:
              description: The minimum number of seconds to wait before you can send a request burst of size `X-Ratelimit-Limit-Objects`. See [Rate limiting](https://techdocs.akamai.com/purge-cache/reference/rate-limiting) for details.
              schema:
                example: 0
                type: number
              x-akamai:
                file-path: headers/x-ratelimit-seconds-to-refresh-limit-objects.yaml
        '400':
          content:
            application/api-problem+json:
              example:
                describedBy: https://techdocs.akamai.com/purge-cache/reference/api-errors
                detail: Invalid or malformed hostname
                httpStatus: 400
                supportId: edcp-NZbXzFpHBjcJeryhw6PVgG
                title: bad URL hostname
              schema:
                additionalProperties: true
                description: V3 Purge response schema.
                properties:
                  describedBy:
                    description: A URL that describes the API's error response.
                    type: string
                  detail:
                    description: Detailed information about the HTTP status code returned with the response.
                    type: string
                  estimatedSeconds:
                    description: The estimated number of seconds before the purge is to complete.
                    type: integer
                  httpStatus:
                    description: The HTTP code that indicates the status of the request to invalidate or purge content. Successful requests yield a `201` code.
                    type: integer
                  purgeId:
                    description: Unique identifier for the purge request.
                    type: string
                  supportId:
                    description: Identifier to provide Akamai Technical Support if issues arise.
                    type: string
                  title:
                    description: Describes the response type, for example, `Rate Limit exceeded`.
                    type: string
                required:
                - httpStatus
                - supportId
                - detail
                type: object
                x-akamai:
                  file-path: schemas/response.yaml
          description: '[Bad request](https://techdocs.akamai.com/purge-cache/reference/400).'
          x-akamai:
            file-path: errors/400.yaml
        '403':
          content:
            application/api-problem+json:
              example:
                describedBy: https://techdocs.akamai.com/purge-cache/reference/api-errors
                detail: http://fpj-test.bad-ideas2.org/
                httpStatus: 403
                supportId: edcp-NZbXzFpHBjcJeryhw6PVgG
                title: unauthorized arl
              schema:
                additionalProperties: true
                description: V3 Purge response schema.
                properties:
                  describedBy:
                    description: A URL that describes the API's error response.
                    type: string
                  detail:
                    description: Detailed information about the HTTP status code returned with the response.
                    type: string
                  estimatedSeconds:
                    description: The estimated number of seconds before the purge is to complete.
                    type: integer
                  httpStatus:
                    description: The HTTP code that indicates the status of the request to invalidate or purge content. Successful requests yield a `201` code.
                    type: integer
                  purgeId:
                    description: Unique identifier for the purge request.
                    type: string
                  supportId:
                    description: Identifier to provide Akamai Technical Support if issues arise.
                    type: string
                  title:
                    description: Describes the response type, for example, `Rate Limit exceeded`.
                    type: string
                required:
                - httpStatus
                - supportId
                - detail
                type: object
                x-akamai:
                  file-path: schemas/response.yaml
          description: '[Forbidden](https://techdocs.akamai.com/purge-cache/reference/403).'
          x-akamai:
            file-path: errors/403.yaml
        '429':
          content:
            application/api-problem+json:
              example:
                describedBy: https://techdocs.akamai.com/purge-cache/reference/api-errors
                detail: ''
                httpStatus: 429
                rateLimit: 10000
                rateLimitCurrentRequestSize: 110
                rateLimitRemaining: 94
                supportId: edup-NZbXzFpHBjcJeryhw6PVgG
                title: URL Rate Limit exceeded
              schema:
                additionalProperties: true
                description: V3 Purge response schema.
                properties:
                  describedBy:
                    description: A URL that describes the API's error response.
                    type: string
                  detail:
                    description: Detailed information about the HTTP status code returned with the response.
                    type: string
                  estimatedSeconds:
                    description: The estimated number of seconds before the purge is to complete.
                    type: integer
                  httpStatus:
                    description: The HTTP code that indicates the status of the request to invalidate or purge content. Successful requests yield a `201` code.
                    type: integer
                  purgeId:
                    description: Unique identifier for the purge request.
                    type: string
                  supportId:
                    description: Identifier to provide Akamai Technical Support if issues arise.
                    type: string
                  title:
                    description: Describes the response type, for example, `Rate Limit exceeded`.
                    type: string
                required:
                - httpStatus
                - supportId
                - detail
                type: object
                x-akamai:
                  file-path: schemas/response.yaml
          description: '[Too many requests](https://techdocs.akamai.com/purge-cache/reference/429).'
          x-akamai:
            file-path: errors/429-url.yaml
        '500':
          content:
            application/api-problem+json:
              example:
                describedBy: https://techdocs.akamai.com/purge-cache/reference/api-errors
                detail: If problem persists over multiple requests, please contact Customer Care
                httpStatus: 500
                supportId: edcp-NZbXzFpHBjcJeryhw6PVgG
                title: internal error
              schema:
                additionalProperties: true
                description: V3 Purge response schema.
                properties:
                  describedBy:
                    description: A URL that describes the API's error response.
                    type: string
                  detail:
                    description: Detailed information about the HTTP status code returned with the response.
                    type: string
                  estimatedSeconds:
                    description: The estimated number of seconds before the purge is to complete.
                    type: integer
                  httpStatus:
                    description: The HTTP code that indicates the status of the request to invalidate or purge content. Successful requests yield a `201` code.
                    type: integer
                  purgeId:
                    description: Unique identifier for the purge request.
                    type: string
                  supportId:
                    description: Identifier to provide Akamai Technical Support if issues arise.
                    type: string
                  title:
                    description: Describes the response type, for example, `Rate Limit exceeded`.
                    type: string
                required:
                - httpStatus
                - supportId
                - detail
                type: object
                x-akamai:
                  file-path: schemas/response.yaml
          description: '[Internal server error](https://techdocs.akamai.com/purge-cache/reference/500).'
          x-akamai:
            file-path: errors/500.yaml
      summary: Check rate and object limit statuses
      tags:
      - Rate limits
      x-akamai:
        supports-account-switch-key: false
externalDocs:
  description: See documentation for Akamai's API Endpoint Definition API
  url: https://techdocs.akamai.com/api-definitions/reference
x-readme:
  samples-languages:
  - curl
  - python
  - node