Tyk OAS APIs API

openapi: 3.2.0
info:
  contact:
    email: support@tyk.io
    name: Tyk Technologies
    url: https://tyk.io/contact
  description: '

    ## <a name="introduction"></a> Introduction


    The Tyk Dashboard API offers granular, programmatic access to a centralised database of resources that your Tyk nodes can pull from. This API has a dynamic user administrative structure which means the secret key that is used to communicate with your Tyk nodes can be kept secret and access to the wider management functions can be handled on a user-by-user and organisation-by-organisation basis.


    A common question around using a database-backed configuration is how to programmatically add API definitions to your Tyk nodes, the Dashboard API allows much more fine-grained, secure and multi-user access to your Tyk cluster, and should be used to manage a database-backed Tyk node.


    The Tyk Dashboard API works seamlessly with the Tyk Dashboard (and the two come bundled together).


    ## <a name="security-hierarchy"></a> Security Hierarchy


    The Dashboard API provides a more structured security layer to managing Tyk nodes.


    ### Organisations, APIs and Users


    With the Dashboard API and a database-backed Tyk setup, (and to an extent with file-based API setups - if diligence is used in naming and creating definitions), the following security model is applied to the management of Upstream APIs:


    * **Organisations**: All APIs are *owned* by an organisation, this is designated by the ''OrgID'' parameter in the API Definition.

    * **Users**: All users created in the Dashboard belong to an organisation (unless an exception is made for super-administrative access).

    * **APIs**: All APIs belong to an Organisation and only Users that belong to that organisation can see the analytics for those APIs and manage their configurations.

    * **API Keys**: API Keys are designated by organisation, this means an API key that has full access rights will not be allowed to access the APIs of another organisation on the same system, but can have full access to all APIs within the organisation.

    * **Access Rights**: Access rights are stored with the key, this enables a key to give access to multiple APIs, this is defined by the session object in the core Tyk API.


    In order to use the Dashboard API, you''ll need to get the ''Tyk Dashboard API Access Credentials'' secret from your user profile on the Dashboard UI.


    The secret you set should then be sent along as a header with each Dashboard API Request in order for it to be successful:



    authorization: <your-secret>

    '
  license:
    name: Mozilla Public License Version 2.0
    url: https://github.com/TykTechnologies/tyk/blob/master/LICENSE.md
  title: Tyk Dashboard OAS APIs API
  version: 5.7.1
servers:
- url: https://{tenant}
  variables:
    tenant:
      default: localhost:8080
      description: Your dashboard host
security:
- bearerAuth: []
tags:
- description: Tyk allows you to work with APIs that you ve designed with the OpenAPI Specification version 3.0.x, making it even easier to get your API up and running. Use the endpoints in this tag to create,delete,import and update OAS APIs.
  externalDocs:
    description: Tyk OAS Documentation.
    url: https://tyk.io/docs/getting-started/key-concepts/high-level-concepts/
  name: OAS APIs
