> ## Documentation Index > Fetch the complete documentation index at: https://docs.gable.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add and remove field tags on a component. > Add and remove tags on fields of one component. Each applied item appends one immutable event, which is both the stored state and the audit trail; reads fold those events per request. ## OpenAPI ````yaml /api-reference/bundled.yaml post /v0/component/{id}/field-tags openapi: 3.1.0 info: title: Gable API description: > API to interact with the Gable platform ## Authorization All API requests require an API key to be passed in the `X-API-KEY` header. For instructions on finding your API key and api endpoint check out the [API Key documentation](../docs/api-keys.md). Example: `curl -H "X-API-KEY: " https://api-{organization}.gable.ai/v0/ping` contact: name: Gable Engineering url: https://gable.ai email: engineers@gable.ai version: 1.54.0 servers: - url: https://{hostname}.gable.ai description: Gable API variables: hostname: default: demo-api description: Customer environment assigned by Gable security: - ApiKeyAuth: [] tags: - name: action - name: api-keys - name: auth - name: changelog - name: config - name: debug - name: settings - name: slack - name: sso - name: webhook - name: notifications - name: telemetry - name: component - name: components - name: sca - name: cross-service-components - name: lineage - name: events - name: measurements - name: defect-report - name: data-tagging description: Tag vocabulary management and field level tagging of lineage boundaries. paths: /v0/component/{id}/field-tags: post: tags: - data-tagging summary: Add and remove field tags on a component. description: >- Add and remove tags on fields of one component. Each applied item appends one immutable event, which is both the stored state and the audit trail; reads fold those events per request. operationId: postComponentFieldTags parameters: - in: path name: id required: true schema: type: string format: uuid description: UUID of the component whose fields are being tagged. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostFieldTagsRequest' responses: '200': description: >- Per item outcomes, in request order. Item level refusals are reported here rather than as an error status, so a partly applied batch stays legible per address. A batch is not a transaction: one bad address must not reject the other 499. content: application/json: schema: $ref: '#/components/schemas/PostFieldTagsResponse' '400': description: >- Malformed body, more than 500 items, or two items sharing the same `tag_id` and `target`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Component not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PostFieldTagsRequest: type: object description: >- Tag mutations for fields of one component. Items apply independently and report their own outcome; nothing is atomic across items. Two items sharing a `tag_id` and address are rejected with 400 rather than resolved last wins. properties: version_id: type: string description: >- The component version addresses resolve against, and whose commit resolves the appended events' `EffectiveSince*` fields. Defaults to the newest version. assignments: type: array minItems: 1 maxItems: 500 description: More than 500 is rejected with 400 rather than partly applied. items: type: object properties: tag_id: type: string minLength: 1 description: >- An unknown id comes back `TAG_NOT_FOUND`; an ADD naming a deactivated one, `TAG_INACTIVE`. operation: type: string description: >- Newest wins. REMOVE acts only on a tag applied to the field itself, so removing an inherited one comes back `ALREADY_ABSENT`. enum: - ADD - REMOVE target: description: >- Where the tag goes. A legacy boundary address (`boundary_coordinates`) targets a field of the component read's boundaries; a discriminator address (`payload`) targets a field of a `discriminator_data` payload group. The two are separate address spaces: a tag is visible only on the read whose vocabulary it was written with. oneOf: - $ref: '#/components/schemas/FieldAddress' - $ref: '#/components/schemas/DiscriminatorFieldAddress' required: - tag_id - operation - target additionalProperties: false required: - assignments additionalProperties: false PostFieldTagsResponse: type: object description: >- Per item outcomes for a bulk tag mutation. The status is 200 whenever the body itself was valid, because each item carries its own outcome. properties: results: type: array description: One entry per requested mutation, in request order. items: type: object properties: target: description: The requested address, echoed back verbatim. oneOf: - $ref: '#/components/schemas/FieldAddress' - $ref: '#/components/schemas/DiscriminatorFieldAddress' tag_id: type: string status: type: string description: >- What became of one requested mutation. `FAILED` is the only value worth retrying. * `APPLIED`: an event was appended and the tag's state changed. * `ALREADY_PRESENT`: an ADD whose tag is already effective there. * `ALREADY_ABSENT`: a REMOVE with nothing to remove, including one aimed at an inherited tag. * `TARGET_NOT_FOUND`: the address does not resolve against the version being written against: for a boundary address, its boundaries; for a discriminator address, its roll-up's payload groups and the fields their rows expose. A display name, a canonical boundary id, a field path absent from that version, a data store component, a payload address on another component or at the wrong level, or `boundary_coordinates` with nothing set all report here: one malformed address must not reject the other items. * `UNRESOLVED_ANCHOR`: that version's scan carries no resolvable commit metadata. Nothing is appended, because an unanchored event is discarded by every read. * `TAG_NOT_FOUND`: no definition exists under that `tag_id`. * `TAG_INACTIVE`: an ADD naming a deactivated definition. * `FAILED`: the append itself failed. Other items are unaffected. enum: - APPLIED - ALREADY_PRESENT - ALREADY_ABSENT - TARGET_NOT_FOUND - UNRESOLVED_ANCHOR - TAG_NOT_FOUND - TAG_INACTIVE - FAILED required: - target - tag_id - status additionalProperties: false required: - results additionalProperties: false ErrorResponse: type: object required: - message properties: id: type: number title: type: string message: type: string FieldAddress: type: object description: >- The address of one taggable field. Only ingress and egress fields of a code component are taggable. Resolved against the boundaries of the request's `version_id` (the newest version when omitted); anything that does not resolve is refused per item with `TARGET_NOT_FOUND`. properties: direction: type: string description: >- Which side of the component the field is on. Required: a pass through component can consume and produce the same payload name. enum: - ingress - egress boundary_coordinates: $ref: '#/components/schemas/BoundaryCoordinates' description: Which boundary the field sits on. field_path: type: string minLength: 1 description: >- Dotted path within the payload, for example `contact.email`. A parent struct is an address in its own right. No escape syntax, so a field whose own name contains a dot is not addressable. required: - direction - boundary_coordinates - field_path additionalProperties: false DiscriminatorFieldAddress: type: object description: >- The discriminator-native address of one taggable field: a payload group of the component (its canonical payload-level group address, as read back on `discriminator_data`), which side of that payload the field is on, and the field path. Resolved against the roll-up of the request's `version_id` (the newest version when omitted): the payload must be one of that version's payload groups and the field one that its field-mapping rows expose on that side; anything else is refused per item with `TARGET_NOT_FOUND`. Tags written with this address render on `discriminator_data?include=tags` and never on the legacy component read, and legacy boundary-addressed tags never render here: the two address vocabularies are kept apart by design. properties: payload: $ref: '#/components/schemas/DiscriminatorGroupAddress' description: >- The payload group's canonical address: `level` must be `payload` with no ancestors, and `componentId` must equal the route component. direction: type: string enum: - ingress - egress description: >- `ingress` addresses a row's `ingress_field` coordinate, `egress` its `egress_field` coordinate. field_path: type: string minLength: 1 description: >- Dotted field path, exactly the row coordinate it addresses. No escape syntax, so a field whose own name contains a dot is not addressable. required: - payload - direction - field_path additionalProperties: false BoundaryCoordinates: type: object description: >- Durable coordinates identifying one ingress or egress boundary. Either may be null. Copy this object rather than rebuilding it from the `payloadName` and `signatureName` beside it, which are filled in for display. A boundary the scan gave no payload name, on a path named `orders`, reads as `payloadName: "orders"` while its coordinates are `payload_name: null, signature_name: "OrdersController.create"`. properties: payload_name: description: The scanner's payload name, or null where it recorded none. anyOf: - type: string - type: 'null' signature_name: description: The package, class or method, or null where the scan recorded none. anyOf: - type: string - type: 'null' required: - payload_name - signature_name additionalProperties: false example: payload_name: null signature_name: OrdersController.create DiscriminatorGroupAddress: type: object description: The metadata coordinates for a discriminator group properties: componentId: type: string format: uuid description: The component this group lives on. Must equal the route component. level: $ref: '#/components/schemas/DiscriminatorLevel' ancestors: type: array description: >- Root-to-immediate-parent ancestor chain. Empty for a `payload`; exactly one `payload` entry for a `field_mapping`. Every ancestor carries the same component and config identity as this wrapper. items: $ref: '#/components/schemas/DiscriminatorGroupAncestor' coordinates: $ref: '#/components/schemas/DiscriminatorGroupCoordinates' required: - componentId - level - ancestors - coordinates additionalProperties: false DiscriminatorLevel: type: string description: >- A level in the product_canonical group hierarchy. `payload` is the root level; `field_mapping` is its child. The group_by dimensions for each level are defined by the config, not enumerated by this API (see DiscriminatorGroupCoordinates). enum: - payload - field_mapping DiscriminatorGroupAncestor: type: object description: >- One ancestor group in a canonical address chain. Ancestors are ordered root-to-immediate-parent: a `field_mapping` carries its `payload`, and a `payload` carries none. The chain's depth and each level's coordinate dimensions are the discriminator config's, not this API's — copy an ancestor's coordinates verbatim rather than rebuilding them. The service derives the parent chain from these coordinates; clients never supply an authoritative parent group ID. properties: level: $ref: '#/components/schemas/DiscriminatorLevel' coordinates: $ref: '#/components/schemas/DiscriminatorGroupCoordinates' required: - level - coordinates additionalProperties: false DiscriminatorGroupCoordinates: type: object description: >- Discriminator-group coordinates — the durable address of a group, as key-value pairs of the facts the group is grouped by. Keys are the discriminator config's group_by dimensions for the group's level, verbatim; the dimension vocabulary is defined by the config, not by this API. Values are the exact grouping facts; null is the engine's null coordinate (fact unknown). Edges and BYO metadata attach to lineage by these coordinates, never by group ID (group IDs are derived from coordinates by the discriminator engine and are only stable within one discriminator config). additionalProperties: description: >- A grouping fact. The engine's coordinate value algebra: null, boolean, integer, string, or array of strings. anyOf: - type: 'null' - type: boolean - type: integer - type: string - type: array items: type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.