Using the agent platform

Nicia is also an agent platform: you configure an agent once and invoke it many times, each invocation a run you can wait on, poll, stream, or be called back about.

This section is for that surface. If you are here for governed knowledge, start with the Quickstart instead.

Start a run and wait for the result

POST /v1/runs starts a run for an agent. Add Prefer: wait=<seconds> to block until it finishes (or the deadline passes) and get the output in the same response.

curl https://api.nicia.ai/v1/runs \
  -H "x-api-key: $NICIA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Prefer: wait=60" \
  -d '{
    "agentId": "<your-agent-id>",
    "input": { "prompt": "Summarize the attached report." }
  }'

{
  "data": {
    "run": {
      "id": "0c7f…",
      "state": "closed",
      "output": { "summary": "…" }
    }
  }
}

When the run finishes in time, state is closed and output holds the result. If it does not finish before the deadline you get back a still-active run (state: "active") — nothing is lost, and you continue asynchronously. See Synchronous results.

Long-running work

• Poll GET /v1/runs/{runId} until state is terminal (closed / failed / abandoned).
• Stream GET /v1/runs/{runId}/stream for messages live over resumable Server-Sent Events.
• Webhooks — register a URL and be notified on completion, with the result delivered inline.

In this section

• Agents — reusable, configured AI workers.
• Runs — one invocation; the unit of execution.
• Conversations — group runs into a multi-turn thread.
• Synchronous results — Prefer: wait semantics.
• Streaming — resumable SSE.
• Webhooks — completion callbacks and signature verification.

Cross-cutting mechanics live in API basics: authentication, errors, and idempotency.