Records

Create, read, update, upsert, delete, archive, restore and merge records.

Start with: records_create, records_get, records_update, records_upsert_batch, records_delete.

19 operations. Discover them from an agent with agentdb_capabilities {"category": "records"}.

#`records.history`

stable

records history

REST: GET /v1/workspaces/{ws}/records/{record}/history scope records:read

Parameter	In	Type	Required	Description
`ws`	path	`string`	yes	string
`record`	path	`string`	yes	string
`cursor`	query	`integer`		integer, at least 1
`limit`	query	`integer`		integer, 1–100, default 50

Example

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/<record>/history" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`records_archive`

stable added in 1.0.0-rc.6 changes data

Archive records: they keep their links and files but are left out of queries, aggregates, search and related lists unless include_archived=true. records_get still returns them (with archived_at). Undo with records_unarchive.

MCP tool: records_archive
REST: POST /v1/workspaces/{ws}/records/archive scope records:write
CLI: agentdb records archive

Arguments

Argument	Type	Required	Description
`ids`	`string[]`	yes	Ids of the records to archive (up to 1000). (max 1000 items)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_archive",
  "arguments": {
    "ids": [
      "rec_example"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_archive",
    "arguments": {
      "ids": [
        "rec_example"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/archive" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["rec_example"]}'

CLI

agentdb records archive [options] <ids...>

#`records_changes`

stable added in 1.0.0-beta.2 read-only

What changed in the workspace since a sequence number: records created/updated/deleted, schema changes, imports (action, id, version, time). Start with after=0 or the marker from a previous call; pass next_after to continue. Use it to keep a summary or another system in sync.

MCP tool: records_changes
REST: GET /v1/workspaces/{ws}/changes scope records:read

Arguments

Argument	Type	Description
`after`	`integer`	integer, at least 0, default 0
`limit`	`integer`	integer, 1–500, default 100
`workspace`	`string`	Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_changes",
  "arguments": {
    "after": 0,
    "limit": 100
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_changes",
    "arguments": {
      "after": 0,
      "limit": 100
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/changes" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

#`records_create`

stable added in 0.2.0-alpha.4 or earlier changes data

Create one record. data keys must be defined fields with correctly typed values; unknown fields are rejected.

MCP tool: records_create
REST: POST /v1/workspaces/{ws}/records scope records:write
CLI: agentdb records create

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`data`	`object`	yes	Field values by field name.
`links`	`object[]`		object[], up to 20 items
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_create",
  "arguments": {
    "object": "contact",
    "data": {
      "first_name": "Ada",
      "last_name": "Example",
      "email": "ada@example.test"
    }
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_create",
    "arguments": {
      "object": "contact",
      "data": {
        "first_name": "Ada",
        "last_name": "Example",
        "email": "ada@example.test"
      }
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","data":{"first_name":"Ada","last_name":"Example","email":"ada@example.test"}}'

CLI

agentdb records create [options] <object>

#`records_delete`

stable added in 0.2.0-alpha.8 changes data destructive

Delete one record (and its links and attachments; attached files are kept). Pass version to delete only if it is unchanged. Returns NOT_FOUND for unknown ids.

MCP tool: records_delete
REST: DELETE /v1/workspaces/{ws}/records/{record} scope records:write
CLI: agentdb records delete

Arguments

Argument	Type	Required	Description
`version`	`integer`		The current version of the item. The call fails with VERSION_CONFLICT if it changed.
`permanent`	`boolean`		boolean
`record_id`	`string`	yes	Record id (rec_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

version comes from records_get or the previous write.

MCP

{
  "tool": "records_delete",
  "arguments": {
    "record_id": "rec_example",
    "version": 2
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_delete",
    "arguments": {
      "record_id": "rec_example",
      "version": 2
    }
  }
}

REST

curl -s -X DELETE "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/rec_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":2}'

CLI

agentdb records delete [options] <id>

#`records_delete_batch`

stable added in 0.2.0-alpha.8 changes data destructive

Delete up to 1000 records of one object, by ids or by a where filter (same format as records_query). With where, expected_count must equal the number of matching records or nothing is deleted (CONFIRMATION_REQUIRED tells you the real count). Run with dry_run=true first to see the count and sample ids. ids mode: atomic=true (default) deletes nothing if an id is missing. Returns deleted, ids, links_removed, attachments_removed.

MCP tool: records_delete_batch
REST: POST /v1/workspaces/{ws}/records/delete scope records:write

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`ids`	`string[]`		Record ids. (max 1000 items)
`where`	`object`		object
`expected_count`	`integer`		integer, at least 0
`atomic`	`boolean`		boolean, default true
`dry_run`	`boolean`		boolean, default false
`permanent`	`boolean`		boolean
`include_archived`	`boolean`		boolean
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_delete_batch",
  "arguments": {
    "object": "contact",
    "where": {
      "all": [
        {
          "field": "email",
          "op": "is_null"
        }
      ]
    },
    "expected_count": 3,
    "dry_run": true
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_delete_batch",
    "arguments": {
      "object": "contact",
      "where": {
        "all": [
          {
            "field": "email",
            "op": "is_null"
          }
        ]
      },
      "expected_count": 3,
      "dry_run": true
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/delete" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","where":{"all":[{"field":"email","op":"is_null"}]},"expected_count":3,"dry_run":true}'

#`records_duplicates`

stable added in 1.0.0-rc.6 read-only

Suggest likely duplicate records of one object by fields (mode exact, normalized (fold level: trim, case, accents, punctuation (default) or company) or similar (trigram similarity >= threshold)), with evidence and the level matched. Suggestions only: AgentDB never merges on its own.

MCP tool: records_duplicates
REST: POST /v1/workspaces/{ws}/duplicates scope records:read
CLI: agentdb records duplicates

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`fields`	`string[]`	yes	Fields to compare (1 to 5). Records with the same values are listed together. (max 5 items)
`mode`	`"exact" \| "normalized" \| "similar"`		string, one of: exact, normalized, similar, default "normalized"
`level`	`"exact" \| "trim" \| "case" \| "accents" \| "punctuation" \| "company"`		string, one of: exact, trim, case, accents, punctuation, company
`threshold`	`number`		number, 0.5–1, default 0.8
`where`	`object`		object
`limit`	`integer`		integer, 1–200, default 50
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_duplicates",
  "arguments": {
    "object": "contact",
    "fields": [
      "email"
    ],
    "mode": "normalized",
    "level": "case"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_duplicates",
    "arguments": {
      "object": "contact",
      "fields": [
        "email"
      ],
      "mode": "normalized",
      "level": "case"
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/duplicates" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","fields":["email"],"mode":"normalized","level":"case"}'

CLI

agentdb records duplicates [options]

#`records_get`

stable added in 0.2.0-alpha.4 or earlier read-only

Fetch one record with its current version.

MCP tool: records_get
REST: GET /v1/workspaces/{ws}/records/{record} scope records:read
CLI: agentdb records get

Arguments

Argument	Type	Required	Description
`record_id`	`string`	yes	Record id (rec_...)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_get",
  "arguments": {
    "record_id": "rec_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_get",
    "arguments": {
      "record_id": "rec_example"
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/rec_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb records get [options] <id>

#`records_merge`

stable added in 1.0.0-rc.6 changes data destructive

Merge records into a survivor: field_choices {field: record_id} is required for every conflicting field; links and attachments move to the survivor; merged records go to the recycle bin. Audited; undo with records_merge_undo while they are in the recycle bin.

MCP tool: records_merge
REST: POST /v1/workspaces/{ws}/records/merge scope records:write
CLI: agentdb records merge

Arguments

Argument	Type	Required	Description
`survivor_id`	`string`	yes	Id of the record that stays.
`merged_ids`	`string[]`	yes	Ids of the records merged into the survivor. (max 10 items)
`field_choices`	`object`		object, default {}
`versions`	`object`	yes	The current version of each record, by record id.
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

versions: each record's current version, from records_merge_preview.

MCP

{
  "tool": "records_merge",
  "arguments": {
    "survivor_id": "rec_example",
    "merged_ids": [
      "rec_example_2"
    ],
    "versions": {
      "rec_example": 3,
      "rec_example_2": 1
    }
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_merge",
    "arguments": {
      "survivor_id": "rec_example",
      "merged_ids": [
        "rec_example_2"
      ],
      "versions": {
        "rec_example": 3,
        "rec_example_2": 1
      }
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/merge" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"survivor_id":"rec_example","merged_ids":["rec_example_2"],"versions":{"rec_example":3,"rec_example_2":1}}'

CLI

agentdb records merge [options]

#`records_merge_preview`

stable added in 1.0.0-rc.6 read-only

Preview merging records into a survivor: every field value, the conflicts you must choose for, the links and files that would move, and the versions to pass to records_merge.

MCP tool: records_merge_preview
REST: POST /v1/workspaces/{ws}/merge-preview scope records:read
CLI: agentdb records merge-preview

Arguments

Argument	Type	Required	Description
`survivor_id`	`string`	yes	Id of the record that stays.
`merged_ids`	`string[]`	yes	Ids of the records merged into the survivor. (max 10 items)
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_merge_preview",
  "arguments": {
    "survivor_id": "rec_example",
    "merged_ids": [
      "rec_example_2"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_merge_preview",
    "arguments": {
      "survivor_id": "rec_example",
      "merged_ids": [
        "rec_example_2"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/merge-preview" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"survivor_id":"rec_example","merged_ids":["rec_example_2"]}'

CLI

agentdb records merge-preview [options] <survivor_id> <merged_ids...>

#`records_merge_undo`

stable added in 1.0.0-rc.6 changes data

Undo a merge: restores the merged records, their links and files, and the survivor's earlier values (if it has not changed since).

MCP tool: records_merge_undo
REST: POST /v1/workspaces/{ws}/merges/{merge}/undo scope records:write
CLI: agentdb records merge-undo

Arguments

Argument	Type	Required	Description
`merge_id`	`string`	yes	Merge id (mrg_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

merge_id comes from records_merge or records_merges.

MCP

{
  "tool": "records_merge_undo",
  "arguments": {
    "merge_id": "mrg_example"
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_merge_undo",
    "arguments": {
      "merge_id": "mrg_example"
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/merges/mrg_example/undo" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

CLI

agentdb records merge-undo [options] <merge_id>

#`records_merges`

stable added in 1.0.0-rc.6 read-only

Merge history (newest first), optionally for one survivor.

MCP tool: records_merges
REST: GET /v1/workspaces/{ws}/merges scope records:read
CLI: agentdb records merges

Arguments

Argument	Type	Description
`record_id`	`string`	Record id.
`limit`	`integer`	integer, 1–100, default 20
`workspace`	`string`	Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_merges",
  "arguments": {
    "record_id": "rec_example",
    "limit": 10
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_merges",
    "arguments": {
      "record_id": "rec_example",
      "limit": 10
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/merges" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb records merges [options]

#`records_purge`

stable added in 1.0.0-rc.6 changes data destructive

Delete records in the recycle bin for good. Cannot be undone.

MCP tool: records_purge
REST: POST /v1/workspaces/{ws}/records/purge scope records:write
CLI: agentdb records purge

Arguments

Argument	Type	Required	Description
`ids`	`string[]`	yes	Ids of deleted records to remove for good (up to 1000). (max 1000 items)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_purge",
  "arguments": {
    "ids": [
      "rec_example"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_purge",
    "arguments": {
      "ids": [
        "rec_example"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/purge" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["rec_example"]}'

CLI

agentdb records purge [options] <ids...>

#`records_recycle_bin`

stable added in 1.0.0-rc.6 read-only

Deleted records that can still be restored (records_delete moves records to the recycle bin), with their deletion time and purge_after date.

MCP tool: records_recycle_bin
REST: GET /v1/workspaces/{ws}/recycle-bin scope records:read
CLI: agentdb records recycle-bin

Arguments

Argument	Type	Description
`object`	`string`	Object type name, e.g. contact.
`limit`	`integer`	integer, 1–200, default 50
`after`	`string`	string, up to 100 characters
`workspace`	`string`	Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_recycle_bin",
  "arguments": {
    "object": "contact",
    "limit": 20
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_recycle_bin",
    "arguments": {
      "object": "contact",
      "limit": 20
    }
  }
}

REST

curl -s "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/recycle-bin" \
  -H "Authorization: Bearer $AGENTDB_TOKEN"

CLI

agentdb records recycle-bin [options]

#`records_restore`

stable added in 1.0.0-rc.6 changes data

Restore deleted records from the recycle bin with their id, data, links and attachments. Fails (nothing changes) on a taken unique value, a missing required link target, or values that no longer fit the schema (allow_dropped_values=true restores without them and lists them). dry_run=true previews.

MCP tool: records_restore
REST: POST /v1/workspaces/{ws}/records/restore scope records:write
CLI: agentdb records restore

Arguments

Argument	Type	Required	Description
`ids`	`string[]`	yes	Ids of deleted records to restore from the recycle bin (up to 1000). (max 1000 items)
`allow_dropped_values`	`boolean`		boolean, default false
`dry_run`	`boolean`		boolean, default false
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_restore",
  "arguments": {
    "ids": [
      "rec_example"
    ],
    "dry_run": true
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_restore",
    "arguments": {
      "ids": [
        "rec_example"
      ],
      "dry_run": true
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/restore" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["rec_example"],"dry_run":true}'

CLI

agentdb records restore [options] <ids...>

#`records_unarchive`

stable added in 1.0.0-rc.6 changes data

Bring archived records back into queries.

MCP tool: records_unarchive
REST: POST /v1/workspaces/{ws}/records/unarchive scope records:write
CLI: agentdb records unarchive

Arguments

Argument	Type	Required	Description
`ids`	`string[]`	yes	Ids of the records to bring back from the archive (up to 1000). (max 1000 items)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_unarchive",
  "arguments": {
    "ids": [
      "rec_example"
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_unarchive",
    "arguments": {
      "ids": [
        "rec_example"
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/unarchive" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["rec_example"]}'

CLI

agentdb records unarchive [options] <ids...>

#`records_update`

stable added in 0.2.0-alpha.4 or earlier changes data

Change some fields of a record. version must equal the record's current version or the call fails with VERSION_CONFLICT. null removes a field. A patch that changes nothing keeps the version.

MCP tool: records_update
REST: PATCH /v1/workspaces/{ws}/records/{record} scope records:write
CLI: agentdb records update

Arguments

Argument	Type	Required	Description
`version`	`integer`	yes	The current version of the item. The call fails with VERSION_CONFLICT if it changed.
`data`	`object`	yes	Field values by field name.
`record_id`	`string`	yes	Record id (rec_...)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

version comes from records_get or the previous write.

MCP

{
  "tool": "records_update",
  "arguments": {
    "record_id": "rec_example",
    "version": 1,
    "data": {
      "email": "ada.new@example.test"
    }
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_update",
    "arguments": {
      "record_id": "rec_example",
      "version": 1,
      "data": {
        "email": "ada.new@example.test"
      }
    }
  }
}

REST

curl -s -X PATCH "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/rec_example" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"version":1,"data":{"email":"ada.new@example.test"}}'

CLI

agentdb records update [options] <id>

#`records_upsert`

stable added in 1.0.0-beta.3 changes data

Create-or-update ONE record by its match key: "id", a unique field, or a declared composite key (match_on: ["first_name","last_name","company_id"], defined once with schema_define_unique_key). Returns status created | updated | unchanged and the record. A missing key value fails (never guessed); a match never merges with a different record. Pass version to require it is unchanged.

MCP tool: records_upsert
REST: POST /v1/workspaces/{ws}/records/upsert-one scope records:write
REST: POST /v1/workspaces/{ws}/records/upsert scope records:write
CLI: agentdb records upsert

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`match_on`	`string \| string[]`	yes	How items are matched: "id", a unique field name, or the fields of a composite unique key.
`id`	`string`		string
`version`	`integer`		The current version of the item. The call fails with VERSION_CONFLICT if it changed.
`data`	`object`	yes	Field values by field name.
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_upsert",
  "arguments": {
    "object": "contact",
    "match_on": "email",
    "data": {
      "email": "ada@example.test",
      "first_name": "Ada"
    }
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_upsert",
    "arguments": {
      "object": "contact",
      "match_on": "email",
      "data": {
        "email": "ada@example.test",
        "first_name": "Ada"
      }
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/upsert-one" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","match_on":"email","data":{"email":"ada@example.test","first_name":"Ada"}}'

CLI

agentdb records upsert [options] <object>

#`records_upsert_batch`

stable added in 0.2.0-alpha.4 or earlier changes data

Create-or-update up to 500 records of one object in one transaction. match_on is "id" (update existing records), a unique field name, or a list of fields forming a composite unique key (schema_define_unique_key). dry_run=true validates every item and reports what would happen (failed items carry identifier, field and error) without writing. atomic=true (default): any failing item rejects the whole batch with BATCH_REJECTED and nothing is written. atomic=false: valid items are saved and failures are listed per index. Items without version overwrite the matched record (last write wins); pass version to require it is unchanged. Items missing the match_on value fail by default; on_missing_match_key="skip" reports them as skipped instead (never created). Duplicate match keys in one batch reject the whole batch. client_ref on an item is echoed in its result. match_fold "case" (or "trim") matches text keys ignoring case/spacing: the stored key is kept, keys equal once folded count as duplicates, and two stored records that collide once folded fail with MATCH_FOLD_COLLISION (never merged). Prefer type email for e-mail fields.

MCP tool: records_upsert_batch
REST: POST /v1/workspaces/{ws}/records/upsert scope records:write

Arguments

Argument	Type	Required	Description
`object`	`string`	yes	Object type name, e.g. contact.
`match_on`	`string \| string[]`	yes	How items are matched: "id", a unique field name, or the fields of a composite unique key.
`dry_run`	`boolean`		boolean, default false
`atomic`	`boolean`		boolean, default true
`on_missing_match_key`	`"error" \| "skip"`		string, one of: error, skip, default "error"
`match_fold`	`"exact" \| "trim" \| "case"`		string, one of: exact, trim, case, default "exact"
`records`	`object[]`	yes	The items (up to 500), each {data, client_ref?}. (max 500 items)
`idempotency_key`	`string`		Optional retry key ([A-Za-z0-9._:-], max 255). Repeating a call with the same key and arguments returns the original result without writing again.
`workspace`	`string`		Workspace id (preferred), slug or exact name. Omit for the default workspace. Resolve names once with workspace_select.

Example

MCP

{
  "tool": "records_upsert_batch",
  "arguments": {
    "object": "contact",
    "match_on": "email",
    "dry_run": true,
    "records": [
      {
        "client_ref": "line 2",
        "data": {
          "email": "ada@example.test",
          "first_name": "Ada"
        }
      },
      {
        "client_ref": "line 3",
        "data": {
          "email": "bob@example.test",
          "first_name": "Bob"
        }
      }
    ]
  }
}

MCP via agentdb_execute

{
  "tool": "agentdb_execute",
  "arguments": {
    "operation": "records_upsert_batch",
    "arguments": {
      "object": "contact",
      "match_on": "email",
      "dry_run": true,
      "records": [
        {
          "client_ref": "line 2",
          "data": {
            "email": "ada@example.test",
            "first_name": "Ada"
          }
        },
        {
          "client_ref": "line 3",
          "data": {
            "email": "bob@example.test",
            "first_name": "Bob"
          }
        }
      ]
    }
  }
}

REST

curl -s -X POST "https://app.agentdb.link/v1/workspaces/$AGENTDB_WORKSPACE/records/upsert" \
  -H "Authorization: Bearer $AGENTDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"object":"contact","match_on":"email","dry_run":true,"records":[{"client_ref":"line 2","data":{"email":"ada@example.test","first_name":"Ada"}},{"client_ref":"line 3","data":{"email":"bob@example.test","first_name":"Bob"}}]}'

Records

#records.history

Example

#records_archive

Arguments

Example

#records_changes

Arguments

Example

#records_create

Arguments

Example

#records_delete

Arguments

Example

#records_delete_batch

Arguments

Example

#records_duplicates

Arguments

Example

#records_get

Arguments

Example

#records_merge

Arguments

Example

#records_merge_preview

Arguments

Example

#records_merge_undo

Arguments

Example

#records_merges

Arguments

Example

#records_purge

Arguments

Example

#records_recycle_bin

Arguments

Example

#records_restore

Arguments

Example

#records_unarchive

Arguments

Example

#records_update

Arguments

Example

#records_upsert

Arguments

Example

#records_upsert_batch

Arguments

Example

#`records.history`

#`records_archive`

#`records_changes`

#`records_create`

#`records_delete`

#`records_delete_batch`

#`records_duplicates`

#`records_get`

#`records_merge`

#`records_merge_preview`

#`records_merge_undo`

#`records_merges`

#`records_purge`

#`records_recycle_bin`

#`records_restore`

#`records_unarchive`

#`records_update`

#`records_upsert`

#`records_upsert_batch`