Filepad exposes three API surfaces:
| Surface | Auth | Purpose |
|---|---|---|
| Agent Access API v1 | OAuth 2.1 bearer tokens | External agents push activity, raise signals, and read their mailbox against a Filepad workspace. |
| FilepadAI run API | Normal Filepad session auth | The native in-app assistant experience: threads, blocks, attachments, approvals, and SSE streams. |
| Internal API | Internal auth | Backend-only admin flows such as key lifecycle and Control Room operations. |
The product API for external agents is Agent Access API v1 at /agent-api/v1. Older /integrations/v1 http/routes may still exist for legacy integrations, but new agent builders should use Agent Access.
Agent Access API v1
Base path: /agent-api/v1
Agent Access is built around scoped OAuth access to a workspace's activity: events, signals, and mailbox.
Authentication
OAuth bearer tokens are required. The gateway challenges unauthenticated
requests with WWW-Authenticate: Bearer and the OAuth metadata URL.
Scopes
| Scope | Access |
|---|---|
events.write | Write external agent activity events and agent-hook invocations |
signals:write | Create signals (findings) on a workspace |
notifications:read | Read and acknowledge the agent's mailbox |
Endpoints at a glance
| Method | Path | Scope |
|---|---|---|
GET | /agent-api/v1/capabilities | any valid key |
POST | /agent-api/v1/workspaces/:workspaceId/events | events.write |
POST | /agent-api/v1/workspaces/:workspaceId/signals | signals:write |
GET | /agent-api/v1/workspaces/:workspaceId/signals | env:read |
GET | /agent-api/v1/workspaces/:workspaceId/signals/:signalId | env:read |
GET | /agent-api/v1/workspaces/:workspaceId/mailbox | notifications:read |
POST | /agent-api/v1/workspaces/:workspaceId/mailbox/ack | notifications:read |
POST | /agent-api/v1/workspaces/:workspaceId/domain/agent-hooks/invocations | events.write |
Every request is also subject to per-integration rate limiting; a connection that exceeds its window gets a 429 with a retry time.
FilepadAI run API
Base path: /agent
These are the http/routes the Filepad app uses for the native FilepadAI assistant. They are session-authenticated and separate from Agent Access keys.
| Method | Path | Purpose |
|---|---|---|
POST | /agent/threads | Create a thread |
GET | /agent/threads | List threads |
GET | /agent/threads/:threadId/blocks | List thread blocks |
GET | /agent/threads/:threadId/blocks/stream | Read-only SSE stream of thread blocks |
DELETE | /agent/threads/:threadId | Delete a thread |
POST | /agent/threads/:threadId/attachments | Attach a file to a thread |
POST | /agent/threads/:threadId/paste-attachments | Attach pasted content to a thread |
GET | /workflow-runtime/approvals/:approvalRequestId | Read a pending approval request |
Internal API
Internal http/routes are not the public Agent Access surface. They can create, rotate, patch, and revoke underlying integration records, but product UI should call them as Agent Access or Agents, not as integrations.