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

# Agent data API

> Share an agent's variable groups, databases and File Stores with the workspace's other agents, with no key, and with your own app or an AI assistant over the web API and MCP, with an endpoint key.

A store is private to its agent until you share it. Sharing a store lets the workspace's other agents, your own app or an AI assistant read it, and when you allow it, change it. Other agents need no key. Apps and AI assistants use one of the agent's endpoint keys. Nothing else can reach it from outside the agent. Variable groups, databases and File Stores can all be shared.

## Turn it on

**1. Open the store**

Open the agent, then its variable group, Database or File Store.

**2. Open Manage access**

Under the store's name, **Shared with** says who may use it now, for example "Shared with: Other agents · API", with its level, or **Not shared**. Click **Manage access**. A drawer opens with two tabs, **Access** and **Activity**. The same drawer opens from the agent's **Settings → External access**, which lists every store under **Data** with who may use it and its calls of the last 7 days.

**3. Choose the level and who**

On **Access**, choose **Read** or **Read & write**. The default, **Off**, keeps the store private. Then choose who may use it:

* **Other agents**: "Any agent in this workspace can use it. No key." For a store in a project, the agents of that project.
* **Apps (API)**: your own app, over the web API, with an endpoint key.
* **AI assistants (MCP)**: an assistant at the agent's MCP address, with an endpoint key.

A store you share for the first time starts with **Other agents**. While it is at **Read** or **Read & write**, at least one of them stays on: to stop sharing it, set it to **Off**.

**4. Make a key, for apps and AI assistants**

Make an endpoint key in the agent's **Settings → Keys**, or use one you have. See [Endpoint keys](https://docs.cogniagent.ai/api/endpoints.md#endpoint-keys). Any key of this agent can call every store open to apps or AI assistants. An agent that offers no endpoint can still have keys: while a store is open to apps or AI assistants, a key may list no endpoint and reaches only those stores. Other agents need no key.

**5. Call it**

Under **For developers**, the drawer shows the store's web address, its MCP address and ready `curl` calls to copy, for the ways in that are open.

Only people who can edit the agent change who may use a store. A store in **Unsorted** can't be shared: move it into an agent first.

| Level | What another agent or a caller may do |
| - | - |
| **Off** | Nothing. The store answers as if it didn't exist |
| **Read** | List and read |
| **Read & write** | Read, add, change and delete |

A way in that is not open answers like a store that doesn't exist: the web API answers 404 while **Apps (API)** is off, and the MCP address lists no tools for the store while **AI assistants (MCP)** is off. For what other agents do with a store you share, see [Use a store another agent shares](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares).

## What stays private

* **Secrets** are never readable or settable from outside. A read shows them masked, and a write to one is refused. Only people set a secret. Other agents never use them: their items can't put a secret of a shared group in a step.
* **Connection variables** are used only by the store's own agent. Other agents can't use them, and a key reads one only as the account's name.
* **Tables and columns** can't be changed from outside, only rows.
* **Other credentials** are refused. Personal access tokens and the workspace API key don't open stores. Only an endpoint key of the store's own agent does.
* **Another agent's store** gets the same answer as a store that doesn't exist.

## Web API

Every call goes under your agent's address, with the kind of store in the path:

```text theme={null}
https://app.cogniagent.ai/api/v1/agents/{agentId}
```

