binder field on a client.
The binder is reached through the me query resolved as a
WorkspaceUser, so every binder operation requires a workspaceToken (see
Authentication). All requests go to:
There is no top-level
binder query. The binder belongs to a client, so you
read it through
me { ... on WorkspaceUser { workspace { clients(filters: { ids: [$clientId] }) { binder { ... } } } } }.
The workspaceToken already identifies the workspace, so you never pass a
workspace ID to read the binder.Query a client’s binder
Use this query when an app, agent, or MCP tool needs the binder overview for a client: filed documents, open missing items, quick counts, and signed URLs for the original uploads and page renders.Arguments
Returns
The binder for the requested client. It contains filed documents, missing
items, message counts, and search.
The logical documents Filed extracted or filed into the binder. Save each
id: it is the documentPath used by
document messages and file-level
leadsheet signoff.Signed page image and markdown URLs for rendering or reading the parent
document page by page.
The status, reason, count, and filtered items for the missing-document check.
Treat an empty item list as an all-clear only when
status is AVAILABLE.MCP usage pattern
- Start with
clients(filters: { ids: [$clientId] })and readbinder. - Use
binder.subdocumentsfor the document list and preserve each subdocumentidfor later annotation, signoff, or leadsheet operations. - Use
parentDocument.urlwhen the user needs the original upload, andparentDocument.subdocPageswhen the user needs page images or page markdown. - Use
missingItemsAssessment.countandmessageCountsfor compact summaries before displaying full lists. - Use
binder.searchwhen the user asks about specific content, issuers, categories, annotations, marks, or values inside the documents.
The Binder type
The top-level binder container for one client.
The files filed in the binder. Pass a
SubDocumentsFilter to narrow to
unreviewed, flagged, or files under one parent document. See
List the files in a binder.The state and filtered result of the missing-document check. Pass a
BinderMissingItemsFilter to narrow by item status. See
List missing items.Deprecated. Use
missingItemsAssessment.items so you can distinguish an
available empty result from a pending or unavailable assessment.Open missing-item and notes counts for badge rendering. See
Read message counts.
Search across bookmarks, annotations, marks, and document contents. See
Search the binder.
The leadsheets tree for a
TAX_PREP or TAX_REVIEW run. Pass the run’s
taskId to read that run’s tree; omit it to read the most recent tree.
Leadsheets are documented separately on
Leadsheets and review; this page
does not re-document them.The SubDocument type
One file in a binder. A subdocument is one logical document extracted from an
uploaded parent (for example one 1099-INT inside a larger uploaded packet).
The subdocument’s unique identifier. This is the value you pass as
documentPath when creating a document message or
signing off on a file.The binder grouping category, when one has been assigned. Nullable: some
subdocuments are uncategorized until a reviewer files them.
The parent document this subdocument was extracted from. See
ParentDocument.The path to the
canonical.json file in the per-client git repo. Populated
when a tax-prep run has picked up this subdocument; null until then.The use-case bucket the subdocument lives in on disk, for example
source_docs, prior_year_docs, or current_year_drafts. null when the
subdocument has not yet been migrated into a bucket.The ParentDocument type
The original uploaded document a subdocument was extracted from. Carries the
file URL and per-page render URLs.
A signed URL for downloading the original file.
SignedPath is
{ filePath: String!, url: String! }.Per-page render URLs for the parent document: one image URL and one markdown
URL per page, both signed and time-limited.
The BinderMissingItemsAssessment type
The result of the missing-document check for the requested item status.
PENDING while the check has not completed, AVAILABLE when the result can be
used, or UNAVAILABLE when the binder lacks enough evidence to determine
missing documents.An explanation for a pending or unavailable assessment. It is
null when the
assessment is available.The missing items matching the requested filter. For an
OPEN filter this is
empty while the assessment is pending or unavailable.The BinderMissingItem type
One item on the missing-document checklist the binder produces: a form the run
expected to find but did not, with a severity, a reason, and a status you can
move between OPEN, IGNORED, and RESOLVED.
The missing-item record ID. Pass this to
ignoreBinderMissingItem or
restoreBinderMissingItem.Why the run flagged this as missing, for example
Expected a 1099-INT from Acme Broker but no matching document was found in the binder.The current status:
OPEN (still needs the document), IGNORED (a reviewer
dismissed it via ignoreBinderMissingItem), or
RESOLVED (the document was later found and filed).The BinderMessageCounts type
Open missing-item and notes counts. Use missingItemsAssessment when you also
need to know whether the missing-document check is available.
The number of stored missing items in the
OPEN status. Do not use this field
alone to infer that the missing-document check completed successfully.The number of open annotation notes on the binder. See
Document messages for the annotation API.
The BinderSearchResults type
The result of Binder.search: four buckets of hits, one per search surface
(bookmarks, annotations, marks, and document contents).
Subdocuments whose file name, issuer, type, or category matched the query. See
BookmarkSearchHit.Binder messages (annotations and notes) whose body or expression matched the
query. See
BinderMessageSearchHit.Binder messages that are marks, whose body or expression matched the query. See
BinderMessageSearchHit.Hits inside document contents, with the matching field names, values, and
bounding boxes. See
BinderContentSearchHit.The BookmarkSearchHit type
The subdocument whose bookmark matched. See
SubDocument.The BinderMessageSearchHit type
A search hit inside a binder message (an annotation or a mark). The underlying
message is a BinderMessage, the binder’s internal message type used by
search. Annotation and sign-off writes use the DocumentMessage type (see
Document messages); BinderMessage is the read
shape the search surface returns.
The binder message that matched. See
BinderMessage.Which message field matched:
BODY (the message body) or EXPRESSION (an
expression inside the message content).The BinderMessage type
The binder’s internal message type, returned by Binder.search. It carries the
message’s anchor (subdocument path, page number, coordinates), content, threads,
and tagged users.
The on-page coordinates of the message anchor, when the message is pinned to a
region.
null for messages that are not pinned to a region.The BinderContentSearchHit type
A search hit inside a subdocument’s contents: the matching field names, values,
and the page-level bounding boxes that pin them.
The subdocument whose contents matched. See
SubDocument.The pages inside the subdocument that carried matches, with the field-level
matches on each page.
The bounding box that pins this match on the page. See
BinderContentBbox
below. null when the match is not pinned to a region.List the files in a binder
Readbinder.subdocuments to list the files filed in a client’s binder. This
is the most common read against the binder: it backs the binder’s Documents
screen.
Arguments
List missing items
Readbinder.missingItemsAssessment to get the state and filtered result of
the missing-document check. Filter by item status to read only open, ignored,
or resolved history.
Arguments
Return only missing items in this status:
OPEN, IGNORED, or RESOLVED.
Omit it to use the default OPEN status.Returns
Whether the missing-document check is
PENDING, AVAILABLE, or UNAVAILABLE.The filtered missing-item rows. Open items are empty for pending or unavailable
assessments.
Read message counts
Readbinder.messageCounts for stored missing-item and open note counts. Use
missingItemsAssessment for a missing-document badge so the UI can distinguish
an available empty result from a pending or unavailable check.
Arguments
Search the binder
Readbinder.search to search across bookmarks (subdocuments by file name,
issuer, type, or category), annotations, marks, and document contents in one
call. The query is debounced in the web app: pass at least two characters.
Arguments
The search query. The web app debounces the input and requires at least two
characters before firing the query.
Ignore a missing item
ignoreBinderMissingItem moves a missing item from OPEN to IGNORED. Use it
when a reviewer dismisses a missing item the run flagged. The mutation takes
the missing-item id and the workspaceId, and returns the updated
BinderMissingItem with its new status.
Input
The ID of the missing item to ignore (the
id from
List missing items).The workspace ID. Unlike the read fields, this mutation takes the workspace ID
explicitly. Use the same workspace ID the
workspaceToken was issued for.Returns: BinderMissingItem!
The ignored BinderMissingItem, with status
set to IGNORED.
Restore a missing item
restoreBinderMissingItem moves a missing item from IGNORED back to OPEN.
Use it when a reviewer wants to re-surface a missing item they previously
ignored.
Input
The ID of the missing item to restore (the
id from
List missing items).Returns: BinderMissingItem!
The restored BinderMissingItem, with status
set to OPEN.