Mount a Connector | SpeechifyAI API

Publish a connector’s operations onto the API in one call: one tool route per operation of an openapi tool definition, or per tool its mcp server lists, named <name_prefix>__<operation> at <path_prefix>/<operation>, so two connectors’ tools stay apart on the MCP face and inside its 64-character tool names.

Send dry_run: true first. The answer lists every operation with its effective action_class and approval, whether a route can serve it, and the action a mount takes: create, update (an MCP tool whose input schema changed since its route was written; changes names what), unchanged, skip (with the reason: not selected, not a read, not auto-approved, a name or path already taken, or the route cap) or stale (a route whose operation the connector no longer offers, or can no longer serve; it is reported and never deleted, since a consumer may still call it). The same call without dry_run writes every create and update in one transaction and returns the written route on each.

Every answer carries a plan_digest. Send the preview’s digest with the apply: the apply plans again inside its transaction and writes only when that plan still has the digest, so a tool the server changed or a route edited after you reviewed is never written unseen. When it differs the apply writes nothing and answers 409 mount_plan_changed with the current plan, as a dry run answers it, in error.details.plan; review that and apply again with its digest, under a new Idempotency-Key if you sent one, since a key replays its first answer, this 409 included. The digest covers every operation the connector offers and every route the API holds for it whatever operations selects, so a preview of everything and an apply of a selection share one. An apply without it writes whatever the mount plans at that moment.

Mounting again is the refresh. Every route the API holds for the connector is compared with what it offers now, whatever its name, path or the selection, so an upstream change is seen as a diff before anyone’s client sees it. operations selects what to create; omit it to create a route for every operation a route can serve. A route an owner renamed or moved keeps its name and path on refresh.

The route write’s rules apply to every operation: the connector must be in the API’s project (409 cross_project_reference), an MCP server must be reachable with its credential to be listed (400 validation_failed on tool_id with the server’s reason), and a public API mounts nothing. An API holds at most 200 routes; a mount that would pass the cap skips what does not fit. Without a plan_digest, a route changed while the mount was being planned answers 409 api_route_conflict; mount again. Dark launch: requires the hosted_apis_access entitlement (402 hosted_apis_not_in_plan otherwise).

