> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# 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?](/user-guide/products-surfaces/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](/user-guide/products-surfaces/creating-a-product) and [Adding capabilities to a Product](/user-guide/products-surfaces/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](#activate-the-api-surface).

### 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](/developer-guides/integrations/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.

> **Warning**
>
> With **Public (No Auth)**, anyone who has the endpoint URL can run your Capabilities, and those executions count against your account. Use it only for public demos or open tools.

### 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.

> **Note**
>
> Give each endpoint in a Surface a different slug. Do not use `capabilities`, `dispatch`, `chat`, or `info` as a slug. The API reserves those paths, so an endpoint with one of these slugs cannot be called by its slug. If two Capabilities resolve to the same slug, the **Endpoints** tab shows a duplicate endpoint warning and serves only one of them. To fix it, set a custom slug on one of the Capabilities.

## 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:

**`OpenAPI JSON URL`**

```plaintext title="OpenAPI JSON 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:

**`Call a capability endpoint`**

```bash title="Call 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:

**`List available endpoints`**

```bash title="List available endpoints"
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](#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](/user-guide/products-surfaces/calling-your-api-endpoints#error-responses).

## Next steps

Continue with these guides:

* [Calling your API endpoints](/user-guide/products-surfaces/calling-your-api-endpoints): send requests and handle responses.
* [Authenticating with product API keys](/user-guide/products-surfaces/authenticating-with-product-api-keys): choose headers and manage API keys.
* [Scoping API keys to capabilities](/user-guide/products-surfaces/scoping-api-keys-to-capabilities): restrict API keys to selected Capabilities.
* [Auto-generated OpenAPI spec](/user-guide/products-surfaces/auto-generated-openapi-spec): import the specification into API tools.
* [Product versioning and status](/user-guide/products-surfaces/product-versioning-and-status): control which Flow or Agent version your endpoints run.