Add an API
Adds a REST API by its OpenAPI description. Each operation becomes a tool at {gateway_url}/mcp, named with the API’s name, a hyphen, and the lowercased operationId. A description the gateway cannot fetch yields an API with no tools. The instance must be ready; otherwise the request answers 409.
{
"data": {
"id": "dbe53cc0-bf7e-4f7a-8d84-752d19890eb3",
"name": "petstore",
"spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
"base_url": "https://petstore3.swagger.io/api/v3",
"auth": {
"type": "none"
},
"tools": [],
"static_headers": {},
"forwarded_headers": [],
"open_to_every_key": true,
"created_at": "2026-10-28T17:07:27.083000Z",
"updated_at": "2026-10-28T17:07:27.083000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10032",
"title": "Invalid enumerated value",
"detail": "Input tag does not match any of the expected tags: 'none', 'api_key', 'bearer_token', 'basic', 'token', 'authorization', 'oauth_client_credentials', 'passthrough'",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10032"
},
"source": {
"pointer": "/auth"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}Authorizations
Telnyx API key
Path Parameters
The Agent Gateway's id.
Body
A name for the API, unique on the instance across MCP servers and APIs, regardless of case. Up to 100 letters, digits, _, and .. The gateway prefixes the API's tools with it and a hyphen.
^[A-Za-z0-9_.]{1,100}$The URL of the API's OpenAPI description: OpenAPI 3.0, OpenAPI 3.1, or Swagger 2.0.
Where the gateway sends the API's requests. Without it, the gateway takes the description's first servers entry.
How the gateway authenticates to the API. AWS Signature Version 4 is for MCP servers only. Replaced whole on an update.
- No authentication
- API key
- OAuth client credentials
- Token passthrough
Show child attributes
Show child attributes
The operations the API exposes as tools, by tool name. [] exposes every operation.
Headers sent on every request.
Show child attributes
Show child attributes
Headers copied from the agent's request, by name.
32true lets every key on the instance use the server, granted or not.
Response
The added API
Show child attributes
Show child attributes
Was this page helpful?
{
"data": {
"id": "dbe53cc0-bf7e-4f7a-8d84-752d19890eb3",
"name": "petstore",
"spec_url": "https://petstore3.swagger.io/api/v3/openapi.json",
"base_url": "https://petstore3.swagger.io/api/v3",
"auth": {
"type": "none"
},
"tools": [],
"static_headers": {},
"forwarded_headers": [],
"open_to_every_key": true,
"created_at": "2026-10-28T17:07:27.083000Z",
"updated_at": "2026-10-28T17:07:27.083000Z"
}
}{
"errors": [
{
"code": "10012",
"title": "Duplicate resource",
"detail": "Resource is a duplicate.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10012"
},
"source": {
"pointer": "/name"
}
}
]
}{
"errors": [
{
"code": "10009",
"title": "Authentication failed",
"detail": "The required authentication headers were either invalid or not included in the request.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10009"
}
}
]
}{
"errors": [
{
"code": "10005",
"title": "Resource not found",
"detail": "The requested resource or URL could not be found.",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10005"
}
}
]
}{
"errors": [
{
"code": "99901",
"title": "Instance not ready",
"detail": "The instance is not ready; its engine is not running."
}
]
}{
"errors": [
{
"code": "10032",
"title": "Invalid enumerated value",
"detail": "Input tag does not match any of the expected tags: 'none', 'api_key', 'bearer_token', 'basic', 'token', 'authorization', 'oauth_client_credentials', 'passthrough'",
"meta": {
"url": "https://developers.telnyx.com/docs/overview/errors/10032"
},
"source": {
"pointer": "/auth"
}
}
]
}{
"errors": [
{
"code": "99903",
"title": "Engine unavailable",
"detail": "The instance's engine did not answer; try again shortly."
}
]
}