Query published definitions

A governed definition is a business view the Twin has built and published, such as invoice totals by region and month. An external agent can use one directly, without asking the Twin's own agent:

1. find a definition and read its card;
2. run a typed query against it, with no model;
3. read the values with the definition's version, freshness and certificates;
4. resolve the evidence behind any Twin answer, including your own queries.

Reading and resolving evidence need twin.read, a query needs twin.query, and approving public use needs twin.write as an organisation admin.

Who sees which definitions

• Members see the definitions an organisation admin has approved for public use. They run aggregate queries only, over the fields the approval classifies as non-personal dimensions or aggregate metrics.
• Organisation admins see and query every serving definition, records included, each marked public, public_access_pending_review or not_public.

An approval applies to the version it was reviewed against. When a new version of the definition starts serving, it shows as public_access_pending_review and members no longer see it until an admin approves that version.

1. Read a definition's card

The card is what the Twin's own agent reads about the definition:

• its meaning, grain, population, completeness and what it is not for;
• each dimension's type, its known values where there are few, and its classification;
• each measure's type, the aggregations it allows, how it may be read (declared_measure, or stored_source_value where its basis is the source's own amount), its additivity, and for a point-in-time measure the dates it adds up within (read it with latest and asOf);
• keys to other definitions, which a query can join or test with relatedRows;
• the query limits, and whether you may run records queries;
• freshness: when the connector data behind it last synced.

A card never names a database relation or SQL.

curl -fsS https://<gateway>/api/twin/products/invoice-totals \
  -H "Authorization: Bearer $TOKEN"

2. Run a governed query

The body is a governed request plus an optional idempotencyKey: the same key returns the same query instead of running it twice. Name every measure you select, filter or aggregate in measureBasis.

{
  "idempotencyKey": "invoice-totals-2026-10",
  "productSlug": "invoice-totals",
  "measureBasis": [{ "field": "invoice_total", "interpretation": "declared_measure" }],
  "queries": [{
    "id": "by_region",
    "kind": "aggregate",
    "groupBy": ["region"],
    "filters": [{ "field": "invoice_month", "operator": "eq", "value": "2026-10-01" }],
    "metrics": [{ "alias": "total", "function": "sum", "field": "invoice_total" }],
    "limit": 50
  }]
}

The query answers 202 with its ID. A request the definition's policy or your access does not allow is refused before it runs, with 422 and a code such as public_records_query_refused or public_field_not_classified.

3. Read the result

Poll twin.products.query.get until the status is completed or failed. A completed query carries:

• result.queries: each query's rows, and complete, which is false when the query matched more rows than its limit (narrow it, or raise the limit up to 200). Figures arrive exactly as certified: a count or an amount is a decimal string, such as "3" or "120.00", so no precision is lost;
• product: the definition's slug, version and productVersionSha256, and the same for a joined or related definition;
• result.freshness: the source sync status and dataAsOf (epoch milliseconds), with its basis;
• result.measureBindings: how each figure was read, with its basis hash. A count of the definition's rows (count_rows) has no field and the interpretation product_row_count; every other figure names its field, whether it was read as declared_measure or stored_source_value, and its aggregation;
• result.appliedPartitionFilters and result.openBuckets: the caveats the Twin's agent receives, such as a month that contains today;
• evidence.certificateRefs: the certificates that attest the result.

A refused query fails with the query tool's own code, for example governed_product_measure_basis_required, so you can correct the request.

4. Resolve the evidence behind an answer

twin.evidence.get takes any run you may read: a governed query's ID, or a session answer's. It returns the answer records with the certificates they cite, each governed read's receipt (rows and completeness per query) and the certificates by definition and version. It returns no result values.

A completed twin.query.get answer also carries evidence: its certificateRefs and answerRecordIds. The evidence entries of a session's presentation stream resolve through twin.evidence.get with their runId.

An answer from the organisation's graph also carries graphCertificateRefs, in both: one for each certified graph read, with its call and read (toolCallId and label, such as q1), the model, query and result hashes, dataAsOf, complete and rowCount. Only reads that match the answer the Twin kept for that call are listed, and the field is left out when the answer made none.

Approve a definition for public use

An organisation admin approves the version they reviewed, with each public field's classification:

{
  "productVersion": 3,
  "productVersionSha256": "…",
  "dataPolicy": "aggregate_non_personal",
  "reason": "Shared with our finance partner",
  "classification": {
    "reviewedBy": "finance-lead@example.com",
    "reviewedAt": 1793000000000,
    "evidenceRefs": ["review:invoice-totals-v3"],
    "fields": [
      { "field": "region", "classification": "non_personal_dimension" },
      { "field": "invoice_total", "classification": "aggregate_metric" }
    ]
  }
}

A version that is no longer the one serving is refused with 409. Clearing the approval works whether or not a version still serves.