Public API v1

Programmatic access to your AGO workspace via scoped API keys

The Public API v1 provides programmatic access to your AGO workspace for server-to-server integrations. All endpoints use scoped API key authentication and return responses in a consistent JSON format.

Individual endpoint details (parameters, request/response schemas, and interactive playground) are available in the Endpoints section of the sidebar.

Base URL

https://your-tenant-id.api.useago.com/api/v1/

Authentication

Authenticate requests by including your API key in the X-API-Key header:

curl https://your-tenant-id.api.useago.com/api/v1/documents \
  -H "X-API-Key: ago_v1_sk_your_key_here"

API keys are created in Settings > Integrations > API Keys. See API Key Authentication for setup details.

Scopes

Each API key is assigned scopes that control endpoint access:

Scope	Description
knowledge:read	Read documents, sources, translations, and versions
knowledge:write	Create, update, delete, and bulk-manage documents and sources
conversations:read	Read conversation threads, messages, and feedback
conversations:write	Update thread evaluation, admin comment, admin tags, and admin status
tickets:read	Read tickets, statuses, statistics, and messages
analytics:read	Read dashboard analytics data
agents_config:read	Read agents, tools, prompt templates, and UI resource templates
agents_config:write	Create, update, and delete agents, tools, prompt templates, and UI resource templates
accounts:read	Read organizations, email domains, and users
custom_data_sources:read	Search and read rows in smart tables
custom_data_sources:write	Push (upsert) and delete rows in smart tables

A key with a write scope automatically has the corresponding read scope. For example, knowledge:write includes knowledge:read.

Response Format

All list endpoints return a consistent paginated structure:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "total": 150
}

Single-object endpoints return the object directly with an object field identifying the type.

Pagination

List endpoints accept these query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
page_size	integer	50	Items per page (max 100)

Error Format

All errors follow a consistent structure. See API Errors for the full error code reference.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "API key missing required scope: knowledge:write",
    "param": null,
    "doc_url": "https://ago.mintlify.app/api/errors#insufficient_scope"
  }
}

Type	HTTP Status	Description
authentication_error	401	Invalid, expired, or locked API key
permission_error	403	Missing required scope or IP not allowed
invalid_request_error	400, 404, 422	Bad parameters or resource not found
api_error	500	Internal server error

---

Available Resources

Knowledge

Documents and Sources — manage your knowledge base content. Supports CRUD, bulk operations (up to 100 items), translations, version history, file uploads, and table of contents management.

Scope: knowledge:read / knowledge:write

Conversations

Read conversation threads, messages, and user feedback. Includes CSV export. Set thread evaluation, admin comment, admin tags, and admin status.

Scope: conversations:read / conversations:write

When filtering by organization or exclude_organization, the API key must also have the accounts:read scope.

Tickets

Read tickets, statuses, statistics, and messages. Includes CSV export.

Scope: tickets:read

Analytics

Query dashboard analytics with date range filters and tab selection (evaluation, overview, knowledge, feedback, user-analytics, tickets).

Scope: analytics:read

Agents

Manage agent configurations including prompt templates, tools, sources, LLM settings, and feedback options.

Scope: agents_config:read / agents_config:write

When setting source_ids or pinned_document_ids on an agent, the API key must also have the knowledge:read scope.

Tools

Manage tool integrations attached to agents. Tool responses never include secret_key values — secret keys are stored encrypted and cannot be retrieved via the API.

Scope: agents_config:read / agents_config:write

Prompt Templates

Manage prompt templates used by agents. Content changes are versioned automatically. Deleting a template in use by an agent returns 409.

Scope: agents_config:read / agents_config:write

UI Resource Templates

Manage Jinja2 templates for dynamic UI components in the chat widget. Template content is validated for correct syntax on creation and update. The template_version is auto-incremented when content changes.

Scope: agents_config:read / agents_config:write

Organizations

Read organizations and their email domains.

Scope: accounts:read

Users

List and read customer users. Filter by organization, email, or search across name fields.

Scope: accounts:read

---

MCP

The API v1 also exposes an MCP server at /api/v1/mcp with 60 tools that mirror these REST endpoints. Connect Claude Desktop, Claude Code, Cursor, or any MCP client to manage your workspace through natural language. Same API key, same scopes.

---

Related Documentation

• API Errors
• API Key Authentication
• MCP Server
• SDK API