---
title: "Batch upsert table draft records"
method: POST
path: "/reference-data/v1/tables/{tableUrn}/draft/batch/upsert"
tags: ["Reference data"]
---

# Batch upsert table draft records

`POST /reference-data/v1/tables/{tableUrn}/draft/batch/upsert`

## Request

- Base URL: `https://your-environment.ataccama.one/api`
- URL: `https://your-environment.ataccama.one/api/reference-data/v1/tables/{tableUrn}/draft/batch/upsert`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/docs/reference-data/v1/tables/:tableUrn/draft/batch/upsert/post.ts> (a function with typed inputs; its response is checked against the schema)

Create new records in the draft dataset, or update existing draft records, in a single batch operation.

Items with a `urn` update the existing record, items without one create a new record.
When you update an existing record, only the attributes you send are updated; all other attributes remain unchanged.
Address each record with at most one item: a record URN repeated in a later item fails that item with `VALIDATION_ERROR`.
Changes stay in the draft until they are published with the [Publish draft changes](#tag/reference-data/POST/reference-data/v1/tables/{tableUrn}/draft/publish) operation.

Each item carries a caller-supplied `id`, unique within the batch, which is echoed back in the corresponding result.
Results are returned in the order of the request items.
Save the URNs of newly created records from `results[].data` if you need to update or delete them later.

**Atomic**: either every item succeeds or nothing is written.
On success, every result has status `OK`.
On failure, each failing item reports its own error: `RESOURCE_NOT_FOUND` when its record URN does not exist in the draft,
or `VALIDATION_ERROR` when its values or its record URN are invalid. Every other item reports `NOT_PROCESSED`.
A failed batch still returns `207`: check `meta.fail` (or each `results[].status`), not only the HTTP status.
All failures found while validating the batch are reported together, so you can fix every failing item before retrying.
An unexpected failure while writing returns `500`, and nothing is written.
Retry the whole batch after fixing the failing items; nothing from a failed batch is kept.

Errors that concern the request as a whole are not reported per item: a body that violates the schema (for example a missing
or empty `id`, or a `urn` that is not a record URN), an empty batch, more than 100 items, or duplicate `id` values return `400`,
and a missing table or draft returns `404`.

## Path parameters

- `tableUrn` string, uri, required: A URN identifying a table resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:table:{uuid} Example: urn:ata:acme-corp:reference-data:table:123e4567-e89b-12d3-a456-426614174000.

## Request body

- object
  - `data` RecordBatchUpsertItem[], required
    - `id` string, required: Caller-supplied correlation ID, echoed back in the corresponding result item. Must be unique within the batch.
    - `urn` string, uri: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.
    - `values` RecordValue[], required
      - `name` string, required
      - `value` unknown
      - `recordUrn` string, uri: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.

## Response `207`

Multi-status batch outcome. Because the batch is atomic, either every item in `results` is `OK` (with `data`),
or none is: failing items carry their own error and all others are `NOT_PROCESSED`.
`meta.success` therefore equals `meta.total` on success and `0` on failure.

- object
  - `meta` BatchOperationMeta, required: Summary of a batch operation outcome. Lets clients assess batch health without iterating every item.
    - `total` integer, required: Number of items in the request.
    - `success` integer, required: Number of items with `OK` status.
    - `fail` integer, required: Number of items with non-`OK` status. `success + fail` equals `total`.
  - `results` RecordBatchResultItem[], required
    - union: Outcome of a single item in a batch upsert. `data` carries the created or updated record and is present only when `status` is `OK`; `error` is present only otherwise. The two are mutually exclusive.
      - object
        - `id` string, required: Echoes the `id` supplied on the corresponding request item.
        - `status` string, required: @ExtensibleEnum Outcome status for this item. `OK` indicates success; any other value indicates failure and equals the `type` of the accompanying `error`. - `RESOURCE_NOT_FOUND` — the record URN of the item does not exist in the table draft. - `VALIDATION_ERROR` — the item is invalid, for example a value does not match the attribute's data type, a referenced record does not exist, or its record URN is already addressed by an earlier item of the batch. - `NOT_PROCESSED` — the item itself is valid, but it was not written because another item in the batch failed.
        - `data` RecordWithState, required: Record with state information (used for draft and review records).
          - `urn` string, uri, required: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.
          - `values` RecordValue[], required: Record attribute values.
            - `name` string, required
            - `value` unknown
            - `recordUrn` string, uri: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.
          - `lastChangedAt` string, date-time: When the values of the record were last changed. A change keeps the time it was made as it moves from draft through review to publishing, so on a published record this is the time of the change, not of the publish. Absent when no change is recorded for the record. Changes are recorded shortly after they are saved, so for a record changed moments ago this can still show the previous change, or be absent if there was none.
          - `lastChangedByUrn` string, uri: A URN identifying a user in the IAM API. Unlike most URNs, the last segment is the user ID as IAM knows it rather than a UUID. A user ID can be any string, for example, an email address, a UUID, or `service-account-{client ID}` for an API client. Characters that a URN cannot contain, such as spaces, `%`, or `#`, are percent-encoded as UTF-8 with uppercase hex digits; all other characters are kept as they are. Users cannot be listed or retrieved through the public API. To find a user's ID, open the user in the web application (**Global settings > User management > Users**). Format: urn:ata:{tenant}:iam:user:{user ID} Example: urn:ata:acme-corp:iam:user:jane.doe@acme-corp.com.
          - `state` string, required: @ExtensibleEnum The state of the record in reference data management: - `NEW`: Newly created record, not yet published. - `CHANGED`: Modified record with unpublished changes. - `DELETED`: Record marked for deletion; removed from the published dataset when the deletion is published. - `UNCHANGED`: Published record with no pending changes. - `REVIEW`: Record submitted for review. Once approved, the record returns to the draft and must still be published.
        - `error` object: Present only when `status` is not `OK`. Its `type` equals `status`, and its `title` is fixed per type: `RESOURCE_NOT_FOUND` — `Resource Not Found`, `VALIDATION_ERROR` — `Validation Error`, `NOT_PROCESSED` — `Not Processed`.
          - `type` string, required: Error type identifier.
          - `title` string, required: Short, human-readable summary of the problem type.
          - `detail` string, required: Detailed specific explanation of the problem.
          - `errors` ValidationErrorDetail[]: Present only for `VALIDATION_ERROR`. Detailed validation errors of the item; each `pointer` is relative to the request item, for example `#/values/2/value`.
            - `detail` string, required: Specific error message for this validation failure.
            - `pointer` string, required: JSON Pointer (RFC 6901) to the field that caused the error.
      - object
        - `id` string, required: Echoes the `id` supplied on the corresponding request item.
        - `status` string, required: @ExtensibleEnum Outcome status for this item. `OK` indicates success; any other value indicates failure and equals the `type` of the accompanying `error`. - `RESOURCE_NOT_FOUND` — the record URN of the item does not exist in the table draft. - `VALIDATION_ERROR` — the item is invalid, for example a value does not match the attribute's data type, a referenced record does not exist, or its record URN is already addressed by an earlier item of the batch. - `NOT_PROCESSED` — the item itself is valid, but it was not written because another item in the batch failed.
        - `data` RecordWithState: Record with state information (used for draft and review records).
          - `urn` string, uri, required: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.
          - `values` RecordValue[], required: Record attribute values.
            - `name` string, required
            - `value` unknown
            - `recordUrn` string, uri: A URN identifying a record resource in the Reference Data API. Format: urn:ata:{tenant}:reference-data:record:{uuid} Example: urn:ata:acme-corp:reference-data:record:523e4567-e89b-12d3-a456-426614174004.
          - `lastChangedAt` string, date-time: When the values of the record were last changed. A change keeps the time it was made as it moves from draft through review to publishing, so on a published record this is the time of the change, not of the publish. Absent when no change is recorded for the record. Changes are recorded shortly after they are saved, so for a record changed moments ago this can still show the previous change, or be absent if there was none.
          - `lastChangedByUrn` string, uri: A URN identifying a user in the IAM API. Unlike most URNs, the last segment is the user ID as IAM knows it rather than a UUID. A user ID can be any string, for example, an email address, a UUID, or `service-account-{client ID}` for an API client. Characters that a URN cannot contain, such as spaces, `%`, or `#`, are percent-encoded as UTF-8 with uppercase hex digits; all other characters are kept as they are. Users cannot be listed or retrieved through the public API. To find a user's ID, open the user in the web application (**Global settings > User management > Users**). Format: urn:ata:{tenant}:iam:user:{user ID} Example: urn:ata:acme-corp:iam:user:jane.doe@acme-corp.com.
          - `state` string, required: @ExtensibleEnum The state of the record in reference data management: - `NEW`: Newly created record, not yet published. - `CHANGED`: Modified record with unpublished changes. - `DELETED`: Record marked for deletion; removed from the published dataset when the deletion is published. - `UNCHANGED`: Published record with no pending changes. - `REVIEW`: Record submitted for review. Once approved, the record returns to the draft and must still be published.
        - `error` object, required: Present only when `status` is not `OK`. Its `type` equals `status`, and its `title` is fixed per type: `RESOURCE_NOT_FOUND` — `Resource Not Found`, `VALIDATION_ERROR` — `Validation Error`, `NOT_PROCESSED` — `Not Processed`.
          - `type` string, required: Error type identifier.
          - `title` string, required: Short, human-readable summary of the problem type.
          - `detail` string, required: Detailed specific explanation of the problem.
          - `errors` ValidationErrorDetail[]: Present only for `VALIDATION_ERROR`. Detailed validation errors of the item; each `pointer` is relative to the request item, for example `#/values/2/value`.
            - `detail` string, required: Specific error message for this validation failure.
            - `pointer` string, required: JSON Pointer (RFC 6901) to the field that caused the error.

## Other responses

- `400`: Bad request. The request parameters or body are invalid.
- `403`: Forbidden. You do not have permission to access the requested resource.
- `404`: Not found. The requested resource does not exist.

---

[API](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api.md) - [All operations](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ataccama/apis/ataccama-one-agentic-data-trust-platform-public-api/revisions/46f16e0487f8?raw)