Workspace API

The Workspace API gives external systems access to workspace-level and per-agent data, plus the administrative writes a workspace admin can do from Agent Management — the same information and actions available through the Workspace Explorer and Workspace Manager capabilities, but accessible over HTTP.

Every endpoint on this page is backed by a capability: reads by Workspace Explorer, writes by Workspace Manager. The same data and actions are reachable two ways: over HTTP with a workspace API key, or by giving an agent the 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 changes; the HTTP API is for systems that work 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_...). GET endpoints require the Workspace read API scope; the write endpoints (POST, PUT, PATCH and DELETE) require the Workspace write API scope. The scopes are independent — enable both on a key that should read and write. Include the key as a Bearer token:

Authorization: Bearer wk_your_key_here

Enabling workspace API access

The Workspace API is an enterprise feature that Abundly enables per workspace. If the API Keys tab says the Workspace API is not enabled for your workspace, contact us — until it is, no new workspace keys can be created and existing ones are rejected.

Go to Workspace Settings → API Keys
Create a new key (or edit an existing one)
Check the Workspace read API and/or Workspace write API scope
Save and copy the key

Workspace API keys grant access to all workspace data including chat histories, messages, member information, and agent configurations — and, with the write scope, the power to pause agents, change their models and limits, move them between teams, and create teams and change who is in them. Keep them secure and rotate them regularly.

Workspace endpoints

Read 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, including Abundly support staff (role `support`)
`/workspaceapi/invites`	Pending and expired workspace invitations
`/workspaceapi/teams`	All teams (add `?includeMembers=true` for member lists; filter with `?name=` or `?tag=`)
`/workspaceapi/teams/:teamId`	Single team details with full member list
`/workspaceapi/secrets`	Secret names and metadata (values are never exposed)
`/workspaceapi/http-apis`	Shared Outgoing API 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/agent-usage`	Per-agent key metrics, triggers & chats and credits for a period (`?days=`, or `?startDate=&endDate=`)
`/workspaceapi/tags`	The workspace tag vocabulary with usage counts per entity type
`/workspaceapi/promotion-requests`	Agent promotion requests, their review steps and decisions (`?agentId=`, `?status=`, `?limit=`)
`/workspaceapi/action-log`	The User action log: who changed what, and when (`?agentId=`, `?eventType=`, `?actorUserId=`, `?from=`, `?to=`, `?page=`, `?pageSize=`)

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, valueStatement (the owner’s one-or-two-sentence statement of why the agent exists), criticality (critical, high, medium or low) and keyMetrics appear when they are set. valueEntries may also appear; it is deprecated (data from the retired value capture feature) and will be removed in a later release. 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 — restricted and personal ones included — with its access, capabilities, hasInstructions (whether it has instructions—not the text itself), 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 default level: `admin`, `edit`, `use`, or `none`. It applies to members of the agent’s team, or to all workspace members when the agent has no team (`groupId` unset). People outside the team get at most `use`, and only through `crossTeamSharing`. `none` means the agent is restricted (or personal) — 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 restricted and personal 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, with the single exception of its promotion review history, not be restricted or personal — see Restricted and personal 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=`)
`/workspaceapi/agents/:agentId/key-metrics`	The agent’s key metrics for a period (filters: `?days=` or `?startDate=&endDate=`, `?recentLimit=`)
`/workspaceapi/agents/:agentId/promotion-requests`	The agent’s promotion review history (filters: `?status=`, `?limit=`)
`/workspaceapi/agents/:agentId/instruction-versions`	The agent’s instruction history (filters: `?since=`, `?version=`, `?includeContent=`)

Promotion reviews

In workspaces where promotion to production goes through review (lifecycle phases), /workspaceapi/promotion-requests returns every request in the workspace — restricted and personal agents included — with each review step, the decisions taken so far, and who the outstanding steps are waiting for. Pass ?agentId= or use the per-agent endpoint for one agent’s history.

