# Copyright 2025 Deutsche Telekom IT GmbH # # SPDX-License-Identifier: Apache-2.0 openapi: 3.0.3 info: title: Stargate Api description: > API of the TARDIS control plane. With this API, you can manage your ApiExposures and ApiSubscriptions. This is a **read-only** API. You can only read the resources. For creating and updating resources, you may use the Rover-API. **Important:** - You may use this API by subscribing to it by using the usual process. You **do not** need to add `scopes` as the default scope is set to `tardis:user:read`. If you require more permissions, please contact the TARDIS team. - This is a Team-API and may be used by any team using TARDIS. In the future, you can simply use your Team-credentials to access this API. contact: name: TARDIS url: https://developer.telekom.de/docs/src/tardis_customer_handbook/support/ email: FMB_TARDIS_Support@telekom.de version: 2.0.0 x-api-category: TARDIS servers: - url: https://api.telekom.de/stargate/v2 security: - OAuth2: - tardis:admin:all tags: - name: ApiExposure description: | With an ApiExposure you can define and API you want to expose on TARDIS, to provide it to other consumers. It is only possible to expose the entire API. It is not possible to expose a single resource. Therefore, every exposure needs the API Base Path which you can find in the Open API Specification File of your API and the upstream URL. - name: ApiSubscription description: | After an API is successful subscribed, you are able to use the API. It is only possible to subscribe to the entire API. It is not possible to subscribe only to a single resource paths: /applications/{applicationId}/apiexposures: get: tags: - ApiExposure summary: Find all ApiExposures description: Find all ApiExposures of this application operationId: getAllApiExposures parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - $ref: 'common.yaml#/components/parameters/Limit' - $ref: 'common.yaml#/components/parameters/Offset' - $ref: 'common.yaml#/components/parameters/Sort' responses: '200': description: OK headers: X-Total-Count: $ref: 'common.yaml#/components/headers/XTotalCount' X-Result-Count: $ref: 'common.yaml#/components/headers/XResultCount' content: application/json: schema: $ref: '#/components/schemas/ApiExposureListResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated post: deprecated: true tags: - ApiExposure summary: Create an ApiExposures description: | Creating and updating resources is asynchronous, which is why the status is given as an answer to a POST/PUT request, since it is possible that the resource to be created has not yet been processed at the time the response is created. If the status after creation is in state "Processing", the resource must be queried with GET to see whether it was created successfully or whether errors/warnings are written in the status. If the creation/update is incorrect, the processing status will be set to blocked. Otherwise to "failed". Status 201 means, that we accepted the request and there are no syntactic or semantic errors, but there can occur failures in the after processing. That will be shown in the status if you request the appropriate resource. operationId: createApiExposure parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiExposureCreateRequest' responses: '202': description: ACCEPTED content: application/json: schema: $ref: '#/components/schemas/ApiExposureResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all /applications/{applicationId}/apiexposures/{apiExposureName}: get: tags: - ApiExposure summary: Find an existing ApiExposure description: Find an existing ApiExposure operationId: getApiExposure parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiExposureName description: The name of the ApiExposure in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiExposureResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated put: deprecated: true tags: - ApiExposure summary: Update an existing ApiExposure description: | Creating and updating resources is asynchronous, which is why the status is given as an answer to a POST/PUT request, since it is possible that the resource to be created has not yet been processed at the time the response is created. If the status after creation is in state "Processing", the resource must be queried with GET to see whether it was created successfully or whether errors/warnings are written in the status. If the creation/update is incorrect, the processing status will be set to blocked. Otherwise to "failed". Status 201 means, that we accepted the request and there are no syntactic or semantic errors, but there can occur failures in the after processing. That will be shown in the status if you request the appropriate resource. operationId: updateApiExposure parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiExposureName in: path description: The name of the ApiExposure required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiExposureUpdateRequest' responses: '202': description: ACCEPTED content: application/json: schema: $ref: '#/components/schemas/ApiExposureResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all delete: deprecated: true tags: - ApiExposure summary: Delete an ApiExposure description: Delete an ApiExposure operationId: deleteApiExposure parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiExposureName in: path description: The name of the ApiExposure required: true schema: type: string responses: '204': description: DELETED '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all /applications/{applicationId}/apiexposures/{apiExposureName}/status: get: tags: - ApiExposure summary: Find an existing ApiExposure and return its status description: Find an existing ApiExposure and return its status operationId: getApiExposureStatus parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiExposureName description: The name of the ApiExposure in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: 'common.yaml#/components/schemas/ResourceStatusResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated /applications/{applicationId}/apisubscriptions: get: tags: - ApiSubscription summary: Find all ApiSubscriptions description: Find all ApiSubscriptions of this application operationId: getAllApiSubscriptions parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - $ref: 'common.yaml#/components/parameters/Limit' - $ref: 'common.yaml#/components/parameters/Offset' - $ref: 'common.yaml#/components/parameters/Sort' responses: '200': description: OK headers: X-Total-Count: $ref: 'common.yaml#/components/headers/XTotalCount' X-Result-Count: $ref: 'common.yaml#/components/headers/XResultCount' content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionListResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated post: deprecated: true tags: - ApiSubscription summary: Create an ApiSubscription description: | Creating and updating resources is asynchronous, which is why the status is given as an answer to a POST/PUT request, since it is possible that the resource to be created has not yet been processed at the time the response is created. If the status after creation is in state "Processing", the resource must be queried with GET to see whether it was created successfully or whether errors/warnings are written in the status. If the creation/update is incorrect, the processing status will be set to blocked. Otherwise to "failed". Status 201 means, that we accepted the request and there are no syntactic or semantic errors, but there can occur failures in the after processing. That will be shown in the status if you request the appropriate resource. operationId: createApiSubscription parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionCreateRequest' responses: '202': description: ACCEPTED content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all /applications/{applicationId}/apisubscriptions/{apiSubscriptionName}: get: tags: - ApiSubscription summary: Find an existing ApiSubscription description: Find an existing ApiSubscription operationId: getApiSubscription parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiSubscriptionName description: The name of the ApiSubscription in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated put: deprecated: true tags: - ApiSubscription summary: Update an existing ApiSubscription description: | Creating and updating resources is asynchronous, which is why the status is given as an answer to a POST/PUT request, since it is possible that the resource to be created has not yet been processed at the time the response is created. If the status after creation is in state "Processing", the resource must be queried with GET to see whether it was created successfully or whether errors/warnings are written in the status. If the creation/update is incorrect, the processing status will be set to blocked. Otherwise to "failed". Status 201 means, that we accepted the request and there are no syntactic or semantic errors, but there can occur failures in the after processing. That will be shown in the status if you request the appropriate resource. operationId: updateApiSubscription parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiSubscriptionName in: path description: The name of the ApiSubscription required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionUpdateRequest' responses: '200': description: UPDATE content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all delete: deprecated: true tags: - ApiSubscription summary: Delete an ApiSubscription description: Delete an ApiSubscription operationId: deleteApiSubscription parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiSubscriptionName in: path description: The name of the ApiSubscription required: true schema: type: string responses: '204': description: DELETED '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:hub:all - tardis:team:all - tardis:user:all /applications/{applicationId}/apisubscriptions/{apiSubscriptionName}/status: get: tags: - ApiSubscription summary: Find an existing ApiSubscription and return its status description: Find an existing ApiSubscription and return its status operationId: getApiSubscriptionStatus parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiSubscriptionName description: The name of the ApiSubscription in: path required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: 'common.yaml#/components/schemas/ResourceStatusResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '404': $ref: 'common.yaml#/components/responses/NotFound' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated /applications/{applicationId}/apiexposures/{apiExposureName}/apisubscriptions: get: tags: - ApiExposure summary: Find all ApiSubscriptions of this ApiExposure description: Find all ApiSubscriptions of this ApiExposure operationId: getAllExposureApiSubscriptions parameters: - $ref: 'common.yaml#/components/parameters/ApplicationId' - name: apiExposureName description: The name of the ApiExposure in: path required: true schema: type: string - $ref: 'common.yaml#/components/parameters/Limit' - $ref: 'common.yaml#/components/parameters/Offset' - $ref: 'common.yaml#/components/parameters/Sort' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ApiSubscriptionListResponse' '400': $ref: 'common.yaml#/components/responses/BadRequest' '401': $ref: 'common.yaml#/components/responses/Unauthorized' '403': $ref: 'common.yaml#/components/responses/Forbidden' '415': $ref: 'common.yaml#/components/responses/UnsupportedMediaType' '500': $ref: 'common.yaml#/components/responses/ServerError' security: - OAuth2: - tardis:admin:all - tardis:admin:read - tardis:admin:obfuscated - tardis:supervisor:read - tardis:hub:all - tardis:hub:read - tardis:hub:obfuscated - tardis:team:all - tardis:team:read - tardis:team:obfuscated - tardis:user:all - tardis:user:read - tardis:user:obfuscated components: schemas: ApiExposure: type: object properties: basePath: type: string pattern: ^\/[a-zA-Z0-9\/-]*$ upstream: type: string format: uri variant: type: string description: | Defines the type of API exposure and determines which gateway the route should be provisioned on. Supported values: - null or 'DEFAULT': Regular API exposure on Stargate gateway (backward compatible) - 'MCP': MCP exposure provisioned on aiGateway - 'TELECONTEXTMCP': MCP exposure on aiGateway with automatic Telecontext integration enum: - DEFAULT - MCP - TELECONTEXTMCP example: DEFAULT approval: $ref: '#/components/schemas/ApprovalStrategy' rateLimit: $ref: '#/components/schemas/RateLimit' visibility: $ref: '#/components/schemas/Visibility' security: $ref: '#/components/schemas/SubscriberSecurity' failover: $ref: '#/components/schemas/ExposureFailover' loadBalancing: $ref: '#/components/schemas/LoadBalancing' trustedTeams: type: array items: $ref: 'common.yaml#/components/schemas/TeamRef' removeHeaders: type: array items: type: string ApiExposureCreateRequest: type: object required: - basePath - upstream - visibility allOf: - $ref: '#/components/schemas/ApiExposure' ApiExposureListResponse: properties: paging: $ref: 'common.yaml#/components/schemas/Paging' _links: $ref: 'common.yaml#/components/schemas/Links' items: type: array items: $ref: '#/components/schemas/ApiExposureResponse' ApiExposureResponse: type: object readOnly: true required: - name - zone - basePath - upstream - visibility allOf: - $ref: '#/components/schemas/ApiExposure' - properties: name: type: string readOnly: true example: eni-heartbeat-v1 zone: type: string readOnly: true status: $ref: 'common.yaml#/components/schemas/Status' ApiExposureUpdateRequest: type: object required: - upstream - basePath - approval - visibility allOf: - $ref: '#/components/schemas/ApiExposure' ApiSubscription: type: object properties: basePath: description: Must match pattern ^\/[a-zA-Z0-9\/-]*$ type: string example: /my-hub/my-app/v1 pattern: ^\/[a-zA-Z0-9\/-]*$ security: $ref: '#/components/schemas/SubscriberSecurity' ApiSubscriptionCreateRequest: required: - basePath type: object allOf: - $ref: '#/components/schemas/ApiSubscription' ApiSubscriptionListResponse: properties: paging: $ref: 'common.yaml#/components/schemas/Paging' _links: $ref: 'common.yaml#/components/schemas/Links' items: type: array items: $ref: '#/components/schemas/ApiSubscriptionResponse' ApiSubscriptionResponse: type: object readOnly: true allOf: - $ref: '#/components/schemas/ApiSubscription' - properties: name: type: string readOnly: true example: eni-echo-v1 zone: type: string readOnly: true gatewayUrl: type: string readOnly: true example: https://stargate-playground.live.dhei.telekom.de/eni/echo/v1 status: $ref: 'common.yaml#/components/schemas/Status' application: $ref: 'common.yaml#/components/schemas/ApplicationRef' team: $ref: 'common.yaml#/components/schemas/TeamRef' approval: $ref: '#/components/schemas/Approval' failover: $ref: '#/components/schemas/SubscriptionFailover' ApiSubscriptionUpdateRequest: required: - basePath type: object allOf: - $ref: '#/components/schemas/ApiSubscription' Approval: type: object readOnly: true required: - status - comment properties: status: type: string example: granted comment: type: string example: trusted team decider: type: string example: hyperion@telekom.de timestamp: type: string format: date-time example: '2022-09-28T16:05:46.384Z' ApprovalStrategy: enum: - AUTO - SIMPLE - FOUREYES type: string OAuth2: type: object required: - type properties: type: type: string enum: - oauth2 tokenEndpoint: type: string clientId: type: string clientSecret: type: string scopes: type: array items: type: string username: type: string password: type: string refreshToken: type: string grantType: type: string tokenRequest: type: string enum: - body - header description: >- Specifies if the authentication data should be sent to the external IDP via headers or in the body of the request BasicAuth: type: object required: - type - username - password properties: type: type: string enum: - basicAuth username: type: string password: type: string RateLimit: type: object properties: second: format: int32 type: integer minute: format: int32 type: integer hour: format: int32 type: integer faultTolerant: type: boolean hideClientHeaders: type: boolean SubscriberSecurity: discriminator: propertyName: type mapping: oauth2: '#/components/schemas/OAuth2' basicAuth: '#/components/schemas/BasicAuth' oneOf: - $ref: '#/components/schemas/OAuth2' - $ref: '#/components/schemas/BasicAuth' Visibility: enum: - ENTERPRISE - WORLD - ZONE type: string SubscriptionFailover: type: array readOnly: true items: type: object properties: zone: type: string readOnly: true example: aws gatewayUrl: type: string readOnly: true example: https://stargate-playground.live.dhei.telekom.de/eni/echo/v1 ExposureFailover: type: object properties: zone: type: string example: aws LoadBalancing: type: object readOnly: true properties: servers: type: array readOnly: true items: $ref: '#/components/schemas/Server' Server: type: object readOnly: true properties: upstream: type: string readOnly: true weight: type: integer readOnly: true