Setting up an API surface

Use an API Surface to expose your Flows and Agents through REST API endpoints. Call each endpoint with a standard HTTP request.

Create an API Surface with a Product, or add one to an existing Product. For an overview, see What are Surfaces?.

Before you begin

Prepare a Flow or Agent that you want to expose as a Capability. For an existing Product, confirm that it contains a Capability that you can connect to the API Surface. For Product and Capability setup, see Creating a Product and Adding capabilities to a Product.

Create an API Surface

You can create a new Product with an API Surface, or add an API Surface to a Product that you already have. Both paths create the API Surface in Draft status, so it rejects API requests until you activate it.

Create a Product with a REST API Surface

To create a Product and API Surface together, follow these steps:

1. On the Products page, click New product.
2. Select REST API.
3. In the Name field, enter a name for the Product.
4. Click Use Existing.
5. Select Agents or Flows.
6. Select the Flow or Agent that you want to expose as a Capability.
7. Click Create REST API. Runtype creates the Product, API Surface, and Capability and connects the Capability to the API Surface.

The Product editor opens with the Launch Your API guide, which can create a test API key and show an example request.

Add an API Surface to an existing Product

To add an API Surface to an existing Product, follow these steps:

1. On the Products page, click the Product that you want to update.
2. Select Visual view.
3. Click Add Surface.
4. In the dialog, select REST API. The API Surface node appears on the canvas.
5. Drag a connection from the Capability node to the API Surface node. The Capability connects to the API Surface.
6. Click Save.

The Endpoints tab lists an endpoint for each enabled Capability connected to the API Surface.

Set up with the Runtype MCP server

If you build from an AI coding assistant, you can set up an API Surface with the Runtype MCP server. Use create_surface with the type api, add_surface_item to connect a Capability, update_surface to set the status to active, and create_surface_key to create an API key. For setup, see Runtype MCP server.

Configure an API Surface

The API Surface panel has the following tabs:

• Overview: edit the Surface name and status, configure response settings and logging, and delete the Surface.
• Endpoints: view connected Capabilities and endpoint URLs, set endpoint slugs, test endpoints, and get OpenAPI specifications.
• Keys: choose the authentication mode, and generate and manage API keys.
• Ship: copy TypeScript SDK and cURL examples.

Set up authentication

API Surfaces require an API key by default. The Authentication Mode setting on the Keys tab controls this:

• Keys Only: every request must include a valid API key. This is the default.
• Public (No Auth): the API accepts requests without an API key.

Generate an API key

To generate an API key, follow these steps:

1. On the Products page, open the Product that contains the API Surface.
2. On the API Surface panel, click Keys.
3. Click Generate Key.
4. In the Name (optional) field, enter a name for the API key.
5. In Key Type, select Test or Production.
6. Optional: In Rate Limit (requests/minute), enter the maximum number of requests per minute for this key. Leave it empty for no per-key limit.
7. Click Generate Key.
8. Copy the generated API key.

Runtype shows a production API key only once, when you create it. You can reveal a test API key again from the Keys tab. Store API keys securely.

API Surface keys use the papi_ prefix. Send an API key in the Authorization header as a Bearer token or in the X-API-Key header.

Test API keys allow up to 50 executions per UTC day. The count resets at midnight UTC. Production API keys have no daily cap. Your account’s usage limits still apply to both key types. A key that exceeds its per-minute rate limit gets 429 Too Many Requests with a Retry-After header.

Activate the API Surface

The Overview tab shows the Surface status. Each status works as follows:

• Draft: the API rejects requests. New API Surfaces start in this status.
• Active: the API accepts requests when authentication succeeds.
• Paused: the API rejects requests until you reactivate the Surface.

To activate the API Surface, follow these steps:

1. On the Overview tab, click the status menu and select Active.
2. Click Save.

Use Paused to take the API offline for maintenance without deleting the Surface configuration. Delete Surface on the Overview tab permanently deletes the Surface and all of its API keys. You cannot undo a deletion.

Configure response shape

In the Overview tab, use Response Shape to control the response body. The following options are available:

• Raw returns only the Capability output.
• Wrapped returns the output in data and includes meta with the execution ID and, when available, duration and token counts.

For a multi-step Flow, use Return Step to choose the first, last, or a named step output.

Set an endpoint slug

Each endpoint URL ends with a slug, for example /api/summarize-article. If you do not set a slug, Runtype lowercases the Capability name and replaces spaces and underscores with hyphens. For example, Summarize Article becomes summarize-article. Other characters stay in the default slug, so set a custom slug if the name contains punctuation.

To set a custom slug, follow these steps:

1. On the API Surface panel, click Endpoints.
2. Click the endpoint to expand it.
3. Click the pencil icon next to the endpoint URL.
4. Enter a slug. The field accepts lowercase letters, numbers, and hyphens.
5. Click the check icon. Runtype shows Endpoint slug saved.

To restore the default slug, clear the field and save.

Test an endpoint in the dashboard

You can test an endpoint before you write any client code. The test uses your dashboard sign-in, so it works before you activate the Surface or create an API key.

To test an endpoint, follow these steps:

1. On the API Surface panel, click Endpoints.
2. Click the endpoint to expand it.
3. In Request Body, enter the JSON input for the Capability.
4. Click Run. The Response panel shows the status and the response body.

The Endpoints tab also links to Interactive API docs, where you can browse and test every endpoint.

View the OpenAPI specification

An active API Surface exposes an OpenAPI 3.2.0 specification. Find the JSON and YAML links in the Endpoints tab, or request the JSON specification with a valid API key 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 with these values:

• YOUR_PRODUCT_ID: the ID of the Product that contains the API Surface.
• YOUR_SURFACE_ID: the ID of the API Surface.

Use .yaml instead of .json to request the YAML specification. The specification reflects the enabled Capabilities, endpoint slugs, and Product metadata.

Use the Ship tab for TypeScript SDK and cURL examples.

Make your first API call

After the API Surface is active and you have an API key, find the exact endpoint URL in the Endpoints or Ship tab. The following command sends a POST request to a Capability endpoint:

curl -X POST "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/YOUR_CAPABILITY_SLUG" \
  -H "Authorization: Bearer papi_YOUR_PRODUCT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "machine learning"
  }'

Replace the placeholders in the command with these values:

• YOUR_PRODUCT_ID: the ID of the Product that contains the API Surface.
• YOUR_SURFACE_ID: the ID of the API Surface.
• YOUR_CAPABILITY_SLUG: the slug of the Capability endpoint.
• papi_YOUR_PRODUCT_KEY: the API key that you generated for the API Surface.

Replace the request body with the input fields that your Capability accepts. A successful call returns 200 OK with the Capability output, in the format that Response Shape sets.

Verify the API Surface

To check the Surface and the key without a request body, list the endpoints that the key can call:

curl "https://api.runtype.com/v1/products/YOUR_PRODUCT_ID/surfaces/YOUR_SURFACE_ID/api/capabilities" \
  -H "Authorization: Bearer papi_YOUR_PRODUCT_KEY"

A 200 OK response with a capabilities list means that the Surface is active and the key is valid. Each item includes the Capability name, description, and endpoint path.

Troubleshoot common errors

The following errors are the most common when you first call an API Surface:

• 401 with the code INVALID_SURFACE and the error API surface is not active: the Surface is in Draft or Paused status. Activate the API Surface.
• 401 with the error Authentication required: the request has no API key. Add the key in the Authorization or X-API-Key header.
• 401 with the code INVALID_KEY: the key is wrong or belongs to another API Surface. Copy the full key from the Keys tab of this Surface.
• 429 with the code TEST_KEY_DAILY_LIMIT_EXCEEDED: the test API key reached 50 executions for the day. Wait until midnight UTC, or use a production API key.

For the full list of error responses, see Calling your API endpoints.

Next steps

Continue with these guides:

• Calling your API endpoints: send requests and handle responses.
• Authenticating with product API keys: choose headers and manage API keys.
• Scoping API keys to capabilities: restrict API keys to selected Capabilities.
• Auto-generated OpenAPI spec: import the specification into API tools.
• Product versioning and status: control which Flow or Agent version your endpoints run.