Skip to main content

field_declarations

GET /field-declarations​

Get the current field declarations

The project's current (newest) field-declarations version (WP-D7 req 5): the canonical declarations, sorted by (event_type, attr_key), the 002 §10 fingerprint of \{"declarations": [...]\} (content only, so the same declarations fingerprint the same in every project) and contract_version, the draft the put that stored it created. Declarations are project-wide: both environments read the same document. 404 not_found before the first put.

Operation ID: getFieldDeclarations · Service: gateway-api

Authentication​

  • apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Responses​

StatusSchemaDescription
200FieldDeclarationsThe current field-declarations version.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

PUT /field-declarations​

Replace the field declarations

Replaces the project's field declarations (WP-D7 req 6) and answers the resulting version. A document identical to the current version (same fingerprint) answers that version and writes nothing, whatever expected_version says, so a retried put is safe. Otherwise an expected_version other than the current version (0 = none yet) is 400 failed_precondition (version_mismatch). A declaration that contradicts the approved contract or the draft guards is 400 failed_precondition with one FieldDeclarationRefusalDetail per offending declaration in error.details: declared_type_conflict (an approved attribute's declared_type never changes), pii_direct_feature (002 §4) or identifier_as_feature (the identifier rule updateContractDraft applies). A duplicate (event_type, attr_key), more than 4,096 declarations or a canonical document over 4 MiB is 400 invalid_argument. Nothing is written on any refusal. On success the put stores the next version, feeds every declared field into the project's profiling input (count 0, no samples) and creates one contract draft: a declared attribute the approved contract lacks takes the declared type with its default encoding, and the declared role, pii, missingness and description, instead of inference; an attribute the approved contract holds takes the declared role, pii, missingness and description as a PATCH of those fields would. When that draft would equal the approved contract, or the document is empty, no draft is created and contract_version is null. The put never approves: approve the draft with approveContract. annotations are stored and returned verbatim and never read. Requires org role owner|admin or an admin-scoped key.

Operation ID: putFieldDeclarations · Service: gateway-api

Authentication​

  • apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Request body​

FieldDeclarationsPut

Responses​

StatusSchemaDescription
200FieldDeclarationsThe resulting version (or the unchanged current one).
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

GET /field-declarations/{version}​

Get one field-declarations version

Any stored field-declarations version (WP-D7 req 5); versions are immutable. 404 not_found for a version this project never stored.

Operation ID: getFieldDeclarationsVersion · Service: gateway-api

Authentication​

  • apiKey (http (bearer)) — Project API key (003 §2): tsk_live_… or tsk_test_… in Authorization: Bearer. Scoped to exactly one project + environment; scopes are a subset of ingest, read, admin. Keys are stored hashed and shown once at creation.
  • consoleSession (http (bearer)) — Console session (003 §2): Identity Platform JWT. Data-plane calls add X-Tessera-Project + X-Tessera-Environment headers, validated against org membership.

Parameters​

NameInRequiredTypeDescription
versionpathyesintegerField-declarations version (per-project monotonic integer).

Responses​

StatusSchemaDescription
200FieldDeclarationsThe field-declarations version.
defaultErrorEnvelopeError response (003 §1). Every non-2xx response uses this envelope; the HTTP status matches error.code. Rate-limited requests get 429 resource_exhausted with retry_after_seconds and a Retry-After header; the X-RateLimit-* headers ride on EVERY response, success or error (003 §1; plan-driven per API key + endpoint class — WP-B2). A 503 unavailable carries retry_after_seconds too for a lock-wait timeout (SQLSTATE 55P03), a rule preview at capacity (preview_capacity_exhausted), or a label preview during which the erasure of every entity holding its censor clock began (label_preview_clock_entity_erased): how long to wait before retrying.

Errors​

Every non-2xx response uses the 003 §1 error envelope; error.request_id matches the X-Request-Id response header, and the HTTP status always matches error.code:

{
  "error": {
    "code": "invalid_argument",
    "details": [
      {
        "type": "field_violation"
      }
    ],
    "message": "human-readable",
    "request_id": "req_01hxample"
  }
}

Closed error-code set (003 §1): invalid_argument, unauthenticated, permission_denied, not_found, already_exists, failed_precondition, resource_exhausted, internal, unavailable.

resource_exhausted responses (HTTP 429) additionally carry retry_after_seconds. See ErrorEnvelope.