The API reads the review; it does not take part in it. Approving and rejecting stay in the portal, where the decision is recorded against the person who made it — a workspace API key belongs to the workspace rather than to any one person, so it cannot stand in for a reviewer.

Change history

Two endpoints tell you what changed on an agent and when — for example, to flag a production agent that has drifted since its promotion was approved and send it back for review.

/action-log returns the same rows as Usage → User action log in the portal: every change to an agent, team or workspace setting, with who made it and when, newest first. Narrow it with ?agentId= and ?from=, or by ?eventType= (comma-separated, for example agent.instructions_changed,agent.capabilities_changed). Restricted, personal and deleted agents are included, as they are in the portal.
/agents/:agentId/instruction-versions returns the agent’s instruction history, newest first: who made each change, when, and the length of each version’s text. The first entry is the live instructions. With ?since=, you get the version in effect at that time plus every later one — enough to diff the instructions as approved against the current ones. Add ?includeContent=true for the text, or ?version= for a single version. Only the latest 100 superseded versions are kept.

curl -s "https://service.abundly.ai/workspaceapi/agents/AGENT_ID/instruction-versions?since=2026-09-01&includeContent=true" \
  -H "Authorization: Bearer wk_your_key_here" | jq '.versions[] | {version, changedAt, contentLength}'

The action log never contains instruction or prompt text. Changed values appear as «redacted:…» tokens that show a value changed but not what it is — use /instruction-versions for the text itself. Changes made by Abundly staff show the actor as “Abundly staff”.

Write endpoints

Write endpoints mirror the Workspace Manager capability — the administrative changes a workspace admin can make from Agent Management without opening an agent, plus creating teams and managing their members. They require the Workspace write API scope. The endpoints below are batch POST requests:

Endpoint	Description
`/workspaceapi/agents/enabled`	Enable or pause agents
`/workspaceapi/agents/model`	Set the agents’ default model
`/workspaceapi/agents/daily-credit-limit`	Set (or clear) the daily credit limit
`/workspaceapi/agents/criticality`	Set (or clear) the criticality rating
`/workspaceapi/agents/credit-details`	Show or hide per-message credit details in chats
`/workspaceapi/agents/tags`	Add, remove, or replace tags on agents
`/workspaceapi/agents/team-moves`	Move agents to another team (supports `dryRun`)
`/workspaceapi/agents/phase`	Promote agents to production or demote them to sandbox (lifecycle phases)
`/workspaceapi/teams/tags`	Add, remove, or replace tags on teams
`/workspaceapi/members/tags`	Add, remove, or replace tags on members

Batch semantics

Each of the endpoints above is a batch operation: the JSON body carries an ids array plus the values to apply, and each id gets its own result. A bad id never fails the rest of the batch — the request returns 200 as long as it was well-formed, so always check the per-id results:

curl -s -X POST https://service.abundly.ai/workspaceapi/agents/tags \
  -H "Authorization: Bearer wk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["AGENT_ID_1", "AGENT_ID_2"], "tags": ["pilot"], "operation": "add"}'

{
   "results": [
      { "id": "AGENT_ID_1", "success": true, "tags": ["pilot", "sales"] },
      { "id": "AGENT_ID_2", "success": false, "error": "Agent 'AGENT_ID_2' not found in this workspace" }
   ],
   "summary": { "total": 2, "succeeded": 1, "failed": 1, "unchanged": 0 }
}

A write that would not change anything is reported with unchanged: true and skipped in the audit log, so re-running a bulk update is safe and quiet.

Tag rules

The three tag endpoints apply the same rules as the portal, so tags written through the API match what the web UI produces. Tags are trimmed, lowercased and deduplicated on the way in — sending "Sales" stores sales. A tag can be at most 50 characters and cannot contain line breaks; a body that breaks either rule is rejected with 400. Each agent, team or member can carry at most 50 tags. An entity already above that keeps its tags and can still have tags removed; only ids that would grow past the limit come back with success: false.

Previewing team moves

