Cortex Docs API

openapi: 3.2.0
info:
  description: The Cortex REST API provides programmatic access to the data in the catalog, Scorecards, and more.
  title: Cortex Docs API
  version: v1
servers:
- url: https://api.getcortexapp.com
  description: Cortex Cloud API host
security:
- bearerAuth: []
tags:
- name: Docs
paths:
  /api/v1/catalog/{tagOrId}/documentation/openapi:
    delete:
      operationId: deleteOpenApiDocForEntity
      parameters:
      - description: The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.
        in: path
        name: tagOrId
        required: true
        schema:
          type: string
          description: Entity identifier - can be a tag or CID
      responses:
        '204':
          description: Successfully deleted documentation
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Delete OpenAPI docs for entity
      tags:
      - Docs
      x-cortex-mcp-description: Cortex Entity API Docs - Read the OpenAPI document registered against an entity
      x-cortex-mcp-enabled: 'false'
    get:
      operationId: getOpenApiDocForEntity
      parameters:
      - description: The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.
        in: path
        name: tagOrId
        required: true
        schema:
          type: string
          description: Entity identifier - can be a tag or CID
      - description: Name of the OpenAPI spec to return. If you have multiple OpenAPI specs configured for your entity as `x-cortex-links`, use this parameter to ensure the correct spec is returned. If this parameter is not specified, we will return the first OpenAPI spec found.
        in: query
        name: name
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecification'
          description: Successfully found documentation
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Documentation not found
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Retrieve OpenAPI docs for entity
      tags:
      - Docs
      x-cortex-mcp-description: Get the OpenAPI document registered against an entity - the API the service actually exposes. Distinct from the entity's Cortex descriptor, which getEntityDescriptor returns.
      x-cortex-mcp-enabled: 'true'
    put:
      operationId: updateOpenApiDocForEntity
      parameters:
      - description: The tag (`x-cortex-tag`) or unique, auto-generated identifier (CID) for the entity. If the tag contains forward slashes, URL-encode each `/` as `%2F`. The tag is matched exactly as encoded, including leading, trailing, and consecutive slashes, which are preserved and not collapsed (for example, the tag `/services/payments-api` is referenced as `%2Fservices%2Fpayments-api`). Tags containing slashes are supported via the API but not in the Cortex UI; this difference is expected.
        in: path
        name: tagOrId
        required: true
        schema:
          type: string
          description: Entity identifier - can be a tag or CID
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpenAPISpecification'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAPISpecification'
          description: Successfully updated documentation
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Update OpenAPI docs for entity
      tags:
      - Docs
      x-cortex-mcp-description: Set the OpenAPI document an entity exposes; the spec is a JSON or YAML string. It replaces any OpenAPI document previously set through the API. If the entity has none yet, one is created. Returns 400 if the spec cannot be parsed. This changes the API documentation only, not the entity's Cortex descriptor; for that, use createOrUpdateEntity or createOrPatchEntity.
      x-cortex-mcp-enabled: 'true'
components:
  schemas:
    OpenAPISpecification:
      required:
      - spec
      type: object
      properties:
        spec:
          type: string
          description: Stringified JSON representation of the OpenAPI spec
    TooManyRequestsProblemDetail:
      required:
      - type
      - title
      - status
      type: object
      properties:
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        retryAfter:
          minimum: 0
          type: integer
          description: The number of seconds until the rate limiting resets.
          format: int32
        status:
          maximum: 599
          minimum: 100
          type: integer
          format: int32
          enum:
          - 429
        title:
          type: string
        type:
          type: string
          format: uri-reference
    ErrorResponse:
      required:
      - message
      - type
      type: object
      properties:
        details:
          type: string
        errorCode:
          type: string
        gatewayHttpStatus:
          type: integer
          format: int32
        httpStatus:
          type: integer
          format: int32
        message:
          type: string
        requestId:
          type: string
        type:
          type: string
          enum:
          - INTEGRATION_MISSING
          - INTEGRATION_UNREGISTERED
          - INTEGRATION_UNSUPPORTED
          - INTEGRATION_GRAPHQL_ERROR
          - INTEGRATION_BAD_REQUEST
          - INTEGRATION_UNAUTHORIZED
          - INTEGRATION_FORBIDDEN
          - INTEGRATION_NOT_FOUND
          - INTEGRATION_UNPROCESSABLE_CONTENT
          - INTEGRATION_RATE_LIMITED
          - INTEGRATION_INTERNAL_ERROR
          - INTEGRATION_NOT_IMPLEMENTED
          - INTEGRATION_BAD_GATEWAY
          - INTEGRATION_UNAVAILABLE
          - INTEGRATION_GATEWAY_TIMEOUT
          - INTEGRATION_TIMED_OUT
          - INTEGRATION_CACHE_ERROR
          - INTEGRATION_UNHANDLED_HTTP_ERROR
          - INTEGRATION_UNHANDLED_EXCEPTION
          - INTEGRATION_UNEXPECTED_ERROR
          - ILLEGAL_ARGUMENT_ERROR
          - BAD_REQUEST
          - FORBIDDEN
          - NOT_FOUND
          - REQUEST_TIMEOUT
          - CONFLICT
          - UNHANDLED_EXCEPTION
          - UNCATEGORIZED
          - SERVICE_CREATOR
          - UNKNOWN_HOST
          - TOO_MANY_REQUESTS
  responses:
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsProblemDetail'
      description: The client has exceeded the rate limit by performing too many requests in a short period. Retry the request after a delay.
      headers:
        Retry-After:
          description: The number of seconds until the rate limiting resets.
          schema:
            minimum: 0
            type: integer
            format: int32
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      description: 'All requests to the Cortex API need to provide an `Authorization: Bearer <token>` header, where `<token>` is an API key created in the Settings page of your workspace.'
      scheme: bearer
      type: http
x-provenance:
  method: harvested
  publisher: Cortex
  source: https://docs.cortex.io/openapi/cortex_swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)