> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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](/security/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:

```json theme={null}
{
  "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](/api/errors) for the full error code reference.

```json theme={null}
{
  "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`

<Note>
  When filtering by `organization` or `exclude_organization`, the API key must also have the `accounts:read` scope.
</Note>

### 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`

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

### 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](/api/mcp-tool-api) 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/errors)
* [API Key Authentication](/security/api-key-authentication)
* [MCP Server](/api/mcp-tool-api)
* [SDK API](/api/sdk-api)