List Fields

List canonical fields from the field registry with cursor pagination, search, tier filtering, and cluster filtering. Returns field metadata and occurrence counts.

The field registry is the knowledge graph of all canonical fields discovered across your extracted documents. Every time Talonic processes a document, it maps raw field names to canonical entries in the registry — normalizing variations like inv_num, Invoice Number, and invoice_no into a single canonical field.

Fields are organized into three tiers based on extraction frequency: Tier 1 (core) fields appear consistently across document types and have the highest confidence. Tier 2 (established) fields appear regularly but in fewer document types. Tier 3 (emerging) fields have been seen only a handful of times and may still be evolving.

Each field belongs to a semantic cluster — a group of conceptually related fields discovered through embedding similarity. For example, invoice_number, po_number, and order_id might share a cluster called "identifiers". Clusters help you understand the shape of your data without manually categorizing hundreds of fields.

Use GET /v1/fields to browse, search, and filter the registry. The endpoint supports cursor-based pagination for efficient traversal of large registries, and filtering by tier, cluster, and name search.

The field registry is read-only via the API. Fields are created and promoted automatically as documents are extracted. Use the platform UI to manually merge, rename, or reclassify fields.

GET/v1/fields

Response

Response fields

dataarrayArray of field objects.

data[].idstringField UUID.

data[].canonical_namestringNormalized canonical field name (e.g. invoice_number).

data[].display_namestringHuman-readable display name (e.g. Invoice Number).

data[].data_typestringInferred data type (string, number, date, boolean, array).

data[].tierintegerTier level: 1 (core), 2 (established), 3 (emerging).

data[].cluster_namestringName of the semantic cluster this field belongs to.

data[].occurrence_countintegerTotal number of times this field has been extracted across all documents.

data[].master_instructionstring | nullSynthesized extraction instruction derived from field occurrences.

data[].created_atstringISO 8601 creation timestamp.

data[].updated_atstringISO 8601 last update timestamp.

data[].linksobjectRelated resource URLs.

data[].links.selfstringURL to fetch this field by ID.

data[].links.similarstringURL to find similar fields by embedding similarity.

pagination.totalintegerTotal number of fields matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "canonical_name": "invoice_number",
      "display_name": "Invoice Number",
      "data_type": "string",
      "tier": 1,
      "cluster_name": "identifiers",
      "occurrence_count": 1847,
      "master_instruction": "Extract the unique invoice identifier, typically alphanumeric, found in the header area of the document.",
      "created_at": "2024-06-15T10:00:00.000Z",
      "updated_at": "2024-12-01T08:30:00.000Z",
      "links": {
        "self": "/v1/fields/f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "similar": "/v1/fields/f1a2b3c4-d5e6-7890-abcd-ef1234567890/similar"
      }
    },
    {
      "id": "a2b3c4d5-e6f7-8901-bcde-f23456789012",
      "canonical_name": "total_amount",
      "display_name": "Total Amount",
      "data_type": "number",
      "tier": 1,
      "cluster_name": "financials",
      "occurrence_count": 1523,
      "master_instruction": "Extract the final total or grand total amount, usually at the bottom of the document after tax and discounts.",
      "created_at": "2024-06-15T10:05:00.000Z",
      "updated_at": "2024-11-28T15:20:00.000Z",
      "links": {
        "self": "/v1/fields/a2b3c4d5-e6f7-8901-bcde-f23456789012",
        "similar": "/v1/fields/a2b3c4d5-e6f7-8901-bcde-f23456789012/similar"
      }
    }
  ],
  "pagination": {
    "total": 342,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImEyYjNjNGQ1LWU2ZjctODkwMS1iY2RlLWYyMzQ1Njc4OTAxMiJ9"
  }
}

Filter by tier

curl -H "Authorization: Bearer tlnc_..." \
  "https://api.talonic.com/v1/fields?tier=1&limit=50"

Errors

Error responses

400validation_errorInvalid tier value (must be 1, 2, or 3) or invalid cluster_id format.

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Field Harmonization

Get Field

List Schemas