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

# Upsert rows by key values

> For each row, match on a single **key** column:

- **0 matches** → a new row is created (`action: created`).
- **1 match** → the existing row is updated (`action: updated`).
- **>1 matches** → returns an `AMBIGUOUS_MATCH` error for that row.

The `key` dict must contain exactly one entry `{column_name: value}`.

<Info>
  **Upsert = update or create.** Rows are matched by the key columns you specify. If a matching row exists, it is updated; otherwise a new row is inserted.
</Info>


## OpenAPI

````yaml /api-reference/openapi.json POST /v1/table/{table_uuid}/rows/upsert
openapi: 3.1.0
info:
  title: Databar.ai API
  description: >-

    # Authentication


    Databar uses API keys to allow access to the API. You can find your API key
    in your workspace home page, but to use the REST API you’ll first need to
    schedule a call with us.

    Our API expects the API key to be included in all API requests to the server
    in the Header of your request with the key `x-apikey`.

    To find your API key, head over to your Databar workspace and click
    Integrations.


    **Example:**


    `bash

    curl https://api.databar.ai/v1/user/me -H x-apikey: {YOUR_API_KEY}`
  contact:
    email: info@databar.ai
  version: 0.1.2
servers:
  - url: https://api.databar.ai
    description: Production
security: []
paths:
  /v1/table/{table_uuid}/rows/upsert:
    post:
      tags:
        - Table
      summary: Update or create rows by key
      description: |-
        For each row, match on a single **key** column:

        - **0 matches** → a new row is created (`action: created`).
        - **1 match** → the existing row is updated (`action: updated`).
        - **>1 matches** → returns an `AMBIGUOUS_MATCH` error for that row.

        The `key` dict must contain exactly one entry `{column_name: value}`.
      operationId: Upsert_rows_v1_table__table_uuid__rows_upsert_post
      parameters:
        - name: table_uuid
          in: path
          required: true
          schema:
            type: string
            format: uuid
            description: The UUID of the table
            title: Table Uuid
          description: The UUID of the table
        - name: x-apikey
          in: header
          required: true
          schema:
            type: string
            title: API Key
            description: API Key for authentication
          description: API Key for authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertResponse'
        '400':
          description: Validation error (BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SDKErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UpsertRequest:
      properties:
        rows:
          items:
            $ref: '#/components/schemas/UpsertRow'
          type: array
          maxItems: 50
          minItems: 1
          title: Rows
          description: List of rows to upsert (max 50).
        return_rows:
          type: boolean
          title: Return Rows
          description: If true, each result includes full row_data.
          default: false
      type: object
      required:
        - rows
      title: UpsertRequest
      example:
        return_rows: false
        rows:
          - fields:
              company_name: Acme
              first_name: Ivan
            key:
              email: ivan@example.com
          - fields:
              first_name: New Person
              title: Engineer
            key:
              email: new@example.com
    UpsertResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/UpsertResultItem'
          type: array
          title: Results
      type: object
      required:
        - results
      title: UpsertResponse
      example:
        results:
          - action: updated
            id: 91f0e833-5dfc-4f63-be96-e3a28925190f
          - action: created
            id: a1b2c3d4-0000-0000-0000-000000000000
            index: 1
    SDKErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: 'Error code: BATCH_TOO_LARGE, UNKNOWN_COLUMNS, INVALID_DATA.'
        max_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Size
          description: Maximum batch size (only for BATCH_TOO_LARGE).
        columns:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Columns
          description: Unknown column names (only for UNKNOWN_COLUMNS).
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
          description: Human-readable error message (only for INVALID_DATA).
      type: object
      required:
        - error
      title: SDKErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpsertRow:
      properties:
        key:
          type: object
          maxProperties: 1
          minProperties: 1
          title: Key
          description: >-
            Exactly one column to match on: {column_name: value}. If no match —
            create, if one match — update, if multiple — AMBIGUOUS_MATCH error.
          example:
            email: ivan@example.com
        fields:
          type: object
          title: Fields
          description: Column values to set/update, keyed by human-readable column name.
          example:
            company_name: Acme
            first_name: Ivan
      type: object
      required:
        - key
        - fields
      title: UpsertRow
    UpsertResultItem:
      properties:
        index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Index
          description: Original index in the request array (present for created rows).
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: UUID of the updated or newly created row.
        action:
          anyOf:
            - type: string
              enum:
                - updated
                - created
            - type: 'null'
          title: Action
          description: '''updated'' or ''created''.'
        error:
          anyOf:
            - type: object
            - type: 'null'
          title: Error
          description: 'Error object, e.g. {"code": "AMBIGUOUS_MATCH", "matches": 3}.'
        row_data:
          anyOf:
            - type: object
            - type: 'null'
          title: Row Data
          description: Full row data (only when return_rows=true).
      type: object
      title: UpsertResultItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````