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. Use scoped API keys for server-to-server requests. Most REST responses are JSON; export and MCP endpoints have different response formats.

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 Developer > 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, admin status, and external ticket links
resolutions:read	Retrieve your integration’s resolution status and answer
resolutions:write	Run an AGO agent and receive a complete answer without streaming
tickets:read	Read tickets, statuses, statistics, and messages
tasks:read	Read board tasks, comments, statuses, labels, and assignable staff (active staff principals only)
tasks:write	Create, update, move, link, archive, delete, and comment on board tasks
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

To send text, a conversation, or an email to an AGO agent and receive its complete answer, use the Resolutions API. It supports JSON responses and direct Markdown or text bodies.

Paginated list endpoints return this structure:

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

Many single-object REST responses include an object field identifying the type. Check each endpoint’s schema: custom data source details omit this field, CSV exports return CSV, and MCP uses JSON-RPC, SSE, or an empty response depending on the operation.

Pagination

Paginated list endpoints accept these query parameters. Some lists, such as a document’s translations and versions, return all entries without pagination; check the individual endpoint’s parameters.

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

Error Format

The shared REST error handler returns the structure below. MCP JSON-RPC and session errors can have different fields. See API Errors for the full error code reference.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "Your API key does not have the 'knowledge:write' scope required for this endpoint.",
    "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, or client IP outside its allowlist
permission_error	403	Missing required scope
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

Documents can carry a page_id — your own identifier for the record, unique within a source. It makes syncing from an external system repeatable: POST /documents/bulk updates the matching document instead of creating a duplicate, and POST /documents/bulk-delete accepts source_id + page_ids so you never have to store AGO’s internal IDs on your side.

Search documents

Use POST /api/v1/documents/search to retrieve knowledge for an answer or find documents by exact attributes. Requires knowledge:read (knowledge:write also grants access). Authenticate with your X-API-Key header, as for other v1 endpoints. The MCP equivalent is search_documents.

{
  "query": "How do I configure SSO?",
  "filters": {
    "default_language": "en",
    "metadata": {"product": "ago", "plan": "enterprise"}
  },
  "limit": 5
}

Parameter	Description
query	Optional semantic search text, up to 8,000 characters. Results are ranked by similarity.
filters	Optional exact document attributes. All supplied filters must match.
limit	Maximum returned documents: 1–100, default 5.
include_content	Include full current content, including any override. Default false.

Supply a non-empty query or at least one filter. Supported filters are document_id, source_id, page_id, title, status, default_language, doc_type_id, and metadata. IDs are AGO UUIDs; page_id is your own document identifier.

String filters are case-sensitive and match the entire value. Each key inside metadata matches a top-level document attribute exactly: numbers differ from strings, null matches an explicit JSON null rather than a missing key, and arrays and objects must match in full. Metadata keys are literal names, not query operators. You can supply up to 50 metadata keys. Unknown filter names and invalid arguments are rejected.

To find a document in a particular source without a semantic search:

{
  "filters": {
    "source_id": "8c39fd46-936e-4a33-bdea-6970c45e8b29",
    "page_id": "sso-configuration"
  },
  "include_content": true
}

Without query, search includes documents that have not been indexed and returns matches in stable document-ID order. With query, search ranks indexed documents within the exact filters. No matches returns an empty data array; filters are never widened automatically. Retrieval failures return an error.

The response contains object: "search_result", mode: "semantic" or "exact", data, and has_more. Each match contains the document summary, current metadata, doc_type_id, url, is_internal, an excerpt of up to 1,200 characters, and score. Full content is included only when requested. In semantic mode, the excerpt comes from the best matching indexed passage, and the score is cosine similarity (higher is better, not a confidence percentage). In exact mode, the excerpt is the beginning of the current content and score is null.

has_more: true means additional matches were retrieved beyond your limit; increase limit or narrow your filters. Semantic search returns nearest matches and is not an exhaustive document listing. Use GET /api/v1/documents for paginated browsing.

