Developers

REST API Reference.

Automate agents, tasks and workflows from your own systems. Every endpoint is scoped to your organization and checked against the key's role.

Authentication

Create an API key in Settings → API keys and send it as Authorization: Bearer ax_live_…. Keys act with the role you assign (never Owner). Browser sessions also work; cookie-authenticated writes must come from the same origin.

curl -X POST https://app.ainexusops.com/api/v1/tasks \
  -H "Authorization: Bearer $AINEXUSOPS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"<agent-uuid>","title":"Weekly expense review","instructions":"Flag unusual spend in the attached export","documentIds":["<doc-uuid>"]}'

Errors return { "error": { "code", "message", "recovery", "reference" } } with an HTTP status (401, 402 credits/plan, 403, 404, 409, 422, 429, 5xx). Rate limit: 600 requests/minute per key.

Authentication

POST	/api/v1/auth/register	—	Create an account and organization (sets a session cookie).
POST	/api/v1/auth/login	—	Sign in with email and password (sets a session cookie).
POST	/api/v1/auth/logout	session	Revoke the current session.

Agents

GET	/api/v1/agents	public	Marketplace catalog and categories.
GET	/api/v1/agents/:id	public	Agent details by id or slug.
POST	/api/v1/agents/:id/subscribe	agents.subscribe	Subscribe ({interval}); returns checkoutUrl for paid agents.
POST	/api/v1/agents/:id/activate	agents.configure	Optionally save configuration steps, then activate.
GET	/api/v1/my-agents	agents.view	Your organization's agents and lifecycle status.

Conversations

GET	/api/v1/conversations	agents.view	List conversations (?agentId, ?q).
POST	/api/v1/conversations	agents.use	Start a conversation {agentId, title?}.
GET	/api/v1/conversations/:id	agents.view	Conversation with messages and artifacts.
POST	/api/v1/conversations/:id/messages	agents.use	Send {content, documentIds?}; returns the structured reply.
GET	/api/v1/conversations/:id/export?format=md\|json	agents.view	Export a conversation.

Tasks & approvals

GET	/api/v1/tasks	tasks.view	List tasks (?status, ?agentId).
POST	/api/v1/tasks	tasks.create	Create {agentId, title, instructions, documentIds?, priority?} — runs asynchronously (202).
GET	/api/v1/tasks/:id	tasks.view	Task with steps, logs, artifacts and approvals.
DELETE	/api/v1/tasks/:id	tasks.view	Cancel a task.
GET	/api/v1/approvals	tasks.view	List approvals (?status).
POST	/api/v1/approvals/:id/decision	approvals.decide	{decision: approve\|reject, note?, editedArgs?}.

Workflows

GET	/api/v1/workflows	workflows.view	List workflows.
POST	/api/v1/workflows	workflows.edit	Create {name, trigger, nodes, edges}.
GET	/api/v1/workflows/:id/runs	workflows.view	Recent runs with traces.
POST	/api/v1/workflows/:id/runs	workflows.run	Start a run {input?}.
POST	/api/v1/hooks/workflows/:id?token=	webhook token	Webhook trigger (JSON body becomes {{input}}).

Documents, integrations, usage

GET	/api/v1/documents	documents.view	List documents (?q, ?tag).
POST	/api/v1/documents	documents.upload	Upload multipart field “file” (+ tags, folderId, agentAccess).
GET	/api/v1/documents/:id/download	documents.view	Download the original file.
GET	/api/v1/integrations	integrations.view	Integrations and connection status.
GET	/api/v1/usage?days=30	usage.view	Credits, tokens and executions.
GET	/api/v1/billing	billing.view	Plan, credits, invoices.
GET	/api/v1/notifications	any member	Notifications (?unread=1).
GET	/api/v1/reports/export	reports.export	CSV or PDF export (?format, ?kind, ?days).