Agent Access API v1

Agent Access API v1 lets external agents read the files they are allowed to see, discover skills/*.md as reusable prompts, write safe artifacts, propose reviewable edits, and report activity.

Base path: /agent-api/v1

MCP-compatible discovery path: /mcp/v1

Legacy /integrations/v1 routes may still exist for older system integrations. New agent builders should use /agent-api/v1.

Authentication

Every request must include four HMAC signature headers:

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

Canonical string:

METHOD
pathWithQuery
timestampSeconds
nonce
sha256(rawBody)

Sign with base64(hmac_sha256(secret, canonicalString)).

Important details:

pathWithQuery is the exact path and query string being called.
GET requests hash the empty body.
Timestamps must be fresh.
Nonces cannot be replayed for the same key.
Secrets are shown only once when created or rotated.

Scopes

Scope	Description
`env:read`	Read environment folders, file tree, supported file content, indexed workspace search, and prompt/resource discovery
`artifacts:write`	Create note artifacts under the real `artifacts/` folder
`files:propose`	Create reviewable file edit proposals
`memory:read`	Reserved for future memory-specific read surfaces
`events.write`	Push external agent activity events

Agent Access v1 does not directly mutate .filepad/, agents/, skills/, memory/, sources/, uploads/, or automations/. File proposals are reviewable and limited to supported files under artifacts/, agents/, skills/, and memory/.

Files and folders hidden from agents are omitted from Agent Access file-tree, prompt discovery, MCP resources, search results, file reads, and proposals.

Endpoints

`GET /agent-api/v1/capabilities`

Returns the authenticated key and granted scopes.

{
  "agent": {
    "keyId": "ik_abc123",
    "integrationId": "int_def456",
    "workspaceId": "ws_abc123"
  },
  "scopes": ["env:read", "artifacts:write"]
}

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

Scope: env:read

Returns canonical environment folders such as .filepad, agents, skills, memory, sources, uploads, artifacts, and automations.

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

Scope: env:read

Returns real Markdown files under skills/ as prompt/capability records.

{
  "prompts": [
    {
      "path": "skills/summarize.md",
      "fileNodeId": "fn_skill",
      "name": "summarize",
      "title": "Skill - Summarize",
      "description": "Use this skill when asked to summarize a source document.",
      "contentUrl": "/agent-api/v1/workspaces/ws_abc123/files/fn_skill"
    }
  ]
}

{
  "title": "Agent note",
  "text": "# Created by an external agent"
}

`POST /agent-api/v1/workspaces/:workspaceId/files/:fileNodeId/proposals`

Scope: files:propose

Creates a reviewable proposal against a supported editable artifact-backed file. The proposal is not applied directly.

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

Scope: events.write

Writes an external agent event.

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

MCP tools

Agent Access V1 includes two MCP surfaces:

@filepad/mcp-server is the recommended stdio MCP server for OpenClaw, Claude Desktop, Cursor, Windsurf, and other MCP clients. It exposes Filepad tools through tools/list and tools/call while enforcing the same Agent Access scopes.
/mcp/v1/workspaces/:workspaceId/prompts and /mcp/v1/workspaces/:workspaceId/resources are backend HTTP discovery routes for prompt/resource records.

Example MCP config:

{
  "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": "..."
      }
    }
  }
}

Backend-hosted HTTP/SSE MCP tool execution is future work.

Error handling

Status	Code	Meaning
`401`	`UNAUTHENTICATED`	Missing or invalid HMAC auth, stale timestamp, replayed nonce, unknown key, or revoked key
`403`	`FORBIDDEN_SCOPE`	Valid key without the required scope
`404`	`NOT_FOUND`	Resource not found or workspace mismatch
`409`	`ENVIRONMENT_NOT_INITIALIZED`	Required environment folder is missing

Workspace mismatches are intentionally non-enumerating.

Next steps

Create an Agent Access key in the Filepad workspace Agents tab.
Use the snippets in docs/agent-api/snippets/.
Read the repository docs at docs/agent-api/README.md for full endpoint examples.