Search uses the same tenant-wide read access as listing and reading documents, including drafts and internal documents. It does not reproduce a chat agent’s source selection or keyword restrictions. Documents marked is_internal: true may inform answers but must never be cited, quoted or named; their url is null.

Create a source

POST /api/v1/sources creates a knowledge source. Requires knowledge:write. Give the type by name in source_type (for example ago, mintlify, zendesk or notion), or by UUID in source_type_id — exactly one of the two. An unknown name returns 404 with the list of available types. Source responses include both source_type and source_type_id.

{
  "name": "Product docs",
  "source_type": "mintlify",
  "domain": "docs.example.com",
  "auto_sync_enabled": true
}

Then start the first import with POST /api/v1/sources/{source_id}/sync.

Export a knowledge source

POST /api/v1/sources/{source_id}/exports prepares a ZIP in the background. It contains full Markdown documents, folders for subpages, stored attachments, index.html and manifest.json. Requires knowledge:read; knowledge:write also grants access.

curl --fail \
  -H "X-API-Key: $AGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_files":true,"create_folders":true}' \
  "https://your-tenant-id.api.useago.com/api/v1/sources/$SOURCE_ID/exports"

The 202 response includes id, status and poll_after_seconds. Both options default to true; pass {} to use the defaults. Read GET /api/v1/source-exports/{id} with the same API key every five seconds until status is ready or failed. Pending and processing jobs have no download link. A failed job includes an error; request a new export after addressing it.

Ready jobs return download_url, download_url_expires_at, size_bytes and expires_at. The private download URL lasts up to four hours and redirects to the stored archive. Download it without sending your API key:

curl --fail --location "$DOWNLOAD_URL" --output source.zip
# Resume an interrupted download of the same export:
curl --fail --location --continue-at - "$DOWNLOAD_URL" --output source.zip
unzip source.zip -d source
rg -n -i "refund" source --glob '*.md'

Archives are retained for 24 hours after completion. Read the status endpoint again to get a fresh download link without rebuilding the ZIP. Links are bounded by archive expiry. The download endpoint returns 409 before the job is ready and 410 after expiry; cleaned-up jobs return 404. An expired signed link returns 401. Request a new export once the archive expires.

Set include_files to false for Markdown only, or create_folders to false for flat page paths. Exports include current AGO corrections, all document statuses, and documents from directly included sources. Limits are 10,000 documents and 100 MiB uncompressed; hierarchies deeper than 32 levels require flat paths. Unavailable attachments appear in the manifest’s warnings; external images stay remote links. Recognized inline Markdown links to exported pages and attachments become relative links.

Treat download URLs as private. Exported content may include internal documents: respect the manifest’s is_internal flags when producing answers. See MCP source exports for archive details.

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.

Link an External Ticket

POST /api/v1/conversations/{thread_id}/external-ticket attaches a ticket reference to a conversation using an AGO API key with conversations:write. It supports conversations from anonymous users and users authenticated through your application. No end-user JWT or Zendesk JWT is required.

Call this endpoint from your backend after verifying that the external ticket belongs to the conversation’s customer. For example, your backend can validate a ticket provider’s creation callback and then send the association to AGO. Keep the AGO API key on your server.

curl -X POST 'https://your-tenant-id.api.useago.com/api/v1/conversations/CONVERSATION_UUID/external-ticket' \
  -H 'X-API-Key: ago_v1_sk_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"ticketing_system":"zendesk","external_id":"5553308"}'

Field	Description
thread_id	AGO conversation UUID in the URL, in the workspace associated with your API key.
ticketing_system	Name of a configured ticketing system, using lowercase letters, digits, underscores or hyphens, starting with a letter, up to 64 characters.
external_id	The provider’s ticket ID as a nonblank string, up to 255 characters. Opaque IDs such as SUPPORT-42 are preserved. Send the actual ID expected by that provider’s connector.

The endpoint accepts references for configured ticketing systems without requiring a provider-specific authentication adapter. It trusts your backend’s authorization of the association and makes no call to the external provider to verify the ticket’s existence or requester.

A successful response has HTTP status 200:

