Akamai Categories API

openapi: 3.0.0
info:
  title: 'Akamai: API Endpoint Definition Access tokens Categories 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: Categories
paths:
  /categories:
    post:
      description: Creates a category that you can use to tag endpoints. The request's `apiCategoryName` needs to be unique per account.
      operationId: post-category
      summary: Create a category
      tags:
      - Categories
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/post-category
      requestBody:
        required: true
        content:
          application/json:
            example:
              apiCategoryDescription: The applications related to the Sales department.
              apiCategoryName: Sales
            schema:
              additionalProperties: false
              description: Contains information about an endpoint category.
              type: object
              required:
              - apiCategoryName
              properties:
                apiCategoryDescription:
                  description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                  example: '{{apiCategoryDescription}}'
                  type: string
                apiCategoryId:
                  description: The unique identifier for the category.
                  example: '{{apiCategoryId}}'
                  type: integer
                apiCategoryName:
                  description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                  example: '{{apiCategoryName}}'
                  type: string
                createDate:
                  description: The ISO 6801 timestamp indicating when you created the category.
                  example: '{{createDate}}'
                  format: date-time
                  type: string
                createdBy:
                  description: The identifier for the user who created the category.
                  example: '{{createdBy}}'
                  type: string
                link:
                  description: The location of the navigable resource within this API, for use by API clients.
                  example: '{{link}}'
                  nullable: true
                  type: string
                lockVersion:
                  description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                  example: '{{lockVersion}}'
                  type: number
                updateDate:
                  description: The ISO 6801 timestamp indicating when you last modified the category.
                  example: '{{updateDate}}'
                  format: date-time
                  type: string
                updatedBy:
                  description: The identifier for the user who last modified the category.
                  example: '{{updatedBy}}'
                  type: string
                usageCount:
                  description: The number of endpoints that share the category.
                  example: '{{usageCount}}'
                  type: integer
              x-akamai:
                file-path: schemas/categoryDto.yaml
      responses:
        '201':
          description: New resource successfully created.
          content:
            application/json:
              example:
                apiCategoryDescription: The applications related to the Sales department.
                apiCategoryId: 9902
                apiCategoryName: Sales
                createDate: 2019-06-17T12:40:14+0000
                link: /api-definitions/v2/categories/9902
                lockVersion: 0
                updateDate: 2019-06-17T12:40:14+0000
              schema:
                additionalProperties: false
                description: Contains information about an endpoint category.
                type: object
                required:
                - apiCategoryName
                properties:
                  apiCategoryDescription:
                    description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                    type: string
                  apiCategoryId:
                    description: The unique identifier for the category.
                    type: integer
                  apiCategoryName:
                    description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                    type: string
                  createDate:
                    description: The ISO 6801 timestamp indicating when you created the category.
                    format: date-time
                    type: string
                  createdBy:
                    description: The identifier for the user who created the category.
                    type: string
                  link:
                    description: The location of the navigable resource within this API, for use by API clients.
                    nullable: true
                    type: string
                  lockVersion:
                    description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                    type: number
                  updateDate:
                    description: The ISO 6801 timestamp indicating when you last modified the category.
                    format: date-time
                    type: string
                  updatedBy:
                    description: The identifier for the user who last modified the category.
                    type: string
                  usageCount:
                    description: The number of endpoints that share the category.
                    type: integer
                x-akamai:
                  file-path: schemas/categoryDto.yaml
          headers:
            Location:
              description: Relative URL for created API endpoint category.
              schema:
                type: string
        '400':
          description: Some of user input is invalid.
          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
    get:
      description: Lists all categories available to tag endpoints and optionally indicates the number of endpoints tagged under each category.
      operationId: get-categories
      summary: List categories
      tags:
      - Categories
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/get-categories
      responses:
        '200':
          description: The response lists unique categories, or an empty list if there are none.
          content:
            application/json:
              schema:
                description: The collection of endpoint categories.
                type: array
                items:
                  additionalProperties: false
                  description: Contains information about an endpoint category.
                  type: object
                  required:
                  - apiCategoryName
                  properties:
                    apiCategoryDescription:
                      description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                      type: string
                    apiCategoryId:
                      description: The unique identifier for the category.
                      type: integer
                    apiCategoryName:
                      description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                      type: string
                    createDate:
                      description: The ISO 6801 timestamp indicating when you created the category.
                      format: date-time
                      type: string
                    createdBy:
                      description: The identifier for the user who created the category.
                      type: string
                    link:
                      description: The location of the navigable resource within this API, for use by API clients.
                      nullable: true
                      type: string
                    lockVersion:
                      description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                      type: number
                    updateDate:
                      description: The ISO 6801 timestamp indicating when you last modified the category.
                      format: date-time
                      type: string
                    updatedBy:
                      description: The identifier for the user who last modified the category.
                      type: string
                    usageCount:
                      description: The number of endpoints that share the category.
                      type: integer
                  x-akamai:
                    file-path: schemas/categoryDto.yaml
                x-akamai:
                  file-path: schemas/categoryDtos.yaml
              example:
              - apiCategoryDescription: The applications related to the IT department.
                apiCategoryId: 9903
                apiCategoryName: IT
                createDate: 2019-06-17T12:42:42+0000
                createdBy: mrossi
                link: /api-definitions/v1/api-categories/9903
                lockVersion: 0
                updateDate: 2019-06-17T12:42:42+0000
                updatedBy: bookstore_admin
              - apiCategoryDescription: The applications for internal use only.
                apiCategoryId: 9904
                apiCategoryName: Internal
                createDate: 2019-06-17T12:43:11+0000
                createdBy: mrossi
                link: /api-definitions/v1/api-categories/9904
                lockVersion: 0
                updateDate: 2019-06-17T12:43:11+0000
                updatedBy: bookstore_admin
              - apiCategoryDescription: The applications related to the Sales department.
                apiCategoryId: 9902
                apiCategoryName: Sales
                createDate: 2019-06-17T12:40:14+0000
                createdBy: tyamada
                link: /api-definitions/v1/api-categories/9902
                lockVersion: 0
                updateDate: 2019-06-17T12:40:14+0000
                updatedBy: bookstore_admin
        '403':
          description: You don't have permission to retrieve API endpoint category list.
          content:
            application/problem+json:
              example:
                detail: You don't have access to the endpoint.
                instance: https://problems.luna.akamaiapis.net/api-defintions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                status: 403
                title: Unauthorized Access/Action
                type: https://problems.luna.akamaiapis.net/api-defintions/error-types/UNAUTHORIZED
              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: Whether the response should include the `usageCount` data indicating the number of endpoints under a category, `false` by default.
        example: '{{withUsageInfo}}'
        in: query
        name: withUsageInfo
        required: true
        schema:
          default: false
          type: boolean
        x-akamai:
          file-path: parameters/withUsageInfo-query.yaml
      - 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
  /categories/{apiCategoryId}:
    parameters:
    - description: The unique identifier for the category.
      example: '{{apiCategoryId}}'
      in: path
      name: apiCategoryId
      required: true
      schema:
        type: integer
      x-akamai:
        file-path: parameters/apiCategoryId-path.yaml
    get:
      description: Returns a specific category that you can use to tag endpoints.
      operationId: get-category
      summary: Get a category
      tags:
      - Categories
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/get-category
      responses:
        '200':
          description: Response data shows the category.
          content:
            application/json:
              example:
                apiCategoryDescription: The applications related to the Sales department.
                apiCategoryId: 9902
                apiCategoryName: Sales
                createDate: 2019-06-17T12:40:14+0000
                link: /api-definitions/v2/categories/9902
                lockVersion: 0
                updateDate: 2019-06-17T12:40:14+0000
              schema:
                additionalProperties: false
                description: Contains information about an endpoint category.
                type: object
                required:
                - apiCategoryName
                properties:
                  apiCategoryDescription:
                    description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                    type: string
                  apiCategoryId:
                    description: The unique identifier for the category.
                    type: integer
                  apiCategoryName:
                    description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                    type: string
                  createDate:
                    description: The ISO 6801 timestamp indicating when you created the category.
                    format: date-time
                    type: string
                  createdBy:
                    description: The identifier for the user who created the category.
                    type: string
                  link:
                    description: The location of the navigable resource within this API, for use by API clients.
                    nullable: true
                    type: string
                  lockVersion:
                    description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                    type: number
                  updateDate:
                    description: The ISO 6801 timestamp indicating when you last modified the category.
                    format: date-time
                    type: string
                  updatedBy:
                    description: The identifier for the user who last modified the category.
                    type: string
                  usageCount:
                    description: The number of endpoints that share the category.
                    type: integer
                x-akamai:
                  file-path: schemas/categoryDto.yaml
        '403':
          description: You don't have permission to get the API endpoint category.
          content:
            application/problem+json:
              example:
                detail: You don't have access to the endpoint.
                instance: https://problems.luna.akamaiapis.net/api-defintions/error-instances/d54686b5-21cb-4ab7-a8d6-a92282cf1749
                status: 403
                title: Unauthorized Access/Action
                type: https://problems.luna.akamaiapis.net/api-defintions/error-types/UNAUTHORIZED
              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 category doesn't exist.
          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 a category's description or unique name.
      operationId: put-category
      summary: Edit a category
      tags:
      - Categories
      externalDocs:
        description: See documentation for this operation in Akamai's API Endpoint Definition API
        url: https://techdocs.akamai.com/api-definitions/reference/put-category
      requestBody:
        required: true
        content:
          application/json:
            example:
              apiCategoryDescription: The applications related to the Sales department.
              apiCategoryId: 9902
              apiCategoryName: Sales
              createDate: 2019-06-17T12:40:14+0000
              link: /api-definitions/v2/categories/9902
              lockVersion: 0
              updateDate: 2019-06-17T12:40:14+0000
            schema:
              additionalProperties: false
              description: Contains information about an endpoint category.
              type: object
              required:
              - apiCategoryName
              properties:
                apiCategoryDescription:
                  description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                  example: '{{apiCategoryDescription}}'
                  type: string
                apiCategoryId:
                  description: The unique identifier for the category.
                  example: '{{apiCategoryId}}'
                  readOnly: true
                  type: integer
                apiCategoryName:
                  description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                  example: '{{apiCategoryName}}'
                  type: string
                createDate:
                  description: The ISO 6801 timestamp indicating when you created the category.
                  example: '{{createDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                createdBy:
                  description: The identifier for the user who created the category.
                  example: '{{createdBy}}'
                  readOnly: true
                  type: string
                link:
                  description: The location of the navigable resource within this API, for use by API clients.
                  example: '{{link}}'
                  readOnly: true
                  type: string
                lockVersion:
                  description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                  example: '{{lockVersion}}'
                  readOnly: true
                  type: number
                updateDate:
                  description: The ISO 6801 timestamp indicating when you last modified the category.
                  example: '{{updateDate}}'
                  format: date-time
                  readOnly: true
                  type: string
                updatedBy:
                  description: The identifier for the user who last modified the category.
                  example: '{{updatedBy}}'
                  readOnly: true
                  type: string
                usageCount:
                  description: The number of endpoints that share the category.
                  example: '{{usageCount}}'
                  readOnly: true
                  type: integer
              x-akamai:
                file-path: schemas/categoryDtoPut.yaml
      responses:
        '200':
          description: The response shows the updated category.
          content:
            application/json:
              example:
                apiCategoryDescription: The applications related to the Sales department.
                apiCategoryId: 9902
                apiCategoryName: Sales
                createDate: 2019-06-17T12:40:14+0000
                link: /api-definitions/v2/categories/9902
                lockVersion: 0
                updateDate: 2019-06-17T12:40:14+0000
              schema:
                additionalProperties: false
                description: Contains information about an endpoint category.
                type: object
                required:
                - apiCategoryName
                properties:
                  apiCategoryDescription:
                    description: The description of the category that you may use to tag related endpoints. If you specify `null` or an empty string in the request, the JSON response doesn't include this field.
                    type: string
                  apiCategoryId:
                    description: The unique identifier for the category.
                    type: integer
                  apiCategoryName:
                    description: The unique-per-account name of the category. Any empty value reflects back as an `__UNCATEGORIZED__` keyword.
                    type: string
                  createDate:
                    description: The ISO 6801 timestamp indicating when you created the category.
                    format: date-time
                    type: string
                  createdBy:
                    description: The identifier for the user who created the category.
                    type: string
                  link:
                    description: The location of the navigable resource within this API, for use by API clients.
                    nullable: true
                    type: string
                  lockVersion:
                    description: The identifier used for optimistic locking. See [Concurrency control](https://techdocs.akamai.com/api-definitions/reference/concurrency-control) for details.
                    type: number
                  updateDate:
                    description: The ISO 6801 timestamp indicating when you last modified the category.
                    format: date-time
                    type: string
                  updatedBy:
                    description: The identifier for the user who last modified the category.
                    type: string
                  usageCount:
                    description: The number of endpoints that share the category.
                    type: integer
                x-akamai:
                  file-path: schemas/categoryDto.yaml
        '400':
          description: Some of the request input is invalid.
          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:
                    descri

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