Introduction - Filed Engineering

The Filed API is a single GraphQL endpoint. You send queries and mutations to one URL and request exactly the fields you need.

https://router.apps.filed.com/graphql

Every request except health and the token exchange needs a Bearer token. Most operations act on a workspace and need a workspaceToken; see Authentication to create an API key and exchange it for a token.

Clients and tasks are not top-level queries. They belong to a workspace and are reached through me, resolved as a WorkspaceUser: me { ... on WorkspaceUser { workspace { clients { ... } tasks { ... } } } }. The workspaceToken identifies the workspace, so you never pass a workspace ID.

Operations

Start with the operation that matches the product object you are trying to work with. Most product workflows are not top-level GraphQL queries: read me, resolve the caller as a WorkspaceUser, then traverse through workspace, clients, tasks, and each client’s binder.

Need	Start here	Then use
Check auth and workspace scope	`me`	Read `workspace.id`, `workspace.name`, clients, and tasks.
Create or find a client	`Clients`	Use client IDs for binder, task, and document operations.
Upload or attach source files	`Clients` and Uploading documents	Attach uploaded file IDs to a client, then read the binder.
Read organized client documents	`Binder`	Query `binder.subdocuments`, `missingItemsAssessment`, `messageCounts`, and `search`.
Search across binder content	`Binder.search`	Search bookmarks, notes, marks, and extracted document content.
Add notes, flags, comments, or sign-offs	`Document messages`	Use subdocument IDs from the binder as `documentPath`.
Read tax prep output and reviewer sign-offs	`Leadsheets`	Pass a tax prep or tax review `taskId` when you need a specific run.
Start data entry or tax prep work	`Task triggers`	Trigger the run, then poll `Tasks`.
Monitor background work	`Tasks`	Poll status, read errors, and link task results back to clients.
Run provider-specific integration actions	`Integration capabilities`	List provider capabilities, run one, then poll the capability run.
Generate workpapers	`Workpapers`	Use client and task context to request or read workpaper bundles.
Run planning workflows	`Planning`	Use when the workflow is planning-specific rather than tax-prep-specific.
Automate repeatable work	`Skills`	Use skill APIs for stored automation behavior.

MCP operation routing

When an MCP client reads these docs, prefer this routing pattern:

Call the docs tool first, then start at this API introduction.
Use me to verify the token resolves to a WorkspaceUser.
Use Clients to find or create the client.
Use Binder as the source of truth for client documents, missing items, document search, and document IDs.
Use Document messages for all note, flag, comment, reply, hide, unhide, and sign-off writes.
Use Task triggers to start data entry or tax prep, then Tasks to poll the run.
Use Leadsheets to read tax prep review output and inspect sign-off state after a run.
Use Integration capabilities only after the user has named a provider action or integration workflow.

For MCP use, prefer a small number of focused GraphQL operations over one very large query. First discover workspace, client, binder, and task IDs. Then fetch the specific object needed for the user’s request.

health

Unauthenticated liveness check for the API and its services.

me

Identify the caller: a User (userToken) or WorkspaceUser (workspaceToken).

Clients

Create clients, list and fetch them, and add documents to a binder.

Tasks

List background tasks and check a single task’s status.

Conventions

Scalars, IDs, pagination, sorting, and filtering.

Guides

Authentication

Create an API key and exchange it for an access token.

Making requests

Request shape, variables, and the error model.

Quickstart

Zero to a processed client in five steps.

Uploading documents

Stage files through the resumable upload endpoint, then attach them.

A first request

Confirm your token works with me:

cURL

curl -X POST https://router.apps.filed.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_WORKSPACE_TOKEN" \
  -d '{ "query": "query { me { __typename ... on WorkspaceUser { workspace { id name } } } }" }'

​Operations

​MCP operation routing

health

me

Clients

Tasks

Conventions

​Guides

Authentication

Making requests

Quickstart

Uploading documents

​A first request

Operations

MCP operation routing

Guides

A first request