API Reference | Filepad Docs

Filepad exposes three API surfaces:

Surface	Auth	Purpose
Agent Access API v1	HMAC-SHA256 signed requests	External agents read a Filepad workspace, discover skills as prompts, write artifacts, propose edits, and report activity.
FilepadAI run API	Normal Filepad session auth	The native in-app assistant experience: threads, jobs, approvals, interviews, and SSE streams.
Internal API	Internal HMAC	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 routes may still exist for legacy integrations, but new agent builders should use Agent Access.

Agent Access API v1

Base path: /agent-api/v1

MCP-compatible discovery path: /mcp/v1

Agent Access is built around the Filepad workspace model: files external agents can read, skills as reusable prompts, safe artifact creation, and scoped HMAC keys.

Authentication

Every request includes four HMAC headers:

Header	Value
`x-integration-key-id`	Agent Access key id
`x-integration-timestamp`	Unix timestamp in seconds
`x-integration-nonce`	Unique value per request
`x-integration-signature`	Base64 HMAC-SHA256 signature

Canonical string:

METHOD
pathWithQuery
timestampSeconds
nonce
sha256(rawBody)

The timestamp must be fresh, the nonce cannot be replayed, and the signed path must include the exact query string.

Scopes

Scope	Access
`env:read`	Environment summary, file tree, supported file content, indexed workspace search, and prompt/resource discovery
`artifacts:write`	Create note artifacts under `artifacts/`
`files:propose`	Create reviewable edit proposals without direct file mutation
`memory:read`	Reserved for future memory-specific read surfaces
`events.write`	Write external agent activity events

Agent Access v1 does not directly mutate .filepad/, agents/, skills/, memory/, sources/, uploads/, or automations/.

Endpoints at a glance

Method	Path	Scope
`GET`	`/agent-api/v1/capabilities`	any valid key
`GET`	`/agent-api/v1/workspaces/:workspaceId/environment`	`env:read`
`GET`	`/agent-api/v1/workspaces/:workspaceId/prompts`	`env:read`
`GET`	`/agent-api/v1/workspaces/:workspaceId/file-tree`	`env:read`
`GET`	`/agent-api/v1/workspaces/:workspaceId/files/:fileNodeId`	`env:read`
`POST`	`/agent-api/v1/workspaces/:workspaceId/search`	`env:read`
`POST`	`/agent-api/v1/workspaces/:workspaceId/artifacts`	`artifacts:write`
`POST`	`/agent-api/v1/workspaces/:workspaceId/files/:fileNodeId/proposals`	`files:propose`
`POST`	`/agent-api/v1/workspaces/:workspaceId/events`	`events.write`

Skills as prompts

GET /agent-api/v1/workspaces/:workspaceId/prompts exposes real skills/*.md files as discoverable prompts/capabilities. The response includes path, file node id, title, description, and a contentUrl that agents read with the same HMAC auth.

MCP tools

For MCP-capable agents, use the published stdio MCP server:

{
  "mcpServers": {
    "filepad": {
      "command": "npx",
      "args": ["-y", "@filepad/mcp-server@latest"],
      "env": {
        "FILEPAD_BASE_URL": "https://app.filepad.ai/api",
        "FILEPAD_WORKSPACE_ID": "ws_...",
        "FILEPAD_AGENT_KEY_ID": "ik_...",
        "FILEPAD_AGENT_SECRET": "..."
      }
    }
  }
}

The packaged MCP server exposes tools/list, tools/call, prompts, and resources over the same scoped Agent Access key. The backend /mcp/v1 HTTP routes still provide prompt/resource discovery; backend-hosted HTTP/SSE MCP transport is future work.

FilepadAI run API

Base path: /workspaces/:workspaceId/agent

These are the routes the Filepad app uses for the native FilepadAI assistant. They are session-authenticated and separate from Agent Access keys.

Method	Path	Purpose
`POST`	`/workspaces/:workspaceId/agent/threads`	Create a thread
`GET`	`/workspaces/:workspaceId/agent/threads`	List threads
`GET`	`/workspaces/:workspaceId/agent/threads/:threadId/messages`	List thread messages
`GET`	`/workspaces/:workspaceId/agent/threads/:threadId/jobs`	List jobs for a thread
`GET`	`/workspaces/:workspaceId/agent/threads/:threadId/run-state`	Read projected run state
`POST`	`/workspaces/:workspaceId/agent/threads/:threadId/jobs`	Start an agent job
`GET`	`/workspaces/:workspaceId/agent/jobs/:jobId/stream`	Read-only SSE stream
`POST`	`/workspaces/:workspaceId/agent/approvals/:approvalId/action`	Approve or deny a pending approval

Internal API

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