API Reference - arg.ai

A REST API over workspaces, files, agents, and everything an agent can reach. Every page here is generated from the same OpenAPI spec the API serves, so the schemas match what the server accepts.

Base URL

https://api.arg.ai

Authentication

Pass an API key in the X-API-Key header:

curl https://api.arg.ai/api/workspaces \
  -H "X-API-Key: arg_live_your_key_here"

A user access token works too, as Authorization: Bearer <token>. A few account-level routes accept only a user session; those say so on the page. Not sure what a key is? GET /api/auth/principal reports whether it authenticates as a user or a service account, and which organization it is bound to. See Authentication and API keys.

Error format

Errors are JSON with a detail string:

{ "detail": "Not authorized" }

Code	Meaning
`200`	Success
`202`	Accepted - the work was queued or started in the background
`400`	Bad request, including validation failures
`401`	Missing or invalid credentials
`403`	Authenticated, but not permitted - or the route needs a different kind of credential
`404`	Not found
`409`	Conflict, such as a revision mismatch on a file write
`413`	Payload too large
`429`	Rate limited, or a per-workspace limit was reached
`500`	Server error

Where to start

Group	What it covers
Agent	Start agent runs, poll them, steer the queue, stop them
Agent Tools	Shell, file read/write/edit, and grep, called directly
Actions	The typed capability catalog and its run history
Search	Semantic search over a workspace or organization
Workspaces	Create, configure, and share workspaces
Files	Listing, content, uploads, downloads, versions, references
Sharing	Public links to files and folders
Chats	The chat records agent runs live in
Automations	Deploy triggers and run automations
Servers	Long-running processes on an HTTPS URL
Sites	Hosted sites built from a workspace folder
Notifications	Tell a human something happened
API Keys	Service accounts and credentials
Organizations	Members, roles, invitations
Models	Models available for a run
Account	The calling identity, profile, and sessions

Conventions

Paths are workspace-relative and start with /, for example /data/report.csv.
Long work is asynchronous. Endpoints that start something return an id to poll rather than holding the connection open.
Repeat safely. Where an operation supports it, send an idempotency key so a retry returns the original result instead of doing the work twice.