Skip to content

Integrate

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.

Terminal
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" }
  }'
Success shape · additional metadata omitted
{
  "result": {
    "success": true,
    "data": { "orderId": 42, "quantity": 2 }
  },
  "operationId": "the-history-operation-uuid"
}

Choose an operation

operationRequired fieldsOutput in result
extractdata, schemadata
summarizecontentsummary, keyPoints
validatecriteria, subjectrecommendation, score, reasoning
decidecontext, actionsaction, 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

ResponseNext step
400 idempotency_key_required / invalid_request_idSupply a stable visible-ASCII task ID in the header
400 invalid_bodyCheck fields against the operation schema
415 JSON requiredSend Content-Type: application/json
401 unauthorizedUse an active SDK key for the intended Space
404 agent_not_foundCheck the agent ID and Space
409 in_progressWait, then retry the same ID and body
409 idempotency_mismatchUse a new ID only for the new task
409 request_outcome_unknown / run_expiredInspect History; do not automatically start a new paid attempt
409 local_execution_requiredChoose a NullProtocol model in Settings, then use a new attempt ID
429 rate_limitedWait for Retry-After, then retry with the same ID and body
503 inference_unavailableRestore model availability, then deliberately use a new attempt ID
503 busyRetry later with the same ID and body
500 internal_errorInspect History before deliberately starting a new attempt
200 with result.success: falseHandle 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.