Skip to main content

Read the Object Model

Compute the workspace object model on request: group documents by Spec or type, filter by tag, and read types, edges, wanted claims, and totals in one call.

GET /v1/object-model computes the model of the workspace on each request. group chooses how documents become types. With spec (the default), a document sits under the Spec whose latest completed, non-preview run captured it, and a document captured by several Specs counts once, under the newest run. With document_type, documents are grouped by their classified document type, and each type lists in sources the Specs that captured documents of it. tag keeps only documents carrying that tag; records and reference tables are unaffected, and claims from other documents count as claims_outside.

The response lists types, edges and wanted, the totals, the tag the model was filtered to, and tags, the workspace's document tags most used first (at most 30), so a client can offer the filter without a second call. generated_at is the time the model was computed. Nothing is cached, so each call reflects the current documents, claims and bindings.

GET/v1/object-model

Query parameters

groupstringHow documents become types: spec (by the Spec whose latest completed non-preview run captured them) or document_type (by classified type). Default: spec
tagstringOnly documents carrying this tag, up to 100 characters.

Response fields

generated_atdate-timeWhen the model was computed.
groupingstringspec or document_type.
types[]arrayThe object types. See Type fields.
edges[]arrayThe links between types. See Edge fields.
wanted[]arrayUnresolved claims grouped by source type, relation and the key type they cite. See Wanted fields.
totalsobjectdocuments, claims, claims_resolved, claims_unresolved, claims_on_record, claims_outside.
tagstring | nullThe document tag the model was filtered to.
tags[]arrayThe workspace's document tags, most used first, at most 30: { tag, documents }.

Type fields (types[])

idstringStable id: master:<domain>, spec:<schema id>, doctype:<name>, or table:<reference data id>.
kindstringmaster (a Master Records domain), spec (documents captured by one Spec), document_type (documents of one classified type), or table (a reference table).
labelstring | nullDomain key, Spec name, classified type name, or table name. Null for unclassified documents.
countintegerGolden records, documents, or table rows of this type.
sourcesstring[]Systems the records come from (master), or the Specs that captured documents of the type (document_type).
refstring | nullThe Spec, reference table, or domain the node points at.

Totals (totals)

documentsintegerDocuments in the model after visibility and tag filtering.
claimsintegerRelation claims counted: resolved claims, plus open claims of documents in the model.
claims_resolvedintegerClaims resolved to a document on file. Includes the claims counted in claims_outside.
claims_unresolvedintegerOpen claims that cite nothing on file; the pool of the wanted list.
claims_on_recordintegerOpen claims whose cited identifier is a golden record's id in a system of record.
claims_outsideintegerResolved claims with an end at a document outside the model: deleted, hidden from the viewer, or excluded by tag.

cURL: Group by document type, one cohort

curl "https://api.talonic.com/v1/object-model?group=document_type&tag=2026-renewal" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Errors

A group outside spec and document_type, or a tag longer than 100 characters, is refused with 400. A key that is not scoped to a concrete workspace cannot be given a model: the master view is not valid for this read and answers 422. A missing or invalid key answers 401, a key without the read scope or an app service key answers 403, and too many requests answer 429.

A model of a large workspace is built from the documents, claims and bindings at request time, so the call can take noticeably longer than a list read. A source whose rows exceed the configured row cap is read only up to the cap, and the edges built from it carry truncated: true; treat their counts as lower bounds.

Frequently asked questions

What does group=spec do when a document was captured by several Specs?+
The document counts once, under the Spec whose latest completed, non-preview run captured it. Preview runs and runs that did not complete do not place a document under a Spec.
Does the tag filter change the reference tables and Master Records?+
No. tag keeps only documents carrying that tag. Records and reference tables are unaffected, and claims that end at a document outside the filter count as claims_outside instead of disappearing.
Why does a type have label null?+
Documents that were never classified form a document_type group with a null label. Grouping by spec labels types with the Spec name instead.
Is the response cached?+
No. The model is recomputed on every request, so generated_at is the time of the call and the counts reflect the documents, claims and bindings at that moment.

Related

Object Model Overview
Reading the Graph
Rate Limits