Use the REST API v1

The REST API automates agents, sources, channels, actions, conversations, analytics, Inbox, and chat. API access requires a paid plan.

Create a key

Open workspace API Keys, create a key with the minimum read or write scopes you need, and copy it immediately. Store it as a server-side secret; never expose it in browser code.

Make a request

All endpoints use this base URL:

https://www.agentstack.build/api/v1

Pass the key as a bearer token:

curl https://www.agentstack.build/api/v1/agents \
  -H "Authorization: Bearer $AGENTSTACK_API_KEY"

The organization is resolved from the API key. Responses use a consistent envelope with success, data, and error fields.

Chat with an agent

curl https://www.agentstack.build/api/v1/chat \
  -X POST \
  -H "Authorization: Bearer $AGENTSTACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"YOUR_AGENT_ID","message":"What is your return policy?"}'

Use POST /chat/stream when your client can consume a streaming response. Reuse the returned conversation/session identifiers according to the response schema rather than inventing them.

Find endpoints and schemas

The generated OpenAPI 3.1 document is the complete reference for current paths, request bodies, and response schemas. It includes agents, sources and ingestion, channels, actions, activity, analytics, topics, webhooks, contacts, conversations, chat, custom roles, Inbox, and messages.

Handle errors and limits

• 401: key is missing, invalid, or expired.
• 403: the plan or key scope does not permit the operation.
• 429: respect Retry-After and the rate-limit headers before retrying.
• Validation errors return 400 with a machine-readable error code and message.

Rotate a key from API Keys if it may have been exposed. For interactive administration from an AI coding client, use the MCP server instead.