---
title: "Atomic Field Upsert"
method: POST
path: "/v0/logs/atomic"
tags: ["Logs"]
---

# Atomic Field Upsert

`POST /v0/logs/atomic`

Atomic find-or-create with atomic field update (upsert mode).

This endpoint atomically:
1. Ensures the context exists with correct unique_keys configuration
2. Acquires an advisory lock on the unique key values (prevents race on first insert)
3. Finds an existing log by unique_keys or creates it with initial_data
4. Applies an atomic operation to the specified field
5. If add_to_all_context=true, mirrors the log to the All/* archive context

Required body fields for upsert mode:
- project: Name of the project
- context: Context path for the log
- unique_keys: Key name to type mapping (e.g., {"_assistant_id": "str", "month": "str"})
- initial_data: Data for new log entry (must include all unique key values)
- operation: Atomic operation (+N, -N, *N, /N)

This is race-safe for concurrent first inserts - only one request will create the log,
and all concurrent requests will correctly increment the field.

## Request body

- AtomicFieldUpdateRequest — Request model for atomic field operations that are race-safe under concurrent updates. This endpoint supports two modes: 1. Update mode (default): Updates an existing log entry by log_id 2. Upsert mode: When project/context/unique_keys/initial_data are provided, finds or creates a log entry by unique keys, then applies the atomic operation. Upsert mode uses advisory locks to handle concurrent first inserts safely.
  - `operation` string, required — Atomic operation to apply. Supported formats: +N, -N, *N, /N where N is a number.
  - `field` string, nullable — (Upsert mode) Name of the numeric field to update atomically.
  - `project` string, nullable — (Upsert mode) Name of the project.
  - `context` string, nullable — (Upsert mode) Context path for the log.
  - `unique_keys` object, nullable — (Upsert mode) Unique key configuration for the context. Maps key names to types (str, int, float).
  - `initial_data` object, nullable — (Upsert mode) Data to use when creating a new log entry. Must include all unique key values.
  - `add_to_all_context` boolean — (Upsert mode) If true, also adds the log to the 'All/*' archive context.

## Response `200`

Atomic upsert applied successfully

- AtomicFieldUpdateResponse — Response from atomic field update operation.
  - `new_value` number, required — The new value of the field after the operation.
  - `log_id` integer, nullable — ID of the log entry (included in upsert mode).
  - `created` boolean, nullable — True if a new log was created (upsert mode only).
  - `mirrored_contexts` string[], nullable — List of archive contexts the log was mirrored to (upsert mode only).

## Other responses

- `400` — Invalid operation format or missing required fields
- `404` — Project not found
- `422` — Validation Error

---

[API](https://skmtc.net/unify/apis/unifyai-http-api-reference.md) · [All operations](https://skmtc.net/unify/apis/unifyai-http-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unify/unifyai-http-api-reference/revisions/900377f918b6/schema)