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

# API & MCP Access

> Programmatic access to collections via REST and MCP

Everything you do in the Collections UI is available programmatically, through two interfaces:

* A **REST API** for applications and scripts — fully documented with an interactive playground
* An **MCP endpoint** (JSON-RPC 2.0) for AI agents and MCP-compatible clients

<Card title="Collections API Reference" icon="code" href="/api-reference/ai-collection">
  Full endpoint documentation with request/response schemas and a live playground — collections CRUD, records, analytics, and the MCP endpoint.
</Card>

## REST API at a Glance

| Area            | What you can do                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------- |
| **Collections** | List, create (with a typed schema), read, update metadata and sharing, delete                   |
| **Records**     | Query with MongoDB-style filters, insert in batches (up to 1,000), read, update, upsert, delete |
| **Analytics**   | Count, distinct values, aggregations (sum, avg, count, group by)                                |

Queries accept MongoDB-style filters:

```json theme={null}
{
  "status": "active",
  "deal_value": { "$gte": 50000 },
  "stage": { "$in": ["Proposal", "Negotiation"] }
}
```

For safety, operators that execute code or cross-reference data (`$where`, `$function`, `$expr`, `$lookup`, `$merge`, `$accumulator`, `$out`) are rejected.

## MCP Endpoint

Agents and MCP clients connect to the workspace webhook endpoint (shown in the **Settings** page of the product):

```
POST /v2/workspaces/slug:ai-collection-v3/webhooks/ai-collection/mcp
```

Protocol: **JSON-RPC 2.0** (`initialize`, `tools/list`, `tools/call`). The endpoint exposes the data tools agents use:

| Tool                     | Purpose                                                      |
| ------------------------ | ------------------------------------------------------------ |
| `data_create_collection` | Create a named collection, optionally with a typed schema    |
| `data_insert`            | Insert one or more records                                   |
| `data_query`             | Search records with filter, sort, and pagination             |
| `data_get`               | Fetch a single record by ID                                  |
| `data_update`            | Update records matching a filter                             |
| `data_upsert`            | Insert-or-update on matching fields                          |
| `data_delete`            | Delete records (bulk delete requires explicit configuration) |
| `data_count`             | Count matching records                                       |
| `data_distinct`          | Unique values of a field                                     |
| `data_aggregate`         | Sum / average / count with grouping                          |

Tool arguments mirror the REST payloads — see the [API Reference](/api-reference/ai-collection) for the schemas.

### Schema Format

When creating a collection programmatically, columns are declared as:

```json theme={null}
{
  "name": "products",
  "properties": {
    "product_name": { "type": "text" },
    "price": { "type": "double" },
    "stock": { "type": "integer", "nullable": true },
    "active": { "type": "boolean" },
    "released_at": { "type": "date" },
    "specs": { "type": "json" }
  }
}
```

Supported types: `text`, `integer`, `double`, `boolean`, `date`, `datetime`, `json`, `array`.

## Limits

| Limit             | Value                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------- |
| Batch insert      | 1,000 records per call                                                                 |
| Query page size   | 100 records max per call (default 20) — paginate for more                              |
| Aggregation steps | 10 per call                                                                            |
| Distinct values   | 1,000 max returned                                                                     |
| Collection name   | 64 characters, alphanumeric plus `-` and `_`                                           |
| Rate limits       | 100 requests/min for reads and most operations; 20/min for inserts; 50/min for upserts |

## Behavior Notes

* **Protected fields** — record IDs, creation timestamps, and ownership metadata are managed by the platform; they are stripped from update payloads.
* **Bulk deletes are opt-in** — deleting multiple records in one call is rejected unless enabled in the platform configuration.
* **Duplicate names are rejected** — collection names are unique per owner.
* **Audit events** — every write (`insert`, `update`, `upsert`, `delete`, `collection created`) emits an audit event with the actor and target collection.

## Next Steps

<CardGroup cols="2">
  <Card title="Collections API Reference" icon="book" href="/api-reference/ai-collection">
    Interactive playground and full schemas
  </Card>

  <Card title="Using Collections with Agents" icon="robot" href="/products/ai-collection/agents">
    The user-level view of agent access
  </Card>
</CardGroup>