@filepad/agent-access-sdk

@filepad/agent-access-sdk

Official SDK for connecting external AI agents to Filepad workspaces via Agent Access.

What is Agent Access?

Agent Access is Filepad's scoped API for external agents. It lets an outside agent:

• Read workspace context (folders, files, skills, search)
• Read visible workspace signals
• Read and propose updates to the agent's own home profile
• Create safe artifacts under artifacts/
• Propose reviewable edits to allowed files
• Report activity events
• Receive addressed mailbox notifications from Filepad

Agent Access does not let external agents directly mutate active workspace files, approve their own proposals, or execute automations.

Install

npm install @filepad/agent-access-sdk

Requires Node.js 18+.

Quick Start

import { FilepadAgentClient } from '@filepad/agent-access-sdk';

const client = new FilepadAgentClient({
  baseUrl: 'https://app.filepad.ai/api',
  workspaceId: 'ws_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  keyId: 'ik_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  secret: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
});

// Verify credentials
const { scopes } = await client.verifyCredentials();
console.log('Granted scopes:', scopes);

// Read environment
const env = await client.getEnvironment();
console.log('Folders:', env.folders.map(f => f.name));

// Search workspace
const search = await client.search('quarterly report', { type: 'keyword', limit: 5 });
console.log('Results:', search.results.length);

// Create artifact
const { artifact } = await client.createArtifact({
  title: 'Agent Report',
  text: '# Summary\n\nGenerated by external agent.',
});
console.log('Artifact:', artifact.id);

// Emit event
const { eventId } = await client.createEvent({
  eventType: 'agent.task.completed',
  payload: { artifactId: artifact.id },
});
console.log('Event:', eventId);

// Query visible signals
const signals = await client.getSignals({ status: 'suggested', limit: 10 });
console.log('Signals:', signals.signals.length);
if (signals.signals[0]) {
  const signal = await client.getSignal(signals.signals[0].id);
  console.log('Signal:', signal.findingTypeKey, signal.status);
}

// Read Filepad callbacks addressed to this integration
const mailbox = await client.getMailbox({ unreadOnly: true, limit: 20 });
console.log('Unread mailbox items:', mailbox.items.length);
if (mailbox.items.length > 0) {
  await client.ackMailbox(mailbox.items.map(item => item.id));
}

// Read this key's agent home profile
const profile = await client.getAgentProfile();
console.log('Agent profile key:', profile.keyId);

Authentication

Every request is signed with HMAC-SHA256 using your Agent Access key.

Create a key in Filepad:

• Open a workspace
• Go to Settings → Agent Access
• Click Create Key
• Copy the Key ID and Secret (shown once)

The SDK handles signing automatically. You only need to provide keyId and secret to the client.

API Reference

FilepadAgentClient

verifyCredentials()

Returns the integration key id, integration id, workspace id, and granted scopes.

getEnvironment()

Returns workspace folders and their status.

getFileTree()

Returns all visible files and folders.

getFile(fileNodeId)

Reads a file by its node id.

getPrompts() / getMcpPrompts() / getMcpResources()

Discover skills and resources.

search(query, options?)

Search indexed workspace context.

createArtifact(params)

Create a note artifact under artifacts/.

proposeEdit(params)

Propose a reviewable edit to an allowed file.

createEvent(params)

Emit an activity event.

createSignal(params)

Create a signal (requires signals:write scope).

getSignals(filters?)

Query visible workspace signals by type, severity, status, limit, or cursor. Requires env:read.

getSignal(signalId)

Read one visible workspace signal by id. Requires env:read.

getMailbox(options?)

Read Filepad mailbox notifications addressed to this integration. Requires notifications:read.

ackMailbox(ids)

Acknowledge processed mailbox notification ids. Requires notifications:read.

getAgentProfile(options?)

Read this integration's agent home profile files under agents/integrations/{keyId}/. Requires env:read.

updateAgentProfile(params)

Propose an append or replacement update to one profile file. Requires env:read and files:propose; the change waits for human review.

Error Handling

The SDK throws typed errors:

• AuthenticationError — invalid signature or expired key
• ForbiddenScopeError — missing required scope
• NotFoundError — file or resource not found
• RateLimitError — too many requests
• ProposalPathError — proposal target is not allowed
• StaleVersionError — base version changed during proposal

All errors extend FilepadAgentError with code, message, and status properties.

import { FilepadAgentError, AuthenticationError } from '@filepad/agent-access-sdk';

try {
  await client.getFile('fn_...');
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Check your key id and secret');
  } else if (err instanceof FilepadAgentError) {
    console.error(err.code, err.message);
  }
}

Scope Reference

Scope	What it allows
env:read	Read folders, file tree, file content, search, skill prompts, MCP resources, and visible signals
artifacts:write	Create note artifacts under artifacts/
files:propose	Create reviewable edit proposals for allowed files
memory:read	Read memory entries
events.write	Write agent activity events
signals:write	Create signals for automation triggers
notifications:read	Read and acknowledge Filepad mailbox notifications addressed to this integration

License

MIT