Moving an agent changes who can reach it and can flip team-scoped capabilities on or off. Send "dryRun": true to /workspaceapi/agents/team-moves first: nothing moves, and each result carries an impact object naming the members who gain or lose access and the capabilities that flip. /workspaceapi/teams/tags and /workspaceapi/agents/team-moves return 400 when team settings are not enabled for the workspace.

Teams and team members

These endpoints act on one team or one membership and answer with standard status codes rather than batch results:

Request	Body	Success
`POST /workspaceapi/teams`	`{ name, tags? }`	`201` with `{ id, name, tags }`
`PATCH /workspaceapi/teams/:teamId`	`{ name }`	`200` with `{ id, name }`
`PUT /workspaceapi/teams/:teamId/members/:userId`	`{ role }`	`201` when added, `200` when already a member
`DELETE /workspaceapi/teams/:teamId/members/:userId`	—	`204`

Roles are the team roles the read endpoints return: admin, member or guest.
Membership writes are idempotent. Repeating a PUT leaves one membership and answers 200. A DELETE for someone who isn’t in the team answers 404, which you can treat as already removed.
Members must already belong to the workspace. Adding someone who doesn’t returns 404; invite them to the workspace first.
Creating a team is not idempotent. Team names don’t have to be unique, so a create retried after a timeout can leave a duplicate. Create teams with a tag you own, and look the team up with /workspaceapi/teams?tag= before retrying.
Teams can’t be deleted through the API. Delete them in the portal.

All four return 400 when team settings are not enabled for the workspace.

Audit trail

Every successful write is recorded in the workspace’s User action log (on the Usage page), attributed to the user who created the API key, with source Workspace API. Team membership changes are the exception: like the same changes made in the portal, they are logged but don’t appear in the User action log.

Unlike the read endpoints, writes can target restricted and personal agents — matching the portal, where a workspace admin can pause or retag an agent they cannot open.

Restricted and personal 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 restricted and personal agent as off-limits for content reads.

Restricted and personal agents appear in /agents, in overview.reducedAgents, in overview.lastUsageByAgent, in /agent-usage and in /credits agentUsage — but every /agents/:agentId route and subresource returns 403 for them, apart from /agents/:agentId/promotion-requests. Workspace-wide endpoints still include them: their changes appear in /action-log and their review requests in /promotion-requests. 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, capabilities, integrations and usage timestamps for every agent — and to treat the per-agent endpoints as a drill-down for individual agents that aren’t restricted or personal rather than something to iterate. Check isPrivate before requesting detail for an agent.

Pagination

