Production guidance

Run workflow integrations safely

Production integrations should store their own workflow IDs, treat agent calls as asynchronous billable work, normalize both error shapes, and keep polling as a fallback even when webhooks are enabled.

Authentication and scopes

Send your key as X-API-Key or as Authorization: Bearer. Public workflow agents require agents:invoke. Search and knowledge concept routes require search:read. Scripted calls should include a descriptive User-Agent.

agents:invokesearch:readusage:read

Metadata and session IDs

session_id

A convenience tracking field. If you send it at the top level and inputs does not already contain one, it is merged into the agent inputs. It is not an idempotency key.

configuration.metadata

Caller-owned JSON for workflow reconciliation. It is included in terminal webhook payloads. Polling responses do not currently expose it as a top-level job field.

Webhooks

Invoke requests may include a webhook URL and optional secret. Webhooks fire on terminal completion or failure. They are a delivery convenience, not an exactly-once queue, so your receiver should be idempotent and polling should remain your recovery path.

Events

job.completed and job.failed.

Signing

If a secret is provided, verify X-AE-Signature and X-AE-Timestamp before trusting the payload.

Retries

Delivery retries on non-2xx or timeout. De-dupe by job ID plus terminal event/status.

Invoke configuration
{
  "inputs": {
    "session_id": "run_packaging_001",
    "design_challenge": "Protect reusable shipping containers from impact while using less material"
  },
  "configuration": {
    "metadata": {
      "workflow_id": "wf_2026_05_26_packaging",
      "step": "expansive_research",
      "user_visible_label": "Packaging research"
    },
    "webhook_url": "https://yourapp.example.com/webhooks/agent-ecology",
    "webhook_secret": "whsec_store_this_server_side"
  }
}
Webhook payload
{
  "event": "job.completed",
  "job_id": "8f4c2e5b9a16487abf07b78d5b87d0b3",
  "agent_id": "agents.biomimicry.expansive_research",
  "status": "completed",
  "result": {
    "status": "completed",
    "strategy_count": 42,
    "charge_usd": 0.34
  },
  "metadata": {
    "workflow_id": "wf_2026_05_26_packaging",
    "step": "expansive_research",
    "user_visible_label": "Packaging research"
  },
  "timestamp": "2026-05-26T17:37:18Z"
}

Idempotency

  • POST /v1/agents/{agent_id}/invoke is not currently idempotent through a public Idempotency-Key header.
  • If you receive a job_id, persist it and poll that job. Do not retry the invoke request for the same user action.
  • If the network fails before you receive a job_id, check your own durable request ledger before retrying.
  • Use configuration.metadata.workflow_id to reconcile your workflow state, but do not rely on metadata to prevent duplicate jobs.

Errors, rate limits, and retries

The API is moving toward a unified error envelope, but some auth, validation, and older validation paths still return a detail shape. Normalize both in clients.

Error shapes
{
  "error": {
    "type": "invalid_request",
    "message": "webhook_url must use HTTPS in production",
    "param": "webhook_url",
    "docs_url": null
  }
}

{
  "detail": "Missing required scope: search:read"
}

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["query", "top_k"],
      "msg": "Input should be greater than or equal to 1"
    }
  ]
}

401 / 403

Check key value, scope, and whether the route or agent is available to API-key callers.

402 / 503

Credits or billing preflight prevented job acceptance. Do not assume a job was created.

429 / 5xx

Honor Retry-After or rate-limit reset headers when present; retry safe reads with jitter.

Cost behavior

  • Agent invokes are billable work. The 202 response includes an acceptance-time estimate, while completed jobs may include the customer charge in result.charge_usd.
  • Costs vary with input length, retrieval depth, target counts, image collection attempts, and continuation work.
  • max_cost_usd is a caller-side budget guard for agents that support it. Budget-limited or continuation-limited results may still contain useful partial payloads.
  • Search and knowledge routes are metered lightweight reads. Their scores are relevance signals, not certainty or importance.