Products & Surfaces

Auto-generated OpenAPI spec

Runtype automatically generates OpenAPI 3.0 specifications for your API surfaces, providing machine-readable documentation for API clients and code generation tools.

Accessing the OpenAPI spec

Your API Surface’s OpenAPI spec is available at:

https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/openapi.json

A YAML version is also available at the same path with a .yaml extension. Find the link in the Endpoints tab of your API Surface.

What’s included

The generated spec includes:

  • Endpoints — All capability endpoints with paths and methods
  • Schemas — Request and response body definitions
  • Authentication — Bearer token security scheme
  • Error responses — Standard error formats and status codes
  • Metadata — API version, Product info, contact details

Using with API clients

Import the spec into API development tools:

Postman

  1. Open Postman
  2. Click Import
  3. Select Link
  4. Paste your OpenAPI spec URL
  5. Click Import

Postman creates a collection with all endpoints pre-configured.

Insomnia

  1. Open Insomnia
  2. Click Create → Import from URL
  3. Paste your OpenAPI spec URL
  4. Click Fetch and Import

Bruno

  1. Open Bruno
  2. Right-click collection
  3. Select Import → OpenAPI
  4. Enter your spec URL

Code generation

Generate client libraries from the spec using OpenAPI Generator:

$npx @openapitools/openapi-generator-cli generate \
>  -i https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/openapi.json \
>  -g typescript-fetch \
>  -o ./src/api-client

Supported languages include TypeScript, Python, Go, Java, Ruby, PHP, and many more.

Validating requests

Use the spec to validate requests before sending them:

1import SwaggerParser from '@apidevtools/swagger-parser';
2
3const api = await SwaggerParser.validate('https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/openapi.json');
4console.log('API name: %s, Version: %s', api.info.title, api.info.version);

Spec updates

The OpenAPI spec updates automatically when you:

  • Add or remove capabilities
  • Change capability configurations
  • Update Product settings

Always fetch the latest spec to ensure your client code stays synchronized.

The OpenAPI spec is publicly accessible without authentication. Only actual API calls require authentication.

Spec metadata

The generated spec’s metadata section (title, description) is derived from your Product’s name and description. To update these values, edit the Product’s name or description in the Product settings.

Next steps