Runtype
Products & Surfaces

Setting up an API Surface

An API Surface turns your Flows and Agents into ready-to-use REST API endpoints. Once set up, any application can call your AI Capabilities using standard HTTP requests.

You can create an API Surface when setting up a new Product with the REST API template, or add one to an existing Product at any time. If you need more context first, see What are Surfaces?.

Before you begin: You need a Product with at least one Capability attached. If you have not created the Product yet, see Creating a Product.

Creating an API Surface

Add to an existing Product

  1. Go to Products in the sidebar.

  2. Open the Product you want to update.

  3. Scroll to the Surfaces section.

  4. Click Add Surface or Add Another Surface.

  5. Select REST API.

  6. Click Save.

Runtype creates the API Surface and generates a REST endpoint for each Capability attached to the Product.

First-time setup may show a Launch Your API guide with steps for getting your API key and trying an example request.

Create with the REST API template

  1. Go to Products in the sidebar.

  2. Click + New Product.

  3. Select the REST API template.

  4. Name your Product.

  5. Click Use Existing to attach a Flow or Agent.

  6. Select the Capability you want to expose.

  7. Click Create REST API.

Runtype creates the Product and API Surface together, then generates endpoints and a test API key so you can start right away.

Use the tabs in the Surface panel to configure and manage your API Surface.

Tab

What it's for

Overview

Surface name, status, and response settings

Endpoints

Your Capabilities, request URLs, and OpenAPI spec

Keys

Create and manage API keys

Ship

Integration code snippets and SDK examples

Setting up authentication

API Surfaces use API keys for authentication. Every request must include a valid key.

Creating an API key

  1. Open your Product and select the API Surface.

  2. Go to the Keys tab.

  3. Click Create API Key.

  4. Enter a name for the key.

  5. Choose the key environment: Test or Production.

  6. Click Create.

  7. Copy the generated key right away. It will not be shown again.

All API keys use the papi_ prefix. You can send them with the Authorization header as a Bearer token or with the X-API-Key header.

Store API keys securely. Test keys are rate-limited for development. Use a Production key when you are ready to go live.

Setting Surface status

Use the Overview tab to control whether the API Surface is available.

Status

Behavior

Draft

Endpoints are not accessible

Active

Endpoints are live and accepting requests

Paused

Endpoints are temporarily disabled without removing the Surface

Use Paused when you need to take the API offline for maintenance without changing the rest of the configuration.

Configuring response shape

In the Overview tab, response settings control how your API returns results.

  • Raw returns only the Capability output.

  • Wrapped includes metadata such as execution time and token usage.

For multi-step Flows, you can also choose which step output to return as the final response.

Accessing your OpenAPI spec

Runtype automatically generates an OpenAPI 3.0 specification for every API Surface. You can use it with tools like Postman, Swagger UI, or code generators.

Find the spec in the Endpoints tab in JSON or YAML format, or access it directly at:

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

The spec updates automatically when you add or change Capabilities.

Use the Ship tab for ready-to-use TypeScript and cURL examples.

Making your first API call

Once the API Surface is active, each Capability gets its own endpoint. Find the exact URLs in the Endpoints or Ship tab.

curl -X POST https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug} \
  -H "Authorization: Bearer papi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Your input text here"
  }'

The {capabilitySlug} value is generated from the Capability name. For example, Summarize Article becomes summarize-article.

Next steps

Was this helpful?