Tyk OAS APIs API

openapi: 3.0.0
info:
  title: Tyk Dashboard Admin Additional Permissions OAS APIs API
  version: 5.3.0
  description: 'For Tyk On-Premises installations only, the Dashboard Admin API has two endpoints and is used to set up and provision a Tyk Dashboard instance without the command line.


    In order to use the Dashboard Admin API, you''ll need to get the `admin_secret` value from your Tyk Dashboard configurations.


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


    ```

    admin-auth: <your-secret>

    ```'
servers:
- url: http://localhost/
- url: https://localhost/
security:
- ApiKeyAuth: []
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
        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/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:
            example:
              oas:
                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: getUsersOperation
                      responses:
                        '200':
                          content:
                            application/json:
                              schema:
                                items:
                                  properties:
                                    name:
                                      type: string
                                  type: object
                                type: array
                   

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