Create an agent, submit a task, poll for the verified result.

1. Authenticate

Authorization: Bearer <key> or X-API-Key: <key>. Create a key from your dashboard after subscribing.

2. Create an agent

curl -X POST https://hq.amberoneai.com/api/v1/agent-ops/agents \
  -H "Authorization: Bearer wrap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Triage",
    "role": "specialist",
    "goal": "Classify incoming support tickets and draft a first response.",
    "instructions": "Read the ticket text. Classify as billing/technical/other. Draft a short, helpful reply.",
    "tools": ["http"]
  }'

3. Submit a task

Returns 202 immediately with status queued — execution continues in the background.

curl -X POST https://hq.amberoneai.com/api/v1/agent-ops/agents/{agentId}/tasks \
  -H "Authorization: Bearer wrap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Triage ticket #4821",
    "input": {"ticketText": "My invoice charged me twice this month."}
  }'

4. Poll for the result

Status moves through queued → planning → working → retrying (if needed) → completed or failed. A task is only ever completed once its result has passed a separate verification check — never on step completion alone.

curl https://hq.amberoneai.com/api/v1/agent-ops/tasks/{taskId} \
  -H "Authorization: Bearer wrap_live_..."

Avoid polling: webhooks

Pass webhookUrl when submitting a task and we’ll POST the final task state to it once it reaches completed or failed — HMAC-signed via an X-Amber-Signature header (SHA-256 of the raw body with your webhook secret), so no polling loop is required.

Duplicate-safe submission: idempotency keys

Send an Idempotency-Key header (or an idempotencyKey body field) with any task submission. Retrying the same request with the same key returns the original task instead of creating and re-running a duplicate — safe to retry on a network timeout without double-billing your task quota.

Batch submission

POST /agent-ops/agents/{id}/tasks/batch submits up to 50 tasks in one call — one round trip instead of many, each item optionally carrying its own idempotency key.

Skip polling for fast tasks: run-and-wait

POST /agent-ops/agents/{id}/tasks/run-and-wait submits and waits up to ~25 seconds inline, returning the finished result directly for tasks that complete quickly. If it’s still running when the wait ends, fall back to polling GET /tasks/{id} exactly as with the regular endpoint.

Confidence score

A completed or failed task's result.confidence field (0–100) reflects how certain the verification pass was in its verdict — not how well the task went. A confidently-refused task still reports high confidence; a low score means treat the outcome with more skepticism.

Check usage before you hit a limit

GET /agent-ops/usage returns your plan's limits alongside real current consumption — agent count and tasks used/remaining for the last 30 days, broken down by status. Good for a dashboard, or for checking headroom before a batch submission.

JavaScript

const res = await fetch("https://hq.amberoneai.com/api/v1/agent-ops/agents/" + agentId + "/tasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.AGENT_OPS_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Triage ticket #4821",
    input: { ticketText: "My invoice charged me twice this month." },
  }),
});
const task = await res.json();
console.log(task.data.status); // "queued"

// Poll for completion
let final = task.data;
while (!["completed", "failed"].includes(final.status)) {
  await new Promise((r) => setTimeout(r, 2000));
  const poll = await fetch("https://hq.amberoneai.com/api/v1/agent-ops/tasks/" + task.data.id, {
    headers: { "Authorization": "Bearer " + process.env.AGENT_OPS_API_KEY },
  });
  final = (await poll.json()).data;
}
console.log(final.status, final.result);

Python

import os, time, requests

API_KEY = os.environ["AGENT_OPS_API_KEY"]
BASE = "https://hq.amberoneai.com/api/v1/agent-ops"
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.post(
    f"{BASE}/agents/{agent_id}/tasks",
    headers=headers,
    json={"title": "Triage ticket #4821", "input": {"ticketText": "My invoice charged me twice this month."}},
)
task = resp.json()["data"]

while task["status"] not in ("completed", "failed"):
    time.sleep(2)
    task = requests.get(f"{BASE}/tasks/{task['id']}", headers=headers).json()["data"]

print(task["status"], task.get("result"))

Endpoint reference

Errors

Every error response is { ok: false, error: { code, message }, requestId }. Common codes: missing_api_key, invalid_api_key, forbidden (missing scope or plan feature), plan_required, quota_exceeded, not_found, invalid_request, rate_limited.

Rate limits

Per-plan requests-per-minute, enforced per API key. The current limit and remaining count are returned on every response via X-RateLimit-* headers.

Full API reference

See the platform-wide OpenAPI spec for the complete schema (tag: agent-ops).