Workspaces

Accept an invitation

POST /v1/invitations/accept · post-v1-invitations-accept

Join the caller's account to the workspace an inv_ token names.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/invitations/accept' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Open an organization workspace

POST /v1/workspaces · post-v1-workspaces

Create an organization workspace on the sign-up tenant, owned by the caller. Personal workspaces come only from sign-up. Requires accounts.signup_tenant.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

201 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read a workspace

GET /v1/workspaces/{workspace} · get-v1-workspaces--workspace-

Members see the roster and seats; admins and the owner also see live invitations.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Rename a workspace or set its seats

PATCH /v1/workspaces/{workspace} · patch-v1-workspaces--workspace-

Owner only. The id never changes; seats may not shrink below the active membership.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X PATCH 'https://api.openagents.com/v1/workspaces/{workspace}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

The workspace's access history

GET /v1/workspaces/{workspace}/access · get-v1-workspaces--workspace--access

Members read their own events; admins and the owner read the workspace's.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/access' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Issue an invitation

POST /v1/workspaces/{workspace}/invitations · post-v1-workspaces--workspace--invitations

Admin or owner. Grants admin or member — ownership moves only through transfer. The inv_ token is shown once; delivery is out of band.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

201 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/invitations' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Withdraw an invitation

DELETE /v1/workspaces/{workspace}/invitations/{invitation} · delete-v1-workspaces--workspace--invitations--invitation-

Revoke a pending invitation — the record stays; the state is the answer.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/workspaces/{workspace}/invitations/{invitation}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List the workspace tenant's keys

GET /v1/workspaces/{workspace}/keys · get-v1-workspaces--workspace--keys

A member reads their own keys; an admin or the owner reads all with account attribution. No secret field exists.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/keys' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Issue a key

POST /v1/workspaces/{workspace}/keys · post-v1-workspaces--workspace--keys

A key on the workspace's tenant, bound to the caller's account — named and optionally scoped to doors and actions. The secret is shown once.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

201 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/keys' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Revoke a key

DELETE /v1/workspaces/{workspace}/keys/{key} · delete-v1-workspaces--workspace--keys--key-

The record stays; the state is the answer.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/workspaces/{workspace}/keys/{key}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Copy a key

POST /v1/workspaces/{workspace}/keys/{key}/copy · post-v1-workspaces--workspace--keys--key--copy

Copy a key under the same name, scopes, and reach, bound to the caller's account. The secret is shown once.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

201 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/keys/{key}/copy' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Pause a key

POST /v1/workspaces/{workspace}/keys/{key}/pause · post-v1-workspaces--workspace--keys--key--pause

Hold a key without ending it — it refuses until resumed; attribution stands.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/keys/{key}/pause' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Resume a key

POST /v1/workspaces/{workspace}/keys/{key}/resume · post-v1-workspaces--workspace--keys--key--resume

Release a paused key.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/keys/{key}/resume' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Rotate a key

POST /v1/workspaces/{workspace}/keys/{key}/rotate · post-v1-workspaces--workspace--keys--key--rotate

Fresh id and secret for the same reach, rebound to the key owner's account. Quota, history, and membership never move.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/keys/{key}/rotate' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Change a member's role

PATCH /v1/workspaces/{workspace}/members/{account} · patch-v1-workspaces--workspace--members--account-

The owner moves a member between admin and member; ownership never passes through this route.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X PATCH 'https://api.openagents.com/v1/workspaces/{workspace}/members/{account}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Remove a member

DELETE /v1/workspaces/{workspace}/members/{account} · delete-v1-workspaces--workspace--members--account-

Revoke the membership; the member's sessions end in the same committed write and their keys refuse the workspace on next authentication.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X DELETE 'https://api.openagents.com/v1/workspaces/{workspace}/members/{account}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Transfer ownership

POST /v1/workspaces/{workspace}/transfer · post-v1-workspaces--workspace--transfer

Hand ownership to another active member; the caller becomes an admin in the same committed revision.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Response

200 — The operation completed.

Type: object

Errors

Example

curl -X POST 'https://api.openagents.com/v1/workspaces/{workspace}/transfer' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read the workspace's usage position

GET /v1/workspaces/{workspace}/usage · get-v1-workspaces--workspace--usage

Exact totals over the workspace's own execution receipts joined to the money and quota ledgers — calls by outcome, quota-derived units, cost fields, outstanding holds, breakdowns by model, key, lane, and transport, and the billing entitlement. Member-scoped. The disclosure block states scale, timezone, lag, retention, and skipped counts.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Response

200 — The usage summary with the disclosure block.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/usage' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

List the workspace's call activity

GET /v1/workspaces/{workspace}/usage/activity · get-v1-workspaces--workspace--usage-activity

The filtered receipt list, newest first, with keyset cursor pagination over (resolved_at, digest). Each item carries the receipt's identity fields plus joined cost and quota units.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Response

200 — A page of activity items and the next cursor.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/usage/activity' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Export the workspace's receipts

GET /v1/workspaces/{workspace}/usage/export · get-v1-workspaces--workspace--usage-export

The filtered receipts as NDJSON — the sealed lines verbatim, each re-verifying offline by its own digest. Bounded at 10000 lines.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Response

200 — One sealed ExecutionReceipt per line.

Type: string

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/usage/export' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read one of the workspace's receipts

GET /v1/workspaces/{workspace}/usage/receipts/{digest} · get-v1-workspaces--workspace--usage-receipts--digest-

The sealed execution receipt plus its joined hold and quota reservation. Workspace-scoped — a digest another workspace owns is unknown_receipt.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Response

200 — The receipt, its cost, and its quota units.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/usage/receipts/{digest}' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"

Read the workspace's usage by UTC day

GET /v1/workspaces/{workspace}/usage/timeseries · get-v1-workspaces--workspace--usage-timeseries

The same receipts folded into day buckets — calls, outcomes, quota units, and retail spend per day; exact sums of the rows the activity read returns.

Sign-in: a bearer credential in the Authorization header.

bearer: An issued key: oak_<id>.<secret>. Omitted entirely for anonymous access to shared doors, which a require_workspace_membership deployment refuses outright.

Parameters

Response

200 — Day buckets and the undated count.

Type: object

Errors

Example

curl 'https://api.openagents.com/v1/workspaces/{workspace}/usage/timeseries' \
  -H "Authorization: Bearer $OPENAGENTS_TOKEN"