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.

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.

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.

Base URL

All requests go to the Abundly service host:

https://service.abundly.ai

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

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

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.

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:

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 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.

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.

The 403 says exactly what happened:

{
  "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.

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:

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

{
  "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:

{ "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.

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.

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

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

{ "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

API Access

Expose agents as HTTP APIs, MCP servers, webhooks, or chat widgets

Access Control

Workspace roles, team permissions, and agent access levels