Use the v1 Runtime API

The v1 runtime API is designed around a simple mental model: active agents are exposed as models, and your application uses those model IDs to create responses.

List Available Models

Use:

GET /api/v1/models

This endpoint returns the active agents in the workspace. Your key needs the models:read scope.

Create A Response

Use:

POST /api/v1/responses

Your request must include:

• model: the agent slug
• input: either a string or a supported structured input payload
• store: true

Example:

curl -X POST "https://YOUR_DOMAIN/api/v1/responses" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-agent-slug",
    "input": "Summarize the uploaded notes and save the output.",
    "store": true,
    "stream": false
  }'

Input Types

The API accepts:

• plain text input
• structured arrays containing input_text
• structured arrays containing input_file

For file input, provide exactly one of:

• file_id
• file_data

Streaming And Background Runs

The create endpoint supports streamed and background behavior.

• stream: true returns an event stream
• background: true creates a background response

If your integration replays or resumes a response stream later, make sure the original request supports that flow.

Retrieve A Response

Use:

GET /api/v1/responses/{responseId}

This lets you retrieve the stored response object after creation.

You can also use the retrieve route to continue streaming in supported cases by requesting stream mode on retrieval.

Cancel A Response

Use:

POST /api/v1/responses/{responseId}/cancel

Cancellation fails for responses that are already in a terminal state such as completed or failed.

Work With Files

The file API helps you list and fetch generated outputs.

Main routes:

• GET /api/v1/files
• GET /api/v1/files/{fileId}
• GET /api/v1/files/{fileId}/content

Use these when a run produces artifacts you want to download or process in another system.

Metadata Notes

The request schema supports metadata, including runtime-related keys such as:

• salambo.priority
• salambo.background

Keep metadata small and intentional. Most teams only need it for routing or downstream bookkeeping.