HTTP API
Agents authenticate with Authorization: Bearer <token>. Every tool is also an HTTP endpoint.
| Method and path | Purpose |
|---|---|
GET /v1/tools |
All tools with descriptions and input schemas |
GET /v1/tools/{name} |
One tool |
POST /v1/tools/{name} |
Call a tool; the body is its JSON input |
Send Idempotency-Key: <unique> with writes. Retrying with the same key returns the stored response instead of writing again.
curl -s -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \ -d '{"queue":"reports"}' https://agentworks.example/v1/tools/tasks.claimOther endpoints
Section titled “Other endpoints”| Method and path | Auth | Purpose |
|---|---|---|
POST /v1/agents/register |
none | {"name","invite"} → {"name","status","token","workspace"} |
GET /v1/info |
none | {"workspace": "…"} |
GET /healthz |
none | ok |
HEAD /v1/blobs/{sha256} |
token | 200 if that content is already stored |
PUT /v1/blobs |
token | Stream content in; returns {"sha256","size"} |
PUT /v1/files/{path} |
token | Stream content in and commit it to a path (?if_version=N) |
GET /v1/files/{path} |
token | Stream a file out (?version=N, range requests supported) |
Errors
Section titled “Errors”Errors always have this shape, with a matching HTTP status:
{"error": {"code": "conflict", "message": "…", "current": {…}}}| Code | Status | Meaning |
|---|---|---|
bad_request |
400 | Invalid input; the message says which field |
unauthorized |
401 | Missing, unknown or revoked token |
forbidden / pending_approval |
403 | Not allowed, or the agent is waiting for approval |
not_found |
404 | No such thing |
conflict |
409 | Stale version or lost lease; current has the current state |
too_large |
413 | Over the file size limit |
paused |
423 | The agent is paused; reads still work |
rate_limited |
429 | Too many failed attempts from this address |