paths:
  /api/apis/oas:
    post:
      description: "Create an API Definition in Tyk OAS API format.\n Note that the response includes the newly created Tyk OAS API Definition containing the unique identifier for the API (`ID`). You can provide a value for `ID` in the request body, otherwise Tyk will automatically generate a value."
      operationId: createApiOAS
      parameters:
      - description: The base API which the new version will be linked to.
        example: 663a4ed9b6be920001b191ae
        in: query
        name: base_api_id
        required: false
        schema:
          type: string
      - description: The version name of the base API while creating the first version. This doesn't have to be sent for the next versions but if it is set, it will override base API version name.
        example: Default
        in: query
        name: base_api_version_name
        required: false
        schema:
          type: string
      - description: The version name of the created version.
        example: v2
        in: query
        name: new_version_name
        required: false
        schema:
          type: string
      - description: If true, the new version is set as default version.
        example: true
        in: query
        name: set_default
        required: false
        schema:
          type: boolean
      - $ref: '#/components/parameters/TemplateID'
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsersSample
                    responses:
                      '200':
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
              x-tyk-api-gateway:
                info:
                  name: user
                  state:
                    active: true
                server:
                  listenPath:
                    strip: true
                    value: /user-test/
                upstream:
                  url: https://localhost:8080
            schema:
              allOf:
              - $ref: https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
              - $ref: '#/components/schemas/XTykApiGateway'
      responses:
        '200':
          content:
            application/json:
              example:
                ID: 4c1c0d8fc885401053ddac4e39ef676b
                Message: API created
                Meta: 665597e0b646b300011acb69
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: OAS created.
        '400':
          content:
            application/json:
              example:
                Message: Couldn't read body.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Malformed data.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: Could not retrieve detail of apiID 62a0ec9092faf50001395817 in org 82a0ec9052faf50001395817.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              example:
                Message: Found API with the same ID.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Conflict
        '500':
          content:
            application/json:
              example:
                Message: Error while validating schema.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Create OAS API.
      tags:
      - OAS APIs
  /api/apis/oas/{apiId}:
    delete:
      description: Deleting an API definition will remove the file from the file store. The API definition will not be unloaded and a separate reload request will need to be made to disable the API endpoint.
      operationId: deleteOASApi
      parameters:
      - description: ID of the API you want to delete.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                Message: API deleted.
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Deleted successfully.
        '400':
          content:
            application/json:
              example:
                Message: Could not delete the API.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve API detail.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
      summary: Delete OAS API.
      tags:
      - OAS APIs
    get:
      description: Get a single API definition in OAS format.
      operationId: getOASAPIDetails
      parameters:
      - description: ID of the API you want to fetch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                oasExample:
                  $ref: '#/components/examples/oasExample'
              schema:
                allOf:
                - $ref: https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
                - $ref: '#/components/schemas/XTykApiGateway'
          description: Fetched API.
          headers:
            x-tyk-base-api-id:
              description: ID of the base API if the requested API is a version.
              schema:
                type: string
              style: simple
        '400':
          content:
            application/json:
              example:
                Message: Could not retrieve API detail.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Bad request or API not found.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal data for API detail.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Get OAS API details.
      tags:
      - OAS APIs
    patch:
      description: Update a Tyk OAS API. You can use this endpoint to update the OAS part of your Tyk OAS API definition. This endpoint allows you to configure the Tyk OAS extension based on the query parameters provided (similar to import).
      operationId: patchApiOAS
      parameters:
      - description: ID of the API you want to patch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/UpstreamURL'
      - $ref: '#/components/parameters/ListenPath'
      - $ref: '#/components/parameters/CustomDomain'
      - $ref: '#/components/parameters/AllowList'
      - $ref: '#/components/parameters/ValidateRequest'
      - $ref: '#/components/parameters/MockResponse'
      - $ref: '#/components/parameters/Authentication'
      requestBody:
        content:
          application/json:
            examples:
              PatchByUrl:
                summary: Patch By Url
                value:
                  url: https://gist.githubusercontent.com/lghiur/385183f81d0878e5806fffab843d2ef2/raw/1da0aa8b08b496e6c8c84c4996fad6c4877218a0/Petstore%2520Tyk%2520OAS%2520API%2520Definition
              PatchOASExample:
                summary: Patch Tyk Oas Example
                value:
                  components:
                    securitySchemes:
                      bearerAuth:
                        description: The API Access Credentials
                        scheme: bearer
                        type: http
                  info:
                    description: This is a sample OAS.
                    title: OAS Sample
                    version: 1.0.0
                  openapi: 3.0.3
                  paths:
                    /api/sample/users:
                      get:
                        operationId: getUsersSample
                        responses:
                          '200':
                            content:
                              application/json:
                                schema:
                                  items:
                                    properties:
                                      name:
                                        type: string
                                    type: object
                                  type: array
                            description: fetched users
                        summary: Get users
                        tags:
                        - users
                  security:
                  - bearerAuth: []
                  servers:
                  - url: https://localhost:8080
                  x-tyk-api-gateway:
                    info:
                      name: user
                      state:
                        active: true
                    server:
                      listenPath:
                        strip: true
                        value: /user-test/
                    upstream:
                      url: https://localhost:8080
            schema:
              oneOf:
              - $ref: '#/components/schemas/ApiImportByUrlPayload'
              - allOf:
                - $ref: https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
                - $ref: '#/components/schemas/XTykApiGateway'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FormDataFile'
        description: The content of the file should be the OpenAPI document in JSON format.
      responses:
        '200':
          content:
            application/json:
              example:
                Message: API updated
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Patched API.
        '400':
          content:
            application/json:
              example:
                Message: Invalid `ID` value
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Malformed request.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: Failed to update org object to DB.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden.
        '404':
          content:
            application/json:
              example:
                Message: API not found.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
      summary: Patch a single OAS API by ID.
      tags:
      - OAS APIs
    put:
      description: Updating an API definition uses the same signature object as a `POST`. It will first ensure that the API ID being updated is the same as in the `PUT` object.<br/> Updating will completely replace the file descriptor and will not change an API definition that has already been loaded. The hot-reload endpoint will need to be called to push the new definition to live.
      operationId: updateApiOAS
      parameters:
      - description: ID of the API you want to update.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              components:
                securitySchemes:
                  bearerAuth:
                    description: The API Access Credentials
                    scheme: bearer
                    type: http
              info:
                description: This is a sample OAS.
                title: OAS Sample
                version: 1.0.0
              openapi: 3.0.3
              paths:
                /api/sample/users:
                  get:
                    operationId: getUsersSample
                    responses:
                      '200':
                        content:
                          application/json:
                            schema:
                              items:
                                properties:
                                  name:
                                    type: string
                                type: object
                              type: array
                        description: fetched users
                    summary: Get users
                    tags:
                    - users
              security:
              - bearerAuth: []
              servers:
              - url: https://localhost:8080
              x-tyk-api-gateway:
                info:
                  name: user
                  state:
                    active: true
                server:
                  listenPath:
                    strip: true
                    value: /user-test/
                upstream:
                  url: https://localhost:8080
            schema:
              allOf:
              - $ref: https://raw.githubusercontent.com/TykTechnologies/tyk/refs/heads/master/apidef/oas/schema/3.0.json
              - $ref: '#/components/schemas/XTykApiGateway'
      responses:
        '200':
          content:
            application/json:
              example:
                Message: API updated.
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Updated API.
        '400':
          content:
            application/json:
              example:
                Message: The payload should contain x-tyk-api-gateway.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Malformed API data.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: Found API with same url.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: API definition does not exist
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
        '500':
          content:
            application/json:
              example:
                Message: Error while validating schema.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Update OAS API.
      tags:
      - OAS APIs
  /api/apis/oas/{apiId}/categories:
    get:
      description: Get a list of the API categories associated with the specified API.
      operationId: getApiCategories
      parameters:
      - description: ID of the API.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                categories:
                - developers
                - devops
                - research
              schema:
                $ref: '#/components/schemas/CategoriesPayload'
          description: Category fetched.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}/categories'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: API not found
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
        '500':
          content:
            application/json:
              example:
                Message: Failed to marshal categories payload.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Get OAS API's Categories.
      tags:
      - OAS APIs
    put:
      description: Update the list of API categories associated with the specified API.
      operationId: updateApiCategories
      parameters:
      - description: ID of the API.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              categories:
              - dev
              - testers
              - messages
            schema:
              $ref: '#/components/schemas/CategoriesPayload'
      responses:
        '200':
          content:
            application/json:
              example:
                Message: API categories updated.
                Meta: null
                Status: OK
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Categories updated.
        '400':
          content:
            application/json:
              example:
                Message: Failed to update ApiDef object to DB.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Malformed request data.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}/categories'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: API not found
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
        '500':
          content:
            application/json:
              example:
                Message: Failed to update ApiDef object to DB.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Internal server error.
      summary: Update OAS API categories.
      tags:
      - OAS APIs
  /api/apis/oas/{apiId}/export:
    get:
      description: Download API definition in OAS format (only APIs saved in OAS format). When you set the mode query parameter to public the OAS spec exported will exclude the x-tyk-api-gateway part. When mode query parameter is empty or is set to any other value apart from public then the exported OAS spec will include the x-tyk-api-gateway part.
      operationId: downloadApiOASPublic
      parameters:
      - description: ID of the API you want to export.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      - description: Mode of OAS export, by default mode could be empty which means to export OAS spec including OAS Tyk extension. When mode=public, OAS spec excluding Tyk extension is exported.
        example: public
        in: query
        name: mode
        required: false
        schema:
          enum:
          - public
          type: string
      responses:
        '200':
          content:
            application/octet-stream:
              schema:
                format: binary
                type: string
          description: Fetched successfully.
        '400':
          content:
            application/json:
              example:
                Message: Could not retrieve API detail.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}/export'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
      summary: Export OAS API.
      tags:
      - OAS APIs
  /api/apis/oas/{apiId}/versions:
    get:
      description: List all the  versions of an OAS API.
      operationId: listOASApiVersions
      parameters:
      - description: ID of the API you want to fetch.
        example: 4c1c0d8fc885401053ddac4e39ef676b
        in: path
        name: apiId
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/SearchText'
      - $ref: '#/components/parameters/AccessType'
      responses:
        '200':
          content:
            application/json:
              example:
                apis:
                - expirationDate: 2024-11-30 12:00
                  id: 5b633de8673e40e44bc88b6b248f0937
                  internal: false
                  isDefaultVersion: true
                  name: user
                  versionName: Default
                - expirationDate: 2024-11-30 12:00
                  id: 0fec4eb890cf4b8c5cb6fc011456c315
                  internal: false
                  isDefaultVersion: false
                  name: user
                  versionName: v2
                pages: 1
              schema:
                $ref: '#/components/schemas/VersionMetas'
          description: Version fetched.
        '401':
          content:
            application/json:
              example:
                Message: Not authorised
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                Message: 'access denied: You do not have permission to access  /api/apis/oas/{apiId}/versions'
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              example:
                Message: Could not retrieve API detail.
                Meta: null
                Status: Error
              schema:
                $ref: '#/components/schemas/ApiResponse'
          description: API not found.
      summary: List OAS API versions.
      tags:
      - OAS APIs
  /api/apis/oas/dry-run:
    post:
      description: 'Generate a Tyk OAS API definition without saving it to the Dashboard database.

        This endpoint is used to produce a Tyk OAS API definition without creating the API proxy itself. This provides a dry run functionality for Tyk OAS API creation, showing what would be created in the Dashboard given the set of inputs provided.'
      operationId: dryRunApiOAS
      parameters:
      - $ref: '#/components/parameters/TemplateID'
      - description: The base API which the new version will be linked to.
        example: 663a4ed9b6be920001b191ae
        in: query
        name: base_api_id
        require

# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tyk/refs/heads/main/openapi/tyk-oas-apis-api-openapi.yml