{
  "object": "ticket",
  "id": "<AGO ticket UUID>",
  "ticketing_system": "zendesk",
  "external_id": "5553308",
  "conversation_id": "<AGO conversation UUID>"
}

AGO stores the reference, assigns the conversation owner as the local requester, and reuses an existing local ticket for the same ticketing system and external ID when compatible. A new local ticket initially has no subject or description. For Zendesk, linking immediately queues the standard synchronization for that ticket using the configured connector credentials, even when Sync Enabled is off. The response confirms the saved link; content arrives asynchronously when the worker runs. Enable Sync Enabled for ongoing hourly updates to open tickets. Other ticketing systems retain their existing synchronization behavior. Linking does not create a ticket in the external system. If queuing fails, the saved link remains intact; repeating the same call requests another refresh.

Repeating the same link is safe. Conflicting conversation links or a ticket already associated with another conversation/customer return 409. Missing authentication returns 401, insufficient scope 403, missing conversations 404, invalid references 422, and an unconfigured ticketing system 503. A failed linking request does not submit another external ticket.

This is a server integration endpoint. The SDK does not provide a browser ticket-linking endpoint; keep the API key out of browser code.

Tickets

Read tickets, statuses, forms, statistics, and messages. Includes CSV export. GET /api/v1/tickets/forms lists the ticket forms, which is how you find the ticket_form_id to attach to a user.

Scope: tickets:read

Tasks

Create, update, move, link and comment on the tasks of your team’s Tasks board. Requires Tasks to be enabled for your workspace, and the key’s creator (or the OAuth user) must be an active staff user. The task list uses cursor pagination (next_cursor) instead of page. See Tasks API.

Scope: tasks:read / tasks:write

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.

Agent drafts

Each agent has one draft shared by the builder, the API and MCP. Edit it, test it, then publish it; the live agent does not change until you publish.

Method	Endpoint	Description
GET	/api/v1/agents/{agent_id}/draft	Get the draft, or the published configuration with exists: false and version: 0
PUT	/api/v1/agents/{agent_id}/draft	Change fields of the draft. Only the fields in configuration change
POST	/api/v1/agents/{agent_id}/draft/preview	Send a question to the draft. The answer lists the knowledge documents the agent received. Pass the returned thread_id to continue the conversation, and add "retry": true to replace its last exchange instead
POST	/api/v1/agents/{agent_id}/draft/revert	Set the listed fields back to their live values
POST	/api/v1/agents/{agent_id}/draft/publish	Apply the draft to the live agent and delete the draft
DELETE	/api/v1/agents/{agent_id}/draft	Discard the draft

curl -X PUT https://your-tenant-id.api.useago.com/api/v1/agents/AGENT_ID/draft \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{"configuration": {"custom_prompt": "You are a concise support agent."}, "version": 0}'

curl -X POST https://your-tenant-id.api.useago.com/api/v1/agents/AGENT_ID/draft/preview \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{"question": "How do I reset my password?", "version": 1}'

curl -X POST https://your-tenant-id.api.useago.com/api/v1/agents/AGENT_ID/draft/publish \
  -H "X-API-Key: your-api-key" -H "Content-Type: application/json" \
  -d '{"version": 1}'

has_changes tells whether the draft still differs from the live agent, and changes lists each setting that differs with its live and draft values, the selected items it added and removed by name, and the names of a referenced model, template or icon in live_label and draft_label; a change that brings every setting back to the live values deletes the draft. Pass the version you last read to avoid overwriting someone else’s changes: a stale version returns 409 with code version_conflict. Publishing applies only the settings the draft changed, so edits made to other settings of the live agent in the meantime are kept. It returns 409 with code published_changed when a setting changed in the draft was also changed on the live agent; send "force": true to replace it. Previews run the full pipeline as the API key’s owner and read the agent’s knowledge, so they also require the knowledge:read scope. Configured tools can perform real actions.

Scope: agents_config:read (GET) / agents_config:write

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. Most tools mirror these REST endpoints; a few are MCP-only. 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