Publish a connector's operations onto the API in one call: one `tool` route per operation of an `openapi` tool definition, or per tool its `mcp` server lists, named `<name_prefix>__<operation>` at `<path_prefix>/<operation>`, so two connectors' tools stay apart on the MCP face and inside its 64-character tool names. Send `dry_run: true` first. The answer lists every operation with its effective `action_class` and `approval`, whether a route can serve it, and the `action` a mount takes: `create`, `update` (an MCP tool whose input schema changed since its route was written; `changes` names what), `unchanged`, `skip` (with the `reason`: not selected, not a read, not auto-approved, a name or path already taken, or the route cap) or `stale` (a route whose operation the connector no longer offers, or can no longer serve; it is reported and never deleted, since a consumer may still call it). The same call without `dry_run` writes every create and update in one transaction and returns the written `route` on each. Every answer carries a `plan_digest`. Send the preview's digest with the apply: the apply plans again inside its transaction and writes only when that plan still has the digest, so a tool the server changed or a route edited after you reviewed is never written unseen. When it differs the apply writes nothing and answers 409 `mount_plan_changed` with the current plan, as a dry run answers it, in `error.details.plan`; review that and apply again with its digest, under a new `Idempotency-Key` if you sent one, since a key replays its first answer, this 409 included. The digest covers every operation the connector offers and every route the API holds for it whatever `operations` selects, so a preview of everything and an apply of a selection share one. An apply without it writes whatever the mount plans at that moment. Mounting again is the refresh. Every route the API holds for the connector is compared with what it offers now, whatever its name, path or the selection, so an upstream change is seen as a diff before anyone's client sees it. `operations` selects what to create; omit it to create a route for every operation a route can serve. A route an owner renamed or moved keeps its name and path on refresh. The route write's rules apply to every operation: the connector must be in the API's project (409 `cross_project_reference`), an MCP server must be reachable with its credential to be listed (400 `validation_failed` on `tool_id` with the server's reason), and a public API mounts nothing. An API holds at most 200 routes; a mount that would pass the cap skips what does not fit. Without a `plan_digest`, a route changed while the mount was being planned answers 409 `api_route_conflict`; mount again. Dark launch: requires the `hosted_apis_access` entitlement (402 `hosted_apis_not_in_plan` otherwise).

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

api_idstringRequired

Hosted API id (prefixed external id, api_...).

Headers

Idempotency-KeystringOptional<=255 characters

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns 409 idempotency_conflict. A replayed response carries the Idempotent-Replayed: true header.

A client-generated key (an opaque string, max 255 chars) that makes a side-effect POST safe to retry: the server runs the operation exactly once and replays the first response (its status and body) for 24 hours. Reusing a key with a different request body, or while the first request is still in flight, returns `409 idempotency_conflict`. A replayed response carries the `Idempotent-Replayed: true` header.

Request

This endpoint expects an object.

tool_idstringRequiredformat: "^tool_[0-9a-hjkmnp-tv-z]{26}$"

The openapi or mcp tool definition to mount, in the API’s project.

operationslist of stringsOptional

The operations to create routes for: openapi operation ids or the MCP server’s tool names. Omit to create a route for every operation a route can serve. Naming one the connector does not offer is 400 validation_failed on operations[i]. Existing routes are compared whatever the selection.

name_prefixstringOptionalformat: "^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$"

Prefix of each created route’s name, <name_prefix>__<operation>. Defaults to the tool’s name with other characters as _.

path_prefixstringOptionalformat: "^/(?:[a-z0-9._-]+(?:/[a-z0-9._-]+)*)?$"<=200 characters

Path each created route sits under, <path_prefix>/<operation>; lowercase segments of letters, digits, ., _ or -, with no {param} or *, and not under /mcp, /openapi.json or /_runs. Defaults to /<name_prefix> in lowercase.

dry_runbooleanOptional

Answer what the mount would do and write nothing.

include_writesbooleanOptional

Create routes for operations that are not reads too, each with allow_write: true. Only an API whose auth_mode names a person takes them; the operation’s approval must still be auto. Without it a write is a skip that says so.

plan_digeststringOptionalformat: "^[0-9a-f]{64}$"

The plan_digest of the preview you reviewed. The apply writes only while the plan it computes inside its transaction still has this digest, and otherwise writes nothing and answers 409 mount_plan_changed with the current plan. Omit it to apply what the mount plans now. Refused with dry_run.

Response headers

Speechify-Request-IdstringOptional

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a Speechify-Request-Id request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests

it is the stable handle that ties your observation to Speechify’s server-side logs, and it matches the request_id field in the error envelope.

The legacy alias X-Request-ID carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Unique identifier for this request, present on every response (2xx and non-2xx alike). If the caller sends a `Speechify-Request-Id` request header the server echoes it back (sanitized and length-capped) so one logical request can be traced end-to-end; otherwise the server generates a fresh value. Log it on every response and quote it in support requests - it is the stable handle that ties your observation to Speechify's server-side logs, and it matches the `request_id` field in the error envelope. The legacy alias `X-Request-ID` carries the same value and is still accepted on requests, until 2027-07-24. Prefer the un-prefixed name (RFC 6648).

Response

What the mount did, or on a dry run would do.

tool_idstringformat: "^tool_[0-9a-hjkmnp-tv-z]{26}$"

tool_namestring

tool_kindenum

name_prefixstring

path_prefixstring

dry_runboolean

operationslist of objects

One entry per operation the connector offers, in its order, then one per stale route whose operation it no longer offers.

summaryobject

plan_digeststringformat: "^[0-9a-f]{64}$"

Names this plan’s content: every operation the connector offers and every route the API holds for it, whatever operations selects, and nothing that moves without the plan changing. Send it back as the apply’s plan_digest to write only this plan.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

404

Not Found Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error