Only three 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
`/action-log`	Same as `/messages`
`/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, restricted and personal 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. /workspaceapi/agents/:agentId/key-metrics returns the agent’s key metrics for a period: per metric the count, for measured metrics the aggregate (the average or total, as measurement.aggregation says), the same two figures for the period of equal length before (previousCount, previousAggregate), and up to recentLimit recent records with their refs (default 0, maximum 500). The definitions themselves are on the agent object as keyMetrics. See Choosing a period.

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= to find the runs, then read each one with ?entryId= to get its steps. List pages don’t include steps.

Choosing a period

The two period endpoints, /agent-usage and /agents/:agentId/key-metrics, take either a lookback or a fixed period:

Parameter	Behavior
`?days=`	The last N days ending now (or at `endDate`). Default `30`, maximum `365`
`?startDate=` `?endDate=`	ISO timestamps for a fixed period, for example a calendar month. `endDate` defaults to now; at most 365 days apart

Daily series use UTC day boundaries.

Agent usage

/workspaceapi/agent-usage returns one row per agent for a period, restricted and personal agents included and marked with isPrivate: the agent’s key metrics (count, and for measured metrics the aggregate), its triggers & chats with a daily series, and the credits it used. Every figure comes with the same figure for the period of equal length immediately before (previousCount, previousUsed, previousAggregate), as raw values rather than percentages, so you can apply your own rule for what counts as a trend. The portal shows a percentage only when the previous value is at least 10, and marks an agent created inside the period as new instead (createdAt is on the row). Rows also carry the team, effective lifecycle phase, criticality, value statement, tags, owners and whether the agent is enabled (a disabled agent’s figures for the period still count), which is what the portal’s Usage → Agent usage table filters on and shows in the agent hover card. The rows are what a workspace admin sees on that table, and the portal’s JSON export of it carries the same rows, filtered as shown on screen. A restricted or personal agent’s row is figures only: its /agents/:agentId endpoints still return 403.

curl -s "https://service.abundly.ai/workspaceapi/agent-usage?days=90" \
  -H "Authorization: Bearer wk_your_key_here" \
  | jq '.rows[] | {name, credits: .credits.used, metrics: [.keyMetrics[] | "\(.count) \(.name)"]}'

Key metrics are defined per agent, so compare an agent with itself over time rather than ranking agents against each other.

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, and for write batches with per-id failures — check `results[].success`
`201`	A team was created, or a user was added to a team
`204`	A user was removed from a team
`400`	Invalid filter value (a `limit` above the endpoint’s maximum, an unparseable date), an invalid write body (missing fields, a model the workspace cannot select, invalid tags), or a team write when team settings are disabled
`401`	Missing key, malformed key, or a key that isn’t a `wk_` workspace key
`403`	Valid key without the scope the endpoint requires (Workspace read API for GETs, Workspace write API for writes), or a restricted or personal agent on a read
`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/`, a user who isn’t in the workspace (adding to a team) or in the team (removing), 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 three scopes that can be enabled independently; every key needs at least one:

Scope	What it grants
Agent API endpoints	Access to every agent-exposed API (HTTP API, Document API, MCP, Widget) on agents with “Allow workspace keys on all scopes” enabled
Workspace read API	Read-only access to workspace and agent data via the `GET /workspaceapi/` endpoints
Workspace write API	Administrative writes via the `POST`, `PUT`, `PATCH` and `DELETE` `/workspaceapi/` endpoints

Existing keys default to Agent API endpoints only. Enable the read and/or write scope explicitly to use the endpoints documented on this page.

Core Features

Administration

Advanced

Base URL

Authentication

Enabling workspace API access

Workspace endpoints

Reading the agent list

Who owns an agent

Per-agent endpoints

Promotion reviews

Change history

Write endpoints

Batch semantics

Tag rules

Previewing team moves

Teams and team members

Audit trail

Restricted and personal agents

Credits are a live snapshot

Documents and response size

Tool usage

Tools are not capabilities

Finding the tool names

Reading the response

Unknown tool names

Choosing a period

Agent usage

Example

Status codes

Rate limits

Data redaction

API key scopes

Learn more

API Access

Access Control

​Base URL

​Authentication

​Enabling workspace API access

​Workspace endpoints

​Reading the agent list

​Who owns an agent

​Per-agent endpoints

​Promotion reviews

​Change history

​Write endpoints

​Batch semantics

​Tag rules

​Previewing team moves

​Teams and team members

​Audit trail

​Restricted and personal agents

​Pagination

​Credits are a live snapshot

​Documents and response size

​Tool usage

​Tools are not capabilities

​Finding the tool names

​Reading the response

​Unknown tool names

​Choosing a period

​Agent usage

​Example

​Status codes

​Rate limits

​Data redaction

​API key scopes

​Learn more

API Access

Access Control

Base URL

Authentication

Enabling workspace API access

Workspace endpoints

Reading the agent list

Who owns an agent

Per-agent endpoints

Promotion reviews

Change history

Write endpoints

Batch semantics

Tag rules

Previewing team moves

Teams and team members

Audit trail

Restricted and personal agents

Pagination

Credits are a live snapshot

Documents and response size

Tool usage

Tools are not capabilities

Finding the tool names

Reading the response

Unknown tool names

Choosing a period

Agent usage

Example

Status codes

Rate limits

Data redaction

API key scopes

Learn more