---
title: "Update one field on a passport."
method: PATCH
path: "/api/v1/passports/{id}/fields/{key}"
tags: ["Passports"]
---

# Update one field on a passport.

`PATCH /api/v1/passports/{id}/fields/{key}`

## Request

- Base URL: `https://app.tracepass.eu`
- URL: `https://app.tracepass.eu/api/v1/passports/{id}/fields/{key}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.tracepass.eu/api/oauth/authorize`, token URL `https://app.tracepass.eu/api/oauth/token`, scopes: `passports:write`)

Patch a single field on a passport. The value is validated
against the field key (must exist on the passport's
template) and persisted with an audit-trail entry naming the
credential (`via API key <prefix>` or `via OAuth app <client>`)
and, when the `X-Source` header is set, the calling client
(e.g. `(mcp)`). The channel is recorded only; it never changes
the status.

Status: an API key writes `approved`. An OAuth token writes with
its user's dashboard rights, so a role below admin lands
`pending_review`. A value sent with `source: "ai_suggested"`
always lands `pending_review`, and is refused (400) on a field
that only the economic operator may state or that must be
measured (e.g. battery `stateOfHealth`). Send such a value with
another source if your organisation is making that statement.

An alternate addressing form exists at PATCH
`/api/v1/passports/by-serial/{serial}/fields/{key}` with
the same body shape.

## Request body

- UpdateFieldInput
  - `value` unknown, required
  - `source` 'manual' | 'ai_suggested' | 'reference_db' | 'supplier': Tag the origin of the value. Default `manual`. `ai_suggested` lands in the review queue; the others write with the caller's own rights (see the operation). A response may still show `ai_approved` or `system`: TracePass sets those, and a request claiming them is refused (400).
  - `sourceLocale` string: ISO 639-1 locale of the value. One of the 24 EU locales. Defaults to the passport's `sourceLocale`.

## Response `200`

Field updated.

- object
  - `field` PassportField, required
    - `value` unknown
    - `source` 'manual' | 'ai_suggested' | 'ai_approved' | 'reference_db' | 'supplier' | 'system' | 'derived': Who set the stored value. `derived` is a value calculated from other fields by a formula, not written by an AI model.
    - `aiProvenance` AiProvenance: Marks a value an AI system generated (EU AI Act Art. 50(2)). It stays on the field after a person approves or edits the value; only the two review flags change. Public passport outputs (viewer, JSON-LD, credential, PDF) mark the `research` and `translation` kinds.
      - `kind` 'research' | 'translation' | 'extraction': `research`: found and written by the AI. `translation`: machine translated. `extraction`: read from a document you uploaded.
      - `generatedAt` string, date-time
      - `model` string: The model that generated the value. Returned only to the owning account.
      - `humanReviewed` boolean
      - `humanEdited` boolean
    - `aiTranslated` boolean: Present and `true` on a `?lang=` response when the returned value is a machine translation (EU AI Act Art. 50(2) marking).
    - `sourceProvider` string: Identifier of the reference source that vouches for an AI-suggested value (for example a public register), with `sourceUrl` linking to its record where one is published. An open string: the set of sources can grow, so treat unknown values as "a named source". Absent when no single source vouches for the stored value, such as a value read from your own document or submitted by a supplier.
    - `sourceUrl` string, uri: The provider's canonical URL for this value, when it published one. Machine-readable companion to `evidence`.
    - `status` string
    - `accessLevel` string
    - `sourceLocale` string
    - `translations` object
    - `lastUpdatedAt` string, date-time
    - `lastUpdatedBy` string
  - `version` integer, required

## Other responses

- `400`: Validation error or malformed request.
- `401`: Missing or invalid API key.
- `404`: Resource doesn't exist or is in a different workspace.
- `422`: Idempotency-Key reused with a different request body. Use a new key for the new request, or reuse the original body.
- `429`: Daily v1 write or passport-read budget exhausted. Resets at 00:00 UTC.

---

[API](https://skmtc.dev/tracepass/apis/tracepass-api.md) · [All operations](https://skmtc.dev/tracepass/apis/tracepass-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tracepass/apis/tracepass-api/revisions/60ddeb25638b?raw)