> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.runtype.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server. # Auto-generated OpenAPI spec Use the OpenAPI specification that Runtype generates for your API Surface to document endpoints, import them into API tools, and generate client code. ## Access the OpenAPI spec An active API Surface publishes an OpenAPI 3.2.0 specification at the following URL: ```plaintext https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/openapi.json ``` Replace the placeholders in the URL: * `YOUR_PRODUCT_ID`: the ID of the Product that contains the API Surface. * `YOUR_SURFACE_ID`: the ID of the API Surface. To get the YAML document, replace `.json` with `.yaml` in the URL. Both links are on the **Endpoints** tab of your API Surface. The spec is public, so you can request it without an API key. To browse and test the endpoints in your browser, click **Interactive API docs** on the **Endpoints** tab. If the URL returns a `404` error, check the `error` message: * `Product not found`: the Product ID is wrong. * `API surface not found or not active`: the Surface ID is wrong, the Surface is not an API Surface, or the Surface is not active. ## What's included The generated spec describes the active API Surface with the following content: * **Surface endpoints**: `info`, `capabilities`, `dispatch`, and `chat`. The `info` endpoint is public. The others require an API key. * **Capability endpoints**: one `POST` path for each Capability's endpoint slug, with an optional `stream` query parameter. * **Request schemas**: one input schema for each Capability. * **Authentication**: bearer token and `X-API-Key` header security schemes. * **Error responses**: standard error formats and status codes. * **Server**: the API host that served the spec. * **Metadata**: a title built from your Product name, your Product description, a fixed version of `1.0.0`, and Runtype support contact details. The `dispatch`, `chat`, and Capability endpoints can return JSON or a server-sent event stream. ### Which Capabilities appear The spec lists a Capability only when the Capability is enabled and its item on the API Surface is enabled. An external agent Capability appears as one endpoint for each of the agent's skills that the API Surface shows. If two Capabilities use the same endpoint slug, only one of them runs at that path, and the spec entry for the path can describe the other Capability. The **Endpoints** tab shows a duplicate endpoint warning. Give each Capability a unique endpoint slug. ### Request schemas Each Capability's input schema comes from its parameters schema. For an external agent skill, it comes from the skill's input schema. For a flow-backed Capability without a parameters schema, Runtype infers the schema from the flow's steps. If neither exists, the spec accepts any JSON object, and generated clients get an untyped input. ### Product metadata The spec sets `info.title` to your Product name followed by `API`, for example `Acme Support API`. It sets `info.description` to your Product description, or to `API for` followed by your Product name if the Product has no description. To change these values, edit the Product's name or description in the dashboard. ## Import the spec into API clients Postman, Insomnia, and Bruno can each create a collection from the spec URL. In your tool, open the import option for OpenAPI documents, paste the spec URL, and import it. For the exact menu path, see your tool's documentation. > **Note** > > Some API tools support only OpenAPI 3.0 or 3.1. These tools might reject a 3.2 document or import only part of it. ## Generate client code Use OpenAPI Generator to generate a TypeScript client from the JSON spec: ```bash npx @openapitools/openapi-generator-cli generate \ -i https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/openapi.json \ -g typescript-fetch \ -o ./src/api-client ``` Replace `YOUR_PRODUCT_ID` and `YOUR_SURFACE_ID` with the IDs for your Product and API Surface. OpenAPI Generator also generates clients for Python, Go, Java, Ruby, PHP, and other languages. Each Capability operation is named `execute_` followed by the Capability name, with every character that is not a letter or digit replaced by `_`. Generated method names follow this name. The spec describes every Capability response with the same generic schema: `success`, `response`, and `executionId`. The actual response body depends on the API Surface's response shape setting. By default, a Capability endpoint returns only the capability output. Check the generated response types against the real response before you rely on them. For more information, see [Response shape](/user-guide/products-surfaces/calling-your-api-endpoints#response-shape). ## Keep the spec in sync The spec changes when you do any of the following: * Add, remove, enable, or disable Capabilities. * Change a Capability's configuration or endpoint slug. * Change the Product name or description. After a change, import the spec again and regenerate your client code. Clients and proxies can cache the spec for up to one hour, so a request made soon after a change can return the previous version. Renaming a Capability changes its operation name and the generated method names. Update your calling code after you regenerate. ## Next steps * [Calling your API endpoints](/user-guide/products-surfaces/calling-your-api-endpoints): send requests and handle responses. * [Authenticating with product API keys](/user-guide/products-surfaces/authenticating-with-product-api-keys): add API keys to Capability requests. * [Setting up an API Surface](/user-guide/products-surfaces/setting-up-an-api-surface): create or configure an API Surface.