Your document workspace, built for agents and workflows

Agent Access API v1 lets external agents push activity events, raise and read signals, read their mailbox, and report agent-hook invocations against a Filepad workspace.

Base path: /agent-api/v1

Authentication

OAuth bearer tokens are required. Unauthenticated requests receive a WWW-Authenticate: Bearer challenge plus the OAuth metadata URL.

Scopes

Scope	Description
`events.write`	Push external agent activity events
`signals:write`	Create signals (findings) on a workspace
`notifications:read`	Read and acknowledge the agent's mailbox

Scopes are checked before a request touches any data. A key only carries the scopes it was explicitly granted.

Endpoints

`GET /agent-api/v1/capabilities`

Returns the authenticated key and granted scopes.

{
  "agent": {
    "keyId": "ik_abc123",
    "integrationId": "int_def456",
    "workspaceId": "ws_abc123"
  },
  "scopes": ["events.write", "signals:write"]
}

`POST /agent-api/v1/workspaces/:workspaceId/events`

Scope: events.write

Writes an external agent activity event.

{
  "idempotencyKey": "activity-123",
  "occurredAt": "2026-04-30T15:00:00.000Z",
  "eventType": "agent.activity.reported",
  "payload": {
    "artifactId": "art_123"
  }
}

`POST /agent-api/v1/workspaces/:workspaceId/signals`

Scope: signals:write

Creates a signal (a finding an agent wants surfaced to the workspace).

`GET /agent-api/v1/workspaces/:workspaceId/signals`

Scope: env:read

Lists signals for a workspace, with optional findingTypeKey, severity, status, limit, and cursor filters.

`GET /agent-api/v1/workspaces/:workspaceId/signals/:signalId`

Scope: env:read

Returns a single signal by ID.

`GET /agent-api/v1/workspaces/:workspaceId/mailbox`

Scope: notifications:read

Lists items in the agent's mailbox, with optional limit, unreadOnly, and cursor parameters.

`POST /agent-api/v1/workspaces/:workspaceId/mailbox/ack`

Scope: notifications:read

Acknowledges one or more mailbox items by ID.

`POST /agent-api/v1/workspaces/:workspaceId/domain/agent-hooks/invocations`

Scope: events.write

Records an agent-hook invocation for observability.

Error handling

Status	Code	Meaning
`401`	`OAUTH_REQUIRED` / `OAUTH_TOKEN_NOT_FOUND` / `OAUTH_INTEGRATION_REVOKED`	Missing, invalid, expired, or revoked token
`403`	`WORKSPACE_MISMATCH`	Key is valid but not authorized for this workspace
`403`	`FORBIDDEN_SCOPE`	Valid key without the required scope
`429`	`RATE_LIMITED`	Too many requests from this connection; retry after the window resets

Next steps

Create an Agent Access key in the Filepad workspace Agents tab.
Agent Access overview — how the connection model works
Security overview — the security principles behind Agent Access