Use the REST API v1

The REST API automates agents, sources, channels, actions, conversations (including operator notes), 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 that you need. Copy the key immediately. Store the key as a server-side secret. Do not expose the key 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 API key determines the organization. Every response uses 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?"}'

If your client can consume a streaming response, use POST /chat/stream. Reuse the conversation or session identifier that the response schema returns. Do not invent your own identifiers.

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 (GET/POST /agents/{id}/conversations/{conversationId}/notes, PATCH/DELETE /conversations/notes/{noteId}), chat, custom roles, Inbox, and messages.

Conversation notes are free-form, operator-only annotations on a chat session. The end customer never sees them. A note is useful for tagging a transcript for later review, or as training data. If the organization has webhooks configured, a new note fires a conversation.note_created webhook event.

OAuth discovery (MCP clients)

The REST API above authenticates with an API key. The MCP server is separate. It uses OAuth. MCP clients discover how to authenticate by fetching two metadata documents.

Both documents are public. Clients do not need to authenticate to fetch them. Both are also served under /api/auth/ for clients that resolve them relative to the auth base path. Both copies emit the same JSON, including an identical scopes_supported list. See Scopes for what each scope grants. A client that supports Dynamic Client Registration registers itself at the registration_endpoint that these documents advertise. There is no key to create by hand.

The MCP endpoint resolves the organization in this order: the user's pinned MCP organization (set by switch_organization), then the most recent dashboard organization, then the oldest membership. If a membership is later revoked, the system discards the pin and resolves the organization again automatically. So a user who loses access to one organization does not lose the MCP connector.

Agent list fields

GET /agents returns pendingDeleteAt on each agent. This field gives the deadline for restoring an agent scheduled for deletion, or null for a live agent. The /agents endpoint returns live agents only, so the field is always null there. The MCP list_agents tool can filter to soft-deleted agents, so the field carries a value there.

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.

A Redis-backed limiter enforces rate limits on the server side. A recent internal change made the Redis client start lazily. This change treats the Redis connection as optional for local development only. Production rate-limiting behavior stays the same as described here.

If you suspect that a key leaked, rotate it from API Keys. For interactive administration from an AI coding client, use the MCP server instead.