Send an endpoint key as in the [Endpoint API](https://docs.cogniagent.ai/api/endpoints.md#base-url-and-authentication):

```http theme={null}
Authorization: Bearer cek_YOUR_KEY
```

Only endpoint keys work here. Bodies are JSON. Calls count against the same limit as endpoint calls: 120 a minute per key.

| Path | What it holds |
| - | - |
| `/files` | File Stores |
| `/variables` | Variable groups |
| `/databases` | Databases |

`{store}`, `{group}` and `{db}` below can be the item's id, its key or its name, URL-encoded. Names are unique within a kind, so a name is enough.

### See what a key reaches

Each list answers with only the stores of that kind this key may use. `access` is `read` or `read_write`.

| Call | Answers |
| - | - |
| `GET /files` | `{ "fileStores": [{ "id", "key", "name", "access" }] }` |
| `GET /variables` | `{ "groups": [{ "id", "key", "name", "access" }] }` |
| `GET /databases` | `{ "databases": [{ "id", "key", "name", "access" }] }` |

```bash theme={null}
curl 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files' \
  -H 'Authorization: Bearer cek_YOUR_KEY'
```

### Environments

An agent can have more than one [environment](https://docs.cogniagent.ai/features/environments.md), such as Production and Demo. A call to `/files/{store}`, `/variables/{group}` or `/databases/{db}` reads and writes the environment the agent runs in, and the answer says which: `environment` in a JSON answer, or the `x-environment` header on a file download. When the agent is in Production, that is `Production`.

A key whose store is set to **Read & write** can name another environment with `?environment=<name>`. The name is not case sensitive, and `production` is Production.

* A key set to **Read** that names an environment gets 403 `environment_not_allowed`. It always reads the current one.
* A name the agent doesn't have gets 404 `environment_not_found`.
* A File Store or Database that is **Separate in each environment** has its own files or rows there. While they are still being copied, failed or are not set up, the call gets 409 `store_contents_not_ready`, such as "Leads has no rows in Demo yet." It is never answered from Production.
* A store that is **The same in every environment** answers the same whichever environment you name.
* A variable's value is never taken from Production. A variable with no value there reads as empty.

```bash theme={null}
curl -X PUT 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/variables/Business/opening_hours?environment=Demo' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'If-Match: "0"' \
  -H 'Content-Type: application/json' \
  -d '{ "value": "Always open" }'
```

```bash theme={null}
curl -G 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/databases/CRM/tables/leads/rows' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  --data-urlencode 'environment=Demo' \
  --data-urlencode 'limit=20'
```

### Files

A path starts at the store's top folder, for example `reports/2026/march.pdf`.

| Call | Does | Level |
| - | - | - |
| `GET /files/{store}` | List the top folder. `?recursive=true` lists everything below it. `?cursor=` gets the next page | Read |
| `GET /files/{store}?search=` | Search the whole store. Add `&folder=<path>`, `&type=` or `&modifiedAfter=` to narrow it | Read |
| `GET /files/{store}/{path}` | A folder answers its listing. A file answers its bytes | Read |
| `GET /files/{store}/{path}?meta=true` | A file's details as `{ "file": … }`. A folder answers 400 | Read |
| `PUT /files/{store}/{path}` | Upload the request body as the file. 201 when new. Missing folders above it are made. If a file is already there the call fails with 409 `conflict`, unless you add `?ifExists=replace` (overwrites, 200) or `?ifExists=keep_both` (keeps both files) | Read & write |
| `PUT /files/{store}/{path}?folder=true` | Make the folder and its parents. No body | Read & write |
| `PATCH /files/{store}/{path}` | Move, rename or both: `{ "toFolder": "archive", "newName": "march-final.pdf" }` | Read & write |
| `DELETE /files/{store}/{path}` | Move it to the Trash | Read & write |

`ifExists` is `fail` (the default), `replace` or `keep_both`.

Two things to know:

* `?search=` on a path is refused. To search inside a folder, put the search on the store and name the folder: `?search=…&folder=<path>`.
* A trailing slash does not mark a folder, and the server redirects it away. Use `?folder=true`.

```bash theme={null}
curl 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files/Reports?search=invoice&folder=2026' \
  -H 'Authorization: Bearer cek_YOUR_KEY'
```

```bash theme={null}
curl 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files/Reports/2026/march.pdf' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -o march.pdf
```

```bash theme={null}
curl -X PUT 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files/Reports/2026/march.pdf?ifExists=replace' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'Content-Type: application/pdf' \
  --data-binary @march.pdf
```

```bash theme={null}
curl -X PUT 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files/Reports/2027/q1?folder=true' \
  -H 'Authorization: Bearer cek_YOUR_KEY'
```

```bash theme={null}
curl -X PATCH 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/files/Reports/2026/march.pdf' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "toFolder": "archive", "newName": "march-final.pdf" }'
```

A web page or image with scripts that an outside key writes is never shown as a page in the app. People see its text, or download it.

### Variables

| Call | Does | Level |
| - | - | - |
| `GET /variables/{group}` | The group's variables as `{ "environment": "Production", "variables": [...] }`. `?search=` matches names, descriptions and values that are not secret | Read |
| `GET /variables/{group}/{name}` | One variable as `{ "environment", "variable" }` | Read |
| `PUT /variables/{group}/{name}` | Add a variable or change it. Body `{ "type"?, "value", "description"? }`. Answers `{ "environment", "variable" }`, 201 when new and 200 when changed | Read & write |
| `DELETE /variables/{group}/{name}` | Delete it. Answers `{ "deleted": true }` | Read & write |

A `DELETE` of a variable that something uses fails with 409 `variable_in_use`. The people who work in the app see the full **Used by** list; a key learns only the kinds. Change those uses, then delete again.

Writes take an optional `If-Match: <revision>` header, using the revision number from the variable's answer. If someone changed the variable since, the call fails with 409 `revision_conflict` and the current revision, so read it again and retry. A value that is not a number is 400 `invalid_request`.

Secrets are always masked, and only people in the app can set a secret's value.

A variable group has a value per environment: see [Environments](#environments). A variable's `revision` counts per environment. `revision` 0 means the variable has no value in that environment yet. Send `If-Match: "0"` on a `PUT` to write only if there is still no value there: the first write wins, and a later one gets 409 `revision_conflict` with the current revision.

```bash theme={null}
curl 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/variables/Business?search=hours' \
  -H 'Authorization: Bearer cek_YOUR_KEY'
```

```bash theme={null}
curl -X PUT 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/variables/Business/opening_hours' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "value": "Mon-Fri 9:00-17:00", "description": "Shown to callers" }'
```

```bash theme={null}
curl -X DELETE 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/variables/Business/opening_hours' \
  -H 'Authorization: Bearer cek_YOUR_KEY'
```

#### Connection variables

A variable of type `connection` holds an account of one app, shared with the workspace. It reads as an object and never shows credentials:

```json theme={null}
{ "app": "hubspot", "connectionId": "…", "connectionName": "Sales CRM" }
```

An empty one reads as `null`. Like every variable, it has a value per [environment](#environments). See [Connection variables](https://docs.cogniagent.ai/features/agent-variables.md#connection-variables).

A `PUT` sets one:

* The body's `value` is the account's id, or `null` to clear it.
* To create one, send `"type": "connection"` and `"connectionApp"`, the id of the app. Without it the call fails with `variable_type_mismatch`: "A Connection variable needs its app." The app is fixed after that.
* The account must be in the workspace, of the variable's app, shared, and one the person behind the key may use.
* Only a person sets one. A key counts as the person who made it. If that person has left the workspace, the call is refused.
* A `DELETE` of one is a person's call too.

| `code` | When |
| - | - |
| `actor_not_allowed` | "A Connection variable is set by a person." A step, coworker or conversation tried. Also when the key's maker is no longer in the workspace |
| `connection_not_found` | The account is not in the workspace |
| `connection_wrong_app` | The account is of another app |
| `connection_not_shared` | The account is private. Share it with the workspace first |
| `connection_other_project` | The account belongs to another project than the agent's |
| `connection_not_usable` | The person behind the key may not use the account |

These answer 400. A step can't use a Connection variable of another app, or one the agent doesn't have: that is refused as `agent_variable_unknown` when the step is saved.

### Databases

| Call | Does | Level |
| - | - | - |
| `GET /databases/{db}/tables` | The tables, with their columns | Read |
| `GET /databases/{db}/tables/{table}/rows?filter=&sort=&limit=&cursor=` | Find rows, a page at a time | Read |
| `GET /databases/{db}/tables/{table}/rows/{id}` | One row | Read |
| `POST /databases/{db}/query` | Run one read-only SELECT with parameters | Read |
| `POST /databases/{db}/tables/{table}/rows` | Add one row, or `{ "rows": [...] }` up to 1,000 | Read & write |
| `PATCH /databases/{db}/tables/{table}/rows/{id}` | Change one row | Read & write |
| `PATCH /databases/{db}/tables/{table}/rows?filter=` | Change every row a filter matches. The filter is required | Read & write |
| `DELETE /databases/{db}/tables/{table}/rows/{id}` | Delete one row | Read & write |

`filter` is JSON in the web address, with the operators `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `like` and `is_null`:

```text theme={null}
{"status":"open","amount":{"gt":100}}
```

`POST /databases/{db}/query` always runs read-only, even on a store set to **Read & write**. To change data, use the row calls.

```bash theme={null}
curl -G 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/databases/CRM/tables/leads/rows' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  --data-urlencode 'filter={"status":"open"}' \
  --data-urlencode 'limit=20'
```

```bash theme={null}
curl -X POST 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/databases/CRM/query' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "sql": "SELECT status, COUNT(*) AS n FROM leads GROUP BY status", "params": [] }'
```

```bash theme={null}
curl -X POST 'https://app.cogniagent.ai/api/v1/agents/AGENT_ID/databases/CRM/tables/leads/rows' \
  -H 'Authorization: Bearer cek_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Ada Lovelace", "email": "ada@example.com", "status": "open" }'
```

### Errors

Errors look like `{ "error": { "code": "…", "message": "…" } }`.

| HTTP | `code` | When |
| - | - | - |
| 400 | `invalid_request` | The call is malformed or can't be done, such as `?meta=true` on a folder |
| 400 | `variable_name_invalid` | The name is not a valid variable name |
| 400 | `variable_type_mismatch` | The value does not fit the variable's type |
| 401 | `invalid_key` | The key is missing, unknown, revoked or expired |
| 403 | `store_read_only` | A write on a store set to **Read** |
| 403 | `environment_not_allowed` | A key set to **Read** named an environment with `?environment=` |
| 403 | `secret_people_only` | A secret is set by a person in the app: a key cannot set it, change it or delete it |
| 404 | `not_found` | The store or item doesn't exist, is **Off**, is not open to **Apps (API)**, or this key may not see it. These look the same on purpose |
| 404 | `environment_not_found` | The `?environment=` name is not an environment of the agent |
| 404 | `variable_not_found` | The variable is not in the group |
| 405 | `method_not_allowed` | That method doesn't work on this path. The `Allow` header lists the ones that do |
| 409 | `conflict` | A file or folder with that name already exists. Use `ifExists=replace` or `keep_both` |
| 409 | `store_contents_not_ready` | The store's files or rows in that environment are not ready yet, such as "Leads has no rows in Demo yet." See [Environments](#environments) |
| 409 | `variable_exists` | A variable with that name already exists |
| 409 | `variable_in_use` | A delete of a variable that a workflow, conversation flow or coworker of the agent still uses. The message says what uses it by kind, such as "2 workflows and 1 coworker". It names no item |
| 409 | `revision_conflict` | "This variable was changed by someone else." Read it again and retry. The answer carries the current revision |
| 413 | `body_too_large` | A file upload over 50 MB |
| 429 | `busy` | Too many file calls from this key or workspace are running at once. Try again shortly |
| 503 | `busy` | The store is not ready yet. Try again shortly |
| 429 | `rate_limited` | The limit of 120 calls a minute was reached |
| 503 | `store_unavailable` | The store can't be reached right now. Try again shortly |
| 503 | `unavailable` | The service can't answer right now. Try again shortly |
| 507 | `size_limit` | The workspace's storage or the database is full |

## MCP

An agent's MCP address lists a set of tools for each store open to **AI assistants (MCP)**:

```text theme={null}
https://embed.cogniagent.ai/mcp/agents/<agent-id>
```

Connect with an endpoint key of the agent, as in [AI assistants over MCP](https://docs.cogniagent.ai/api/endpoints.md#ai-assistants-over-mcp). Tools are named `<key>__<action>`, for example `CRM__find_rows`. A store that is **Off**, or not open to AI assistants, lists nothing, and an assistant sees a change on its next call.

| Store | Read | Added by Read & write |
| - | - | - |
| **Variable groups** | `list_variables`, `get_variable`, `search_variables` | `set_variable`, `delete_variable` |
| **Database** | `list_tables`, `describe_table`, `find_rows`, `query` | `insert_rows`, `update_rows`, `delete_rows` |
| **File Store** | `list_files`, `read_file`, `search_files` | `write_file`, `create_folder`, `move_file`, `delete_file` |

Every store tool reads and writes the environment the agent runs in, and takes no `environment`. A Database or File Store whose rows or files are not ready there answers `store_contents_not_ready`. The variable tools' answers carry `environment`. `list_variables` and `search_variables` answer `{ variables, truncated }`. `query` is always read-only. `read_file` returns text, or a binary file up to 1 MB as base64. `write_file` takes up to 5 MB a call; use the web API for larger files. `delete_file` moves the file to the Trash. An agent's address lists at most 100 tools, endpoints first and then stores by name. A store beyond the limit is left out.

```bash theme={null}
claude mcp add-json cogniagent-crm '{"type":"http","url":"https://embed.cogniagent.ai/mcp/agents/AGENT_ID","headers":{"Authorization":"Bearer cek_YOUR_KEY"}}'
```

## Activity

The **Activity** tab of **Manage access** lists the calls made from outside the agent: which other agent and which of its items, or which key, whether through another agent, the web API or MCP, the action, the table, variable or file it touched, whether it worked, and when. Another agent's item you can't open is not named. A refused call shows as "Refused: …" with why. Values, rows, SQL and file contents are never recorded. When a copy of an agent that uses the store takes its contents, the row reads **Copied into a shared agent**. Each write is one row. Reads in the same minute from one key, or from one item of another agent, are counted together, with failed reads counted apart by what went wrong. Entries are kept 30 days.

## Call a store from another agent

Another agent needs no key. Turn on **Other agents** in the store's **Manage access**, and the store shows in that agent's pickers under **Shared by other agents**. See [Use a store another agent shares](https://docs.cogniagent.ai/features/data-stores.md#use-a-store-another-agent-shares).

Another agent always reaches the store's Production values, rows and files, whatever environment either agent runs in. While that agent runs in another environment, its writes are refused with `link_read_only_outside_production`: "Demo can read Leads from Sales but not change it. Only Production can."

## Copies

A copy of a shared agent has every store at **Off**, shared with no one, and no endpoint keys come with it. A store another agent shares with the agent travels as the copy's own store, with its structure, and with its contents only when they are included and may still be shared when the copy is made. See [Stores from other agents](https://docs.cogniagent.ai/features/sharing-agents.md#stores-from-other-agents).

## Next steps

> [card] [Endpoint API](https://docs.cogniagent.ai/api/endpoints.md)
>
> Keys, limits and calls to your agent's endpoints.

> [card] [Data stores](https://docs.cogniagent.ai/features/data-stores.md)
>
> What each kind of store holds, and how other agents use one.

> [card] [Agent variables and secrets](https://docs.cogniagent.ai/features/agent-variables.md)
>
> Where secrets are kept and how they stay private.

> [card] [Connect MCP](https://docs.cogniagent.ai/mcp-server.md)
>
> The tools that build and run your workspace.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.