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:

1
import SwaggerParser from '@apidevtools/swagger-parser';
2
3
const api = await SwaggerParser.validate('https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/openapi.json');
4
console.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.

Customizing the spec

Add custom metadata to your spec:

1. Go to API surface settings
2. Click Documentation
3. Add:
   • API description

• Contact information
• License details
• External documentation links

4. Click Save

These details appear in the generated spec’s metadata section.

Next steps

• Calling your API endpoints for usage examples
• Scoping API keys to capabilities
• Setting up an API surface