Products & Surfaces

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

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.
  5. In Visual view, drag a connection from the Capability node to the API Surface node.
  6. Click Save.

Runtype creates the API Surface in draft status. The Endpoints tab lists an endpoint for each enabled Capability connected to 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 together 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.

Configure an API Surface

Use the following tabs to configure and integrate your API Surface:

TabUse it to
OverviewEdit the Surface name and status, and configure response settings.
EndpointsView connected Capabilities, endpoint URLs, and OpenAPI specifications.
KeysGenerate and manage API keys.
ShipCopy TypeScript SDK and cURL examples.

Set up authentication

API Surfaces use API keys by default. When Authentication Mode is Keys Only, include a valid API key in every request. Select Public (No Auth) to allow unauthenticated requests.

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. Click Generate Key.
  7. Copy the generated API key.

Production API keys appear only when you create them. Test API keys remain revealable from the Keys tab. Store API keys securely.

All API 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, and test API keys have no lifetime cap. Production API keys do not have this surface test-key cap, but account-level limits can apply. Every Surface accepts both key types, so you can create a production API key from the Keys tab at any time.

Set Surface status

Use the Overview tab to control whether the API Surface accepts requests. The following table describes each status:

StatusBehavior
DraftThe API rejects requests.
ActiveThe API accepts requests when authentication succeeds.
PausedThe API rejects requests until you reactivate the Surface.

Use Paused to take the API offline for maintenance without deleting the Surface configuration.

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.

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
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
$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 configured slug for the Capability endpoint.
  • papi_YOUR_PRODUCT_KEY: the API key that you generated for the API Surface.

Runtype uses the configured endpoint slug. If you do not set one, Runtype converts the Capability name to lowercase kebab case. For example, Summarize Article becomes summarize-article.

Replace the request body with the input fields that your Capability accepts.

Next steps

Continue with these guides: