Setting up an API Surface

An API Surface exposes your Flows and Agents as REST API endpoints. Once configured, you can call your AI Capabilities programmatically from any application using standard HTTP requests.

You can create an API Surface when setting up a new Product using the REST API template, or add one to an existing Product.

Creating an API Surface

Option 1: Add to an existing Product

1. Navigate to Products in the sidebar.

2. Open the Product you want to add an API Surface to.

3. Scroll to the Surfaces section.

4. Click Add surface (or Add Another Surface if you already have surfaces).

5. Select REST API as the surface type.

6. Choose an Orchestration Mode:

   • Single Capability — Creates a dedicated endpoint for each Capability (recommended for most API use cases)

   • Orchestrated — Routes requests to the appropriate Capability based on intent, keywords, or custom rules

7. Click Save.

Your API Surface is now created. Runtype automatically generates REST endpoints for each Capability attached to your Product.

Option 2: Create via REST API template

1. Navigate 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 your Product and API Surface together, automatically generating endpoints and an API key.

Configuring your API Surface

After creating your API Surface, you'll configure it using the tabs in the surface panel: Overview (name, status, response settings), Endpoints (Capabilities, requests, OpenAPI), Keys (API keys), and Ship (integration code).

Setting up authentication

API Surfaces use Product API keys for authentication. Each request must include a valid API key in the Authorization header.

1. Open your Product and navigate to the API Surface.

2. Go to the Keys tab.

3. Click Create API Key.

4. Enter a name for the key (e.g., "Production Client" or "Internal Dashboard").

5. Choose the key environment: Test or Production.

6. Optional: Scope the key to specific Capabilities by selecting them from the list. Unscoped keys can access all Capabilities on the Product.

7. Optional: Set permissions (Read, Write, Admin) based on your security requirements.

8. Click Create.

9. Copy the generated API key immediately—it won't be shown again.

For more details, see Managing API keys and Scoping API keys to Capabilities.

Choosing an orchestration mode

Your orchestration mode determines how requests are routed to Capabilities.

Single Capability mode (default for API Surfaces):

• Each Capability gets its own dedicated endpoint

• You specify the exact Capability to call in the URL path

• Best for programmatic access where you know which Capability to invoke

Orchestrated mode:

• Single endpoint that routes requests to different Capabilities automatically

• Routes based on user input, keywords, or custom logic

• Useful for conversational APIs or intent-based routing

To change the orchestration mode, go to the Orchestration tab in your API Surface settings and select your preferred mode.

Learn more in Surface orchestration modes.

Setting environment and status

Control your API Surface's availability with environment and status settings.

Status: Set your Product status to control API availability:

• Draft — API endpoints are not accessible

• Active — Endpoints are live and accept requests

• Paused — Temporarily disable endpoints without deleting the Surface

• Archived — Permanently disable endpoints

To change status, open your Product settings, select a status from the dropdown, and click Save.

See Product versioning and status for details.

Configuring response shape

In the Overview tab, you'll find Response Configuration settings that control how your API returns results:

• Response Shape: Choose Raw (return only the result) or Wrapped (include metadata like execution time, tokens used)

• Step Result: For multi-step Flows, select which step's output to return

This gives you control over the exact JSON structure your API clients receive.

Accessing OpenAPI spec and code snippets

Runtype automatically generates an OpenAPI 3.0 specification for your API Surface. You can access the spec and example code in multiple places:

• Endpoints tab: View the OpenAPI spec (JSON or YAML) and get quick-start code snippets

• Ship tab: Find integration code for TypeScript SDK and cURL with your API key

• Get Started step: When onboarding is shown, this step provides your API key, snippets, and OpenAPI spec

Your OpenAPI spec is also available at:

https://api.runtype.com/v1/products/{product-id}/openapi.json

The spec updates automatically when you add or modify Capabilities. For more information, see Auto-generated OpenAPI spec.

Using your API endpoints

Once your API Surface is active, each Capability is accessible via a POST endpoint. The exact base URL format is:

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

Find your specific endpoint URLs and base URL in the Endpoints or Ship tab. Include your API key in the Authorization header:

curl -X POST https://api.runtype.com/v1/products/your-product-id/surfaces/your-surface-id/api \
  -H "Authorization: Bearer papi_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Your input text here"
  }'

Next steps

• Calling your API endpoints — Learn request formats, streaming, variables, and error handling

• Authenticating with Product API keys — Understand authentication flows and security best practices

• Surface orchestration modes — Deep dive into single vs. orchestrated routing

• Setting up a Chat Surface — Add a chat widget to your Product

• Setting up an MCP Surface — Connect your Product to AI IDEs