The Responses API starts runtime execution for an active agent model.
The model value is an active agent slug returned by GET /api/v1/models,
for example sal9-active-qa-agent. Do not prefix it with agent:.
Create a response
Required scope:
curl "$SALAMBO_BASE_URL/api/v1/responses" \
-H "Authorization: Bearer $SALAMBO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_AGENT_SLUG",
"input": "Write a short status report.",
"store": true,
"background": true
}'
Request body
| Field | Type | Required | Notes |
|---|
model | string | yes | Active agent slug returned by GET /api/v1/models. |
input | string or array | yes | Prompt text or structured input items. |
stream | boolean | no | Request streaming output when supported. |
background | boolean | no | Queue asynchronous work when supported. Also enabled by metadata salambo.background=true. |
store | boolean | no | Must not be false; use true when you want later retrieval. |
previous_response_id | string or null | no | Continue from a previous response. |
metadata | object | no | Up to 32 string values. Keys max 64 chars, values max 512 chars. |
salambo.prioritysalambo.background
Text input
{
"model": "YOUR_AGENT_SLUG",
"input": "Analyze this task.",
"store": true
}
file_id or file_data for each input_file item.
{
"model": "YOUR_AGENT_SLUG",
"input": [
{ "type": "input_text", "text": "Summarize this file." },
{ "type": "input_file", "file_id": "file_..." }
],
"store": true
}
Retrieve a response
GET /api/v1/responses/{responseId}
curl "$SALAMBO_BASE_URL/api/v1/responses/resp_..." \
-H "Authorization: Bearer $SALAMBO_API_KEY"
Cancel a response
POST /api/v1/responses/{responseId}/cancel
curl -X POST "$SALAMBO_BASE_URL/api/v1/responses/resp_.../cancel" \
-H "Authorization: Bearer $SALAMBO_API_KEY"
Response object
Important fields:
| Field | Meaning |
|---|
id | Response identifier. |
object | Always response. |
status | queued, in_progress, completed, failed, cancelled, or incomplete. |
run_id | Backing run identifier when available. |
output | Output messages, reasoning, function calls, or usage items. |
error | Error details when failed. |
metadata | Stored metadata. |
Readiness errors
Response creation requires an active agent with a ready deployment, runtime-ready billing, provider configuration, and the required API-key scope.
If the model resolves but the agent is not fully runtime-ready, the API returns a structured error instead of starting a sandbox. For example:
{
"error": {
"message": "model does not have a ready active deployment",
"type": "invalid_request_error",
"param": "model",
"code": "conflict"
}
}
