HTTP API
Call a saved agent from any backend or an HTTP request step. No SDK required.
OpenAPI specification
This specification covers public saved-agent execution and saved-task management/run routes, not the dashboard’s broader administration API. Give its URL to a coding agent or import it into an OpenAPI-compatible client. It describes request/response calls; it does not declare outbound webhook delivery.
Make your first request
Set NULLPROTOCOL_KEY in your backend environment. Replace order-reader with the agent ID and choose a unique event ID for each new task.
curl --fail-with-body 'https://api.nullprotocol.ai/v1/agents/order-reader/run' \
--header "Authorization: Bearer $NULLPROTOCOL_KEY" \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: order-42-read-v1' \
--data-raw '{
"operation": "extract",
"data": "Order 42: two blue mugs.",
"schema": { "orderId": "number", "quantity": "number" }
}'{
"result": {
"success": true,
"data": { "orderId": 42, "quantity": 2 }
},
"operationId": "the-history-operation-uuid"
}Choose an operation
| operation | Required fields | Output in result |
|---|---|---|
| extract | data, schema | data |
| summarize | content | summary, keyPoints |
| validate | criteria, subject | recommendation, score, reasoning |
| decide | context, actions | action, parameters, reasoning |
All four accept knowledge, contextKeys and conversation. Summarize also accepts maxLength and focus; validate accepts reference. HTTP decide accepts action objects with action and optional description. Full schemas and examples are in the OpenAPI file.
Keep the same ID when retrying
Idempotency-Key is required: 1–128 visible ASCII characters without spaces. Use the source event ID or generate a UUID once per task. Retry the same request with the same key, agent, ID and body. A completed request returns its stored response without another model request — including a stored failure. The curl example ends in -v1 so you can deliberately distinguish a later attempt from the first task.
If you received a completed refusal such as agent_paused or spend_cap_reached, fix the cause and deliberately submit a new attempt ID, such as order-42-read-v2. Reusing the old ID replays its refusal. A stored inference_unavailable or local_execution_required response also needs a new ID after its cause is fixed. Do not automatically create new attempts after an unknown provider outcome or a 500: inspect History first.
Responses are kept for 30 days. Later, a retained tombstone prevents the old ID from silently starting another paid operation. Rotating the SDK key changes caller identity; check History before retrying an uncertain old task under a different key.
Check transport and operation results
| Response | Next step |
|---|---|
| 400 idempotency_key_required / invalid_request_id | Supply a stable visible-ASCII task ID in the header |
| 400 invalid_body | Check fields against the operation schema |
| 415 JSON required | Send Content-Type: application/json |
| 401 unauthorized | Use an active SDK key for the intended Space |
| 404 agent_not_found | Check the agent ID and Space |
| 409 in_progress | Wait, then retry the same ID and body |
| 409 idempotency_mismatch | Use a new ID only for the new task |
| 409 request_outcome_unknown / run_expired | Inspect History; do not automatically start a new paid attempt |
| 409 local_execution_required | Choose a NullProtocol model in Settings, then use a new attempt ID |
| 429 rate_limited | Wait for Retry-After, then retry with the same ID and body |
| 503 inference_unavailable | Restore model availability, then deliberately use a new attempt ID |
| 503 busy | Retry later with the same ID and body |
| 500 internal_error | Inspect History before deliberately starting a new attempt |
| 200 with result.success: false | Handle result.errorCode and result.error |
Keep operationId for tracing. If result.historyError is present, keep the returned result even if its history row could not be saved.