Products & Surfaces

Calling your API endpoints

Make HTTP requests to your API surface endpoints to invoke capabilities programmatically from any application.

Endpoint structure

API Surface endpoints follow this pattern:

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

The {capabilitySlug} is generated from the Capability name. For example, Summarize Article becomes summarize-article. Find your specific URLs in the API Surface’s Endpoints or Ship tab.

Making a request

Send a POST request with your input data. The request body is passed directly as the capability’s input:

$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 '{
>    "topic": "machine learning",
>    "tone": "casual"
>  }'

You can also enable streaming via a query parameter:

$curl -X POST "https://api.runtype.com/v1/products/{productId}/surfaces/{surfaceId}/api/{capabilitySlug}?stream=true" \
>  -H "Authorization: Bearer papi_your_api_key" \
>  -H "Content-Type: application/json" \
>  -d '{"topic": "machine learning"}'

Request body

The request body for a dedicated capability endpoint is a JSON object. All fields are treated as input parameters for the capability. Optionally include an options object to control streaming:

FieldTypeRequiredDescription
(your fields)anyNoInput parameters for the capability
options.streambooleanNoEnable streaming responses (or use ?stream=true query param)

Alternatively, use the generic /api/dispatch endpoint to specify the capability by name:

FieldTypeRequiredDescription
capabilitystringYesName of the capability to execute
inputobjectNoInput parameters for the capability
messagesarrayNoConversation history (role and content per message)
options.streambooleanNoEnable streaming responses

Response format

Non-streaming responses return the capability output directly as JSON. The exact shape depends on the response format configured on your API Surface:

Raw format (default) returns just the output:

1"AI-generated response text"

Wrapped format includes metadata:

1{
2  "data": "AI-generated response text",
3  "meta": {
4    "executionId": "exec_a1b2c3d4-...",
5    "capability": "summarize-article",
6    "durationMs": 1823,
7    "tokens": {
8      "input": 150,
9      "output": 95,
10      "total": 245
11    }
12  }
13}

You can configure the response format in the Overview tab of your API Surface.

Streaming responses

Streaming responses use Server-Sent Events (SSE). Each event has a named type:

event: execution_start
data: {"type":"execution_start","executionId":"exec_...","seq":0,"kind":"flow","startedAt":"2026-07-23T00:00:00Z"}
event: text_start
data: {"type":"text_start","executionId":"exec_...","seq":1,"id":"text_1"}
event: text_delta
data: {"type":"text_delta","executionId":"exec_...","seq":2,"id":"text_1","delta":"Once upon a time"}
event: text_complete
data: {"type":"text_complete","executionId":"exec_...","seq":3,"id":"text_1","text":"Once upon a time"}
event: execution_complete
data: {"type":"execution_complete","executionId":"exec_...","seq":4,"kind":"flow","success":true}

If an error occurs during streaming:

event: execution_error
data: {"type":"execution_error","executionId":"exec_...","seq":4,"kind":"flow","error":{"code":"FlowExecutionError","message":"Flow execution failed"}}

The event: name always matches data.type, and seq is 0-based and contiguous within an execution stream.

Error responses

Errors return appropriate HTTP status codes:

401 Unauthorized:

1{
2  "error": "Authentication required",
3  "message": "Provide API key via Authorization: Bearer papi_xxx or X-API-Key header"
4}

403 Forbidden:

1{
2  "error": "Forbidden",
3  "message": "API key does not have access to this endpoint"
4}

404 Not Found:

1{
2  "error": "Endpoint not found",
3  "message": "No capability found for endpoint 'my-capability'"
4}

429 Rate Limit Exceeded:

1{
2  "error": "Rate limit exceeded",
3  "code": "RATE_LIMITED",
4  "retryAfter": 60
5}

500 Internal Server Error:

1{
2  "success": false,
3  "error": "Execution failed",
4  "message": "Flow execution failed",
5  "executionId": "exec_a1b2c3d4-..."
6}

Use the executionId to debug failures in execution logs.

Rate limits

API Surfaces enforce rate limits that can be configured per API key. You can set per-minute and per-day limits when creating keys in the Keys tab of your API Surface.

Next steps