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:

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

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: chunk
data: {"content":"Once"}
event: chunk
data: {"content":" upon"}
event: chunk
data: {"content":" a time"}
event: done
data: {"status":"complete"}

If an error occurs during streaming:

event: error
data: {"message":"Flow execution failed"}

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

• Auto-generated OpenAPI spec for programmatic API documentation
• Scoping API keys to capabilities for security
• Authenticating with Product API keys