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

# Workspace API

> Read-only API access to your workspace data using workspace API keys

The Workspace API gives external systems read-only access to workspace-level and per-agent data — the same information visible in the Workspace Explorer capability, but accessible over HTTP.

<Note>
  Every endpoint on this page is backed by the **Workspace Explorer** capability, so the same data is reachable two ways: over HTTP with a workspace API key, or by giving an agent the Workspace Explorer capability and asking it in plain language. Both routes hit the same code and apply the same access rules and redaction. Asking an agent is usually faster for exploring or one-off questions; the HTTP API is for systems that need the data on a schedule.
</Note>

<Info>
  This page is the guide. For the machine-readable spec — every endpoint with its parameters, response fields, and error codes — see the **API Reference** tab in the top navigation.
</Info>

## Base URL

All requests go to the Abundly service host:

```
https://service.abundly.ai
```

<Note>
  Enterprise customers on a dedicated deployment have their own service host, in the form `https://<your-tenant>.service.abundly.ai`.
</Note>

## Authentication

Requests are authenticated with workspace API keys (`wk_...`) that have the **Workspace read API** scope enabled.

Include the key as a Bearer token:

```
Authorization: Bearer wk_your_key_here
```

### Enabling workspace API access

1. Go to **Workspace Settings → API Keys**
2. Create a new key (or edit an existing one)
3. Check the **Workspace read API** scope
4. Save and copy the key

<Warning>
  Workspace API keys grant read access to all workspace data including chat histories, messages, member information, and agent configurations. Keep them secure and rotate them regularly.
</Warning>

## Workspace endpoints

All endpoints are `GET` requests under `/workspaceapi/`. No workspace ID is needed in the URL — the key identifies the workspace.

| Endpoint                            | Description                                                      |
| ----------------------------------- | ---------------------------------------------------------------- |
| `/workspaceapi/overview`            | Workspace settings, feature flags, and configuration             |
| `/workspaceapi/credits`             | Credit balance and per-agent/per-team usage                      |
| `/workspaceapi/members`             | All workspace members with roles and team memberships            |
| `/workspaceapi/invites`             | Pending and expired workspace invitations                        |
| `/workspaceapi/teams`               | All teams (add `?includeMembers=true` for member lists)          |
| `/workspaceapi/teams/:teamId`       | Single team details with full member list                        |
| `/workspaceapi/secrets`             | Secret names and metadata (values are never exposed)             |
| `/workspaceapi/http-apis`           | Shared HTTP API capability configurations                        |
| `/workspaceapi/capability-settings` | Which capabilities are available and their defaults              |
| `/workspaceapi/security-settings`   | Security alert configuration                                     |
| `/workspaceapi/agents`              | All agents (add `?includeOverview=true` for management overview) |
| `/workspaceapi/value-capture`       | Value capture compliance summary across agents                   |

### Reading the agent list

`/workspaceapi/agents` returns one entry per agent. `id`, `name`, `groupId`, `adminOnly`, `enabled`, `capabilities`, `tags`, `updatedAt` and `isPrivate` are always present; `description`, `imageUrl`, `adminRestriction`, `agentDiscoverability`, `dailyCreditLimit`, `criticality` and `valueEntries` appear when they are set.

`capabilities` is a mixed array: plain strings for capabilities with no settings, and `{ name, settings }` objects for those that have them. Normalise to the name before counting or comparing:

```bash theme={null}
curl -s https://service.abundly.ai/workspaceapi/agents \
  -H "Authorization: Bearer wk_your_key_here" \
  | jq '[.agents[].capabilities[] | if type == "string" then . else .name end] | group_by(.) | map({(.[0]): length}) | add'
```

Adding `?includeOverview=true` attaches an `overview` object with `lastUsageByAgent` (a map of agent id to timestamp) and `reducedAgents`, which carries an entry for **every** agent — private ones included — with its `access`, full instructions text, `llmPreferences`, `httpApis`, `mcpServers`, and the exposure flags (`mcpServerExposed`, `httpApiExposed`, `webhooksExposed`, `widgetExposed`, `documentApiExposed`).

### Who owns an agent

There is no `createdBy` field. Ownership is expressed through the `access` object on each agent:

| Field             | Meaning                                                                                                                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `access.customer` | The workspace-wide default level: `admin`, `edit`, `use`, or `none`. `none` means the agent is private — only the users listed in `access.users` can reach it |
| `access.users[]`  | Explicit per-user grants, each with a `level` of `admin`, `edit`, or `use`                                                                                    |

To attribute an agent to the person who built it, take the `access.users[]` entry with level `admin`. A single `?includeOverview=true` call covers the whole workspace, including private agents, so builder attribution needs no per-agent requests.

## Per-agent endpoints

Drill into a specific agent's data. The agent must belong to the workspace and not be private — see [Private agents](#private-agents) below.

