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:

$
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 '{
>
    "input": "Your input text",
>
    "variables": {
>
      "customVar": "value"
>
    }
>
  }'

Request body

The request body accepts these fields:

Response format

Successful responses return JSON:

1
{
2
  "executionId": "exec_xxxxxx",
3
  "output": "AI-generated response text",
4
  "metadata": {
5
    "model": "gpt-4o",
6
    "tokensUsed": 245,
7
    "latencyMs": 1823
8
  }
9
}

Streaming responses

For real-time output, enable streaming:

$
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 '{"input": "Tell me a story", "stream": true}'

Streaming responses use Server-Sent Events (SSE):

data: {"type":"token","content":"Once"}
data: {"type":"token","content":" upon"}
data: {"type":"token","content":" a"}
data: {"type":"done","metadata":{"tokensUsed":245}}

Error responses

Errors return appropriate HTTP status codes:

400 Bad Request:

1
{
2
  "error": "Missing required field: input"
3
}

401 Unauthorized:

1
{
2
  "error": "Invalid or missing API key"
3
}

404 Not Found:

1
{
2
  "error": "Capability not found"
3
}

500 Internal Server Error:

1
{
2
  "error": "Flow execution failed",
3
  "executionId": "exec_xxxxxx"
4
}

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