AI Agentics REST API reference
A single, predictable HTTP API for building, running, and observing AI agents. Authenticate with a bearer key, create a run, stream the agent loop token by token, and inspect every tool call and trace — all over plain JSON.
- Base URL: api.aiagentics.io/v1
- JSON over HTTPS
- Updated 2026
The AI Agentics API is a RESTful interface for the full agent lifecycle: define an agent and its tools, kick off a run, watch the reasoning loop unfold in real time, and pull back structured traces of every decision. All endpoints live under https://api.aiagentics.io/v1, accept and return JSON, and are versioned by URL path so your integrations never break underneath you.
If you have ever called a REST agent API for payments or messaging, this will feel familiar: resource-oriented URLs, standard HTTP verbs, bearer authentication, and conventional status codes. What is different is the streaming model — because an agent thinks and acts over many steps, run endpoints emit a live event stream of tokens, tool calls, and observations rather than a single blocking response.
This reference covers the request shape, the seven core resources, the most-used endpoints, and how to handle rate limits and errors. For higher-level concepts, see how agent tools work and the full documentation.
Authenticate every request with a bearer key
All requests are authenticated and must be made over HTTPS. Plain HTTP and requests without a valid key are rejected.
One header, every call
Create a secret key in your dashboard, then pass it as a bearer token. Keys are environment-scoped (test vs. live) and project-scoped, so blast radius stays small.
Never expose a secret key in a browser, mobile app, or public repo. Route agent calls through your own backend and keep the key server-side.
- Bearer auth: Authorization: Bearer sk_live_…
- Separate test and live keys per project
- Rotate keys with zero downtime
- Scoped permissions per key (read, run, admin)
1$ curl https://api.aiagentics.io/v1/agents \2 -H "Authorization: Bearer sk_live_8fa2…c9" \3 -H "Content-Type: application/json"45{ // 200 OK6 "object": "list",7 "data": [8 { "id": "agt_5fK2", "name": "Support agent",9 "model": "reasoning-pro", "tools": 6 }10 ],11 "has_more": false12}Keep secret keys server-side
A leaked sk_live_ key can create runs and read data on your account. Store keys in environment variables or a secrets manager, never in client bundles or version control. If a key is exposed, revoke it from the dashboard — revocation takes effect within seconds.
The seven core API resources
Every object in the agent API is addressable by a stable, prefixed ID — agt_, run_, tool_, mem_, file_, whk_, trc_ — and exposes the usual create, retrieve, list, and delete operations.
Agents
The reusable definition of an agent: its system instructions, model, attached tools, memory policy, and guardrails. Create once, run many times.
Runs
A single execution of an agent against an input. Runs hold status, the message thread, tool calls, token usage, and the final output.
Tools
Function definitions the agent can call — HTTP tools, code execution, or your own webhooks. Each has a JSON schema for its arguments.
Memory
Persistent stores the agent reads and writes: a vector store for RAG plus key-value scratchpads scoped to a user, session, or project.
Files
Upload documents for retrieval, code interpretation, or attachment to a run. Files are referenced by ID and chunked for vector search.
Webhooks
Register HTTPS endpoints to receive run.completed, run.failed, and tool.requested events. Payloads are signed so you can verify origin.
Traces
A structured, replayable log of one run: every reasoning step, tool input/output, latency, and token count — the backbone of observability.
API keys
Manage secret keys programmatically: list, create scoped keys, and revoke. Admin-scoped keys only, so day-to-day run keys can't escalate.
Common agent API endpoints
The handful of calls that cover most integrations. All paths are relative to the v1 base URL and return JSON.
Build & configure
- POST /v1/agents — Create an agent from instructions, a model, and a list of tool IDs.
- GET /v1/agents/:id — Retrieve an agent definition, including attached tools and memory config.
- POST /v1/tools — Register a tool with a name, JSON-schema arguments, and a handler URL.
- POST /v1/files — Upload a document for retrieval or code interpretation; returns a file_ id.
- POST /v1/webhooks — Subscribe an HTTPS endpoint to run and tool lifecycle events.
Run & observe
- POST /v1/runs — Start a run for an agent with an input; pass stream:true for live events.
- GET /v1/runs/:id — Poll a run's status, message thread, output, and token usage.
- POST /v1/runs/:id/cancel — Stop an in-flight run; any pending tool calls are aborted safely.
- POST /v1/runs/:id/submit_tool_outputs — Return results for tool calls the agent requested, resuming the loop.
- GET /v1/traces/:run_id — Fetch the full step-by-step trace of a run for debugging and replay.
Create a run and stream the agent loop
Set stream:true to receive server-sent events as the agent reasons, calls tools, and produces output — perfect for responsive UIs and long-running tasks.
1$ curl https://api.aiagentics.io/v1/runs \2 -H "Authorization: Bearer sk_live_8fa2…c9" \3 -H "Content-Type: application/json" \4 -d '{5 "agent_id": "agt_5fK2",6 "input": "Summarize today\u2019s failed payments",7 "stream": true8 }'1event: run.created2data: { "id": "run_Q8x", "status": "in_progress" }34event: token // model reasoning5data: { "delta": "Checking the payments table…" }67event: tool.requested8data: { "tool": "sql_query", "args": { "limit": 50 } }910event: tool.completed11data: { "rows": 7, "latency_ms": 84 }1213event: run.completed14data: { "status": "completed", "output": "7 payments…" }When a run pauses on a client-side tool (one your own code fulfills), the stream emits tool.requested and the run enters requires_action. Compute the result and call POST /v1/runs/:id/submit_tool_outputs to resume the loop — exactly the tool-calling pattern that lets agents act on your systems. Prefer polling? Drop stream and call GET /v1/runs/:id until status is completed.
Rate limits, latency, and reliability
The API is built for production workloads. Limits are generous by default and rate-limit headers on every response make backoff easy.
Read requests
per project, per plan
Run creations
20 concurrent runs
API overhead
p50, excludes model time
Uptime SLA
see /status
Backoff with the rate-limit headers
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. On a 429, honor the Retry-After header and retry 429 and 5xx responses with exponential backoff plus jitter. Each response also carries a request_id — include it when you contact support. Live numbers and incident history are on the status page.
API reference, answered
Every request to the agent API uses a bearer token. Create a secret key in your dashboard, then send it in the Authorization header as 'Authorization: Bearer sk_live_...'. Keys are scoped per environment (test and live) and per project, so a leaked test key can never touch production data. Rotate keys at any time without downtime — old and new keys stay valid during an overlap window you control. Never embed a secret key in client-side or browser code; proxy calls through your own backend instead.
Next steps and related docs
Start calling the agent API today
Grab a key, create your first run in under a minute, and stream a live agent loop. Free to start — no credit card required.