| Endpoint                                             | Description                                                                                            |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `/workspaceapi/agents/:agentId`                      | Full agent configuration                                                                               |
| `/workspaceapi/agents/:agentId/chats`                | Chat conversation list                                                                                 |
| `/workspaceapi/agents/:agentId/chats/:chatId`        | Single chat with full message history                                                                  |
| `/workspaceapi/agents/:agentId/documents`            | Agent documents and folders (add `?excludeContent=true` for metadata only)                             |
| `/workspaceapi/agents/:agentId/documents/:docId`     | Single document with content                                                                           |
| `/workspaceapi/agents/:agentId/diary`                | Diary entries (filters: `?date=`, `?conversationId=`, `?year=&month=`)                                 |
| `/workspaceapi/agents/:agentId/activity-log`         | Activity log (filters: `?limit=`, `?page=`, `?pageSize=`, `?entryId=`, `?newerThan=`)                  |
| `/workspaceapi/agents/:agentId/messages`             | Email/SMS messages (filters: `?page=`, `?pageSize=`, `?direction=`, `?channel=`, `?since=`, `?until=`) |
| `/workspaceapi/agents/:agentId/evals`                | Eval definitions (add `?includeRecentResults=true` for results)                                        |
| `/workspaceapi/agents/:agentId/connected-agents`     | Agent-to-agent connections                                                                             |
| `/workspaceapi/agents/:agentId/mcp-servers`          | Connected MCP servers                                                                                  |
| `/workspaceapi/agents/:agentId/tool-usage/:toolName` | Usage stats for one tool, by exact tool name (filters: `?since=`, `?limit=`)                           |

## Private agents

An agent whose default access is **Nothing** (`access.customer` is `none`) is restricted to a specific list of users. The Workspace API has no calling user to check that list against, so it treats every private agent as off-limits for content reads.

<Warning>
  Private agents appear in `/agents`, in `overview.reducedAgents`, in `overview.lastUsageByAgent` and in `/credits` `agentUsage` — but **every** `/agents/:agentId` route and subresource returns `403` for them. A loop that lists agents and then fetches each one's detail will silently skip them, and any count built that way will be too low.
</Warning>

The `403` says exactly what happened:

```json theme={null}
{
  "error": "Agent 'AGENT_ID' has default access 'Nothing' (restricted to a specific user list). The explorer cannot open it — only list_workspace_agents will surface it (with isPrivate=true)."
}
```

The reliable pattern for workspace-wide reporting is to take everything from one `/agents?includeOverview=true` call — which already contains access, instructions, integrations and usage timestamps for every agent — and to treat the per-agent endpoints as a drill-down for individual non-private agents rather than something to iterate. Check `isPrivate` before requesting detail for an agent.

## Pagination

Only two endpoints paginate:

| Endpoint                        | Behavior                                                                                                                                                                                                      |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/agents/:agentId/messages`     | `?page=` (default `1`) and `?pageSize=` (default `50`, max `200`). The response echoes `page` and `pageSize` and includes `totalCount` for the current filter                                                 |
| `/agents/:agentId/activity-log` | `?page=` and `?pageSize=` (default `50`, max `200`). Passing either one turns on pagination and the response echoes both. Without either, you get the most recent entries capped by `?limit=` (default `100`) |

Every other endpoint returns its complete set in one response, and `page`/`pageSize` are ignored there.

## Credits are a live snapshot

`/workspaceapi/credits` reports the current state only: `creditsUsedToday` per agent and `creditsUsedThisMonth` per team, alongside the workspace balances. It accepts no date parameters and there is no historical endpoint — if you need a time series, snapshot the response yourself on a schedule.

`agentUsage` is keyed by agent id and covers every agent in the workspace, including disabled and private ones. `groupUsage` is keyed by team id.

## Documents and response size

`/workspaceapi/agents/:agentId/documents` inlines the complete `textContent` of every document in the list response. That is deliberate — it makes one call enough for an audit or a backup — but on an agent with many large documents the response gets big.

Add `?excludeContent=true` to get metadata only. `textContent` and `data` are dropped from every entry; names, mime types, scopes, and folder structure stay. Use it to enumerate documents cheaply, then fetch the ones you need individually from `/documents/:docId`.

```bash theme={null}
curl -s "https://service.abundly.ai/workspaceapi/agents/AGENT_ID/documents?excludeContent=true" \
  -H "Authorization: Bearer wk_your_key_here" | jq
