> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Upsert a record

> Create or update a record using a stable UUID that your integration owns.

Create or update a record using a stable UUID that your integration owns.

Use a developer access key. See [authentication, errors, and rate limits](/api-reference/authentication).

Required scopes: `records:write`.

Existing values are merged, not fully replaced. An ID belonging to another workspace or object returns `409`. Upsert does not restore archived records. Persist your source-to-UUID mapping before retries; do not generate a new UUID on every run.

## Parameters

<ParamField path="recordId" type="string" required>
  A valid UUID. Reuse the same UUID for the same external item.
</ParamField>

<ParamField body="object" type="string" required>
  Object ID or slug; required even when updating.
</ParamField>

<ParamField body="values" type="object">
  Map writable field IDs or unambiguous slugs to values matching their field definitions. Unknown fields are rejected. Read-only fields are ignored. Discover the schema first; the example assumes a text field named `name` on `clients`. Defaults to an empty map.
</ParamField>

## Response

**201** — `201` for creation or `200` for update, both with `data` containing the record.

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "id": "8fb46bce-310b-4b39-b7cb-f46650317409",
      "objectTypeId": "object_example",
      "title": "Northlane",
      "avatarUrl": null,
      "values": {
        "field_name": "Northlane"
      },
      "archived": false,
      "createdBy": "user_example",
      "createdAt": "2026-09-07T12:00:00.000Z",
      "updatedAt": "2026-09-07T12:00:00.000Z"
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash Request theme={null}
  curl --fail-with-body --silent --show-error \
    -X PUT \
    "https://api.getkato.io/v1/records/$KATO_RECORD_ID" \
    -H "Authorization: Bearer $KATO_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "object": "clients",
    "values": {
      "name": "Northlane"
    }
  }'
  ```
</RequestExample>

Set path-ID environment variables to values returned by your workspace before running the request.

This request changes workspace data. A timeout does not prove that the write failed; inspect the result before retrying.


## Related topics

- [All endpoints](/api-reference/endpoints.md)
- [Sync client records](/recipes/sync-client-records.md)
- [Objects and records API](/api-reference/objects-and-records.md)
- [Authentication and API conventions](/api-reference/authentication.md)
- [Get a record](/api-reference/records/get.md)