Skip to navigation
Products & Surfaces

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:

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.

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:

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.

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