```

## Tool usage

`/workspaceapi/agents/:agentId/tool-usage/:toolName` counts how often one specific tool was called by one agent, across both chat conversations and trigger runs.

### Tools are not capabilities

A capability is a bundle of tools that you switch on for an agent. A tool is a single action the agent can take. `:toolName` expects the **tool** name, which is always lowercase with underscores — for example `code_execution`, `send_email`, `get_document`, `query_document_data`.

Capability names such as `codeExecution` or `readDocuments` are not tool names and will never match. A capability like `readDocuments` contains a dozen or more tools, so there is no single usage number for it — query the individual tools and add them up.

### Finding the tool names

The quickest way is to ask an agent. Every agent knows the names of its own tools, so "What tools do you have, and what are they called?" gets you the exact strings to query. To ask about a *different* agent — "Which tools has Buggsy used this month, and how often?" — use an agent with the **Workspace Explorer** capability, which can read across the workspace.

To do it over the API, read the `steps` of an activity log entry. Each step with a `toolName` gives you a name you can query directly:

```bash theme={null}
curl -s "https://service.abundly.ai/workspaceapi/agents/AGENT_ID/activity-log?entryId=ENTRY_ID" \
  -H "Authorization: Bearer wk_your_key_here" | jq -r '[.steps[]?.toolName] | unique'
```

Steps of type `thinking` and `text` have no `toolName`, so expect `null` in that list.

### Reading the response

```json theme={null}
{
  "toolName": "code_execution",
  "lastUsedAt": "2026-08-09T14:22:07.881Z",
  "totalCount": 3989,
  "since": "2026-07-11T00:00:00.000Z",
  "recentCalls": [{ "timestamp": "...", "input": {}, "source": "trigger" }]
}
```

### Unknown tool names

A name that does not exist returns `404`, so a typo or a capability id fails loudly instead of looking like an idle tool:

```json theme={null}
{ "error": "Tool 'codeExecution' does not exist. Tool names are lowercase with underscores..." }
```

`200` with `totalCount: 0` therefore means something specific: this is a real tool, and this agent has not called it in the window.

<Note>
  Existence is checked against the platform's tools plus the MCP tools your agent has discovered — not against the capabilities the agent has enabled. Asking about a real tool the agent doesn't have returns `200` with a zero count, not `404`. A tool that already has usage recorded never returns `404`, even if the MCP server behind it has since been renamed, disabled, or removed.
</Note>

`totalCount` is the complete count over the window. `recentCalls` is only the most recent calls, and it is not paginated:

| Filter    | Behavior                                                                                                                |
| --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `?since=` | ISO date. Counts usage from this timestamp onward. Defaults to 30 days ago, so lifetime totals need an explicit `since` |
| `?limit=` | How many entries in `recentCalls`. Defaults to `10`, maximum `50`. Values above `50` return `400`                       |

For a complete call history rather than the latest few, page through `/activity-log` with `?page=` and `?pageSize=` and read the steps.

## Example

```bash theme={null}
curl -s https://service.abundly.ai/workspaceapi/agents \
  -H "Authorization: Bearer wk_your_key_here" | jq
```

## Status codes

| Code  | Meaning                                                                                                                                                                                                           |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Success. Also returned for empty results — for example an agent with no matching data                                                                                                                             |
| `400` | Invalid filter value, such as a `limit` above the endpoint's maximum or an unparseable date                                                                                                                       |
| `401` | Missing key, malformed key, or a key that isn't a `wk_` workspace key                                                                                                                                             |
| `403` | Valid key without the **Workspace read API** scope, or a [private agent](#private-agents)                                                                                                                         |
| `404` | Unknown or malformed agent, team, chat, document, or activity-log entry id, including soft-deleted agents. Also an unknown tool name on `/tool-usage/`, and any path that isn't one of the endpoints listed above |

Every response from `/workspaceapi/`, including errors, is JSON. Errors carry a single `error` field with a human-readable message:

```json theme={null}
{ "error": "Access denied. A workspace API key (wk_) is required." }
```

## Rate limits

There is no enforced rate limit on the Workspace API today, and responses carry no rate-limit headers. Keep request rates reasonable — roughly one request per second is plenty for reporting and sync workloads, and the workspace-wide endpoints are designed so that most jobs need only a handful of calls. Limits may be introduced later, so avoid building anything that depends on unlimited throughput.

## Data redaction

Credential values, API keys, and secret values are automatically stripped from all responses — the same redaction rules applied by the Workspace Explorer capability. Secret names and metadata are included so you can see what's configured without exposing sensitive values.

## API key scopes

Workspace API keys support two scopes that can be enabled independently:

| Scope                      | What it grants                                                                                                   |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Custom agent endpoints** | Access to agent-exposed APIs (HTTP API, Document API, MCP, Widget) on agents with "Allow Workspace Keys" enabled |
| **Workspace read API**     | Read-only access to workspace and agent data via the `/workspaceapi/` endpoints                                  |

Existing keys default to **Custom agent endpoints** only. Enable **Workspace read API** explicitly to use the endpoints documented on this page.

## Learn more

<CardGroup cols={2}>
  <Card title="API Access" icon="key" href="/features/agent-api-endpoint">
    Expose agents as HTTP APIs, MCP servers, webhooks, or chat widgets
  </Card>

  <Card title="Access Control" icon="shield" href="/security/access-control">
    Workspace roles, team permissions, and agent access levels
  </Card>
</CardGroup>