Calling your API endpoints

Use POST requests to invoke capabilities on an API Surface from your application.

Endpoint structure

Use the following URL pattern for a capability endpoint:

https://api.runtype.com/v1/products/{PRODUCT_ID}/surfaces/{SURFACE_ID}/api/{CAPABILITY_SLUG}

Replace the placeholders with these values:

• PRODUCT_ID: ID of the Product.
• SURFACE_ID: ID of the API Surface.
• CAPABILITY_SLUG: Configured slug for the capability endpoint.

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

Find the endpoint URL on the API Surface’s Endpoints tab or Ship tab.

Make a request

Send a POST request with the capability’s input as a JSON object. The endpoint passes top-level fields directly to the capability.

Use the following request to send topic and tone fields:

$
curl -X POST "https://api.runtype.com/v1/products/{PRODUCT_ID}/surfaces/{SURFACE_ID}/api/{CAPABILITY_SLUG}" \
>
  -H "Authorization: Bearer papi_YOUR_PRODUCT_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "topic": "machine learning",
>
    "tone": "casual"
>
  }'

Replace papi_YOUR_PRODUCT_KEY with your API key. Use the PRODUCT_ID, SURFACE_ID, and CAPABILITY_SLUG values for your Product, API Surface, and capability endpoint.

To stream a capability response, set options.stream to true in the request body. On a capability endpoint, you can also add stream=true to the URL. The following request uses the query parameter:

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

Use the same PRODUCT_ID, SURFACE_ID, CAPABILITY_SLUG, and papi_YOUR_PRODUCT_KEY values in this request.

Request body

The dedicated capability endpoint accepts a JSON object. Each top-level field becomes an input parameter. Add options.stream to request a stream. The following table lists the supported fields:

To select a capability by name instead of using its endpoint slug, use the generic api/dispatch endpoint. The following table lists its request fields:

Response shape

Non-streaming requests return JSON. The response shape depends on the responseShape setting on your API Surface.

The raw response shape, which is the default, returns only the capability output:

1
"AI-generated response text"

The wrapped response shape includes the capability output and execution metadata:

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

In the wrapped response, the API returns the actual value for exec_YOUR_EXECUTION_ID. Configure responseShape in the API Surface’s Overview tab.

Streaming responses

Streaming responses use Server-Sent Events (SSE). The API emits a unified event stream with a named event and a JSON payload for each event. The following example shows a successful flow stream:

id: 0
event: execution_start
data: {"type":"execution_start","executionId":"exec_YOUR_EXECUTION_ID","seq":0,"kind":"flow","flowId":"flow_YOUR_FLOW_ID","flowName":"Summarize Article","totalSteps":1,"startedAt":"2026-07-23T00:00:00Z"}
id: 1
event: step_start
data: {"type":"step_start","executionId":"exec_YOUR_EXECUTION_ID","seq":1,"id":"step_1","name":"Summarize","stepType":"prompt","index":0,"totalSteps":1,"startedAt":"2026-07-23T00:00:00Z"}
id: 2
event: text_start
data: {"type":"text_start","executionId":"exec_YOUR_EXECUTION_ID","seq":2,"id":"text_1"}
id: 3
event: text_delta
data: {"type":"text_delta","executionId":"exec_YOUR_EXECUTION_ID","seq":3,"id":"text_1","delta":"Machine learning is"}
id: 4
event: text_complete
data: {"type":"text_complete","executionId":"exec_YOUR_EXECUTION_ID","seq":4,"id":"text_1","text":"Machine learning is a method for training models with data."}
id: 5
event: step_complete
data: {"type":"step_complete","executionId":"exec_YOUR_EXECUTION_ID","seq":5,"id":"step_1","name":"Summarize","stepType":"prompt","success":true,"durationMs":1823,"completedAt":"2026-07-23T00:00:02Z"}
id: 6
event: execution_complete
data: {"type":"execution_complete","executionId":"exec_YOUR_EXECUTION_ID","seq":6,"kind":"flow","success":true,"durationMs":1823,"completedAt":"2026-07-23T00:00:02Z"}

Treat exec_YOUR_EXECUTION_ID and flow_YOUR_FLOW_ID as example values. The API returns the actual IDs in the stream. The event name matches data.type, and seq starts at 0 and increments by 1. The SSE id carries the same sequence number.

A capability can emit tool, reasoning, approval, media, and state events.

If execution fails after the stream starts, the API sends execution_error as the terminal event:

id: 6
event: execution_error
data: {"type":"execution_error","executionId":"exec_YOUR_EXECUTION_ID","seq":6,"kind":"flow","error":"Flow execution failed"}

In this example, exec_YOUR_EXECUTION_ID represents the execution ID from execution_start. The API uses the same execution ID throughout the stream.

Error responses

The API uses HTTP status codes to report authentication, authorization, endpoint, rate-limit, and execution errors. The following examples show common responses.

When authentication is missing, the API returns 401 Unauthorized:

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

When a key cannot use the endpoint, the API returns 403 Forbidden:

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

When the capability slug does not match an available endpoint, the API returns 404 Not Found:

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

When a key exceeds its configured limit, the API returns 429 Rate Limit Exceeded:

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

The retryAfter value is the number of seconds before the rate-limit window resets.

When capability execution fails, the API returns 500 Internal Server Error:

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

The exec_YOUR_EXECUTION_ID value represents the execution ID that the API returns.

Use executionId to find the failed run in execution logs.

Rate limits

Configure per-minute and per-day limits for each API key in the API Surface’s Keys tab. The API applies those limits to requests that use the key.

Next steps

Use these links to continue:

• Auto-generated OpenAPI spec: inspect the generated request and response schemas
• Scoping API keys to capabilities: limit a key to specific capabilities
• Authenticating with product API keys: configure headers and manage API keys