Bulk Operations

Perform batch updates, add or remove relations on multiple records in a single API call.

The bulk endpoint lets you apply the same operation to multiple records at once. It supports field updates and relation management, with per-record permission checks.

Bulk Operation

POST /api/v1/bulk

Request Body

{
  "action": "update_field",
  "object_name": "contacts",
  "record_ids": ["id-1", "id-2", "id-3"],
  "field_name": "status",
  "field_value": "qualified"
}

Actions

Action	Description	Extra Fields
`update_field`	Set a field value on all specified records	`field_name`, `field_value`
`add_relation`	Add related records to a relation field	`relation_field`, `target_ids`
`remove_relation`	Remove related records from a relation field	`relation_field`, `target_ids`

Common Fields

Field	Type	Required	Description
`action`	string	Yes	One of `update_field`, `add_relation`, `remove_relation`
`object_name`	string	Yes	The object to operate on (e.g. `contacts`, `companies`)
`record_ids`	UUID[]	Yes	Array of record IDs to modify

Action-Specific Fields

update_field:

Field	Type	Description
`field_name`	string	The field to update
`field_value`	any	The new value to set

add_relation / remove_relation:

Field	Type	Description
`relation_field`	string	The relation field name
`target_ids`	UUID[]	IDs of related records to add or remove

Examples

Update a Field

Set the owner field on three contacts:

curl -X POST "https://kasar.app/api/v1/bulk" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_field",
    "object_name": "contacts",
    "record_ids": [
      "550e8400-e29b-41d4-a716-446655440000",
      "660f9511-f3ac-52e5-b827-557766551111",
      "770a0622-a4bd-63f6-c938-668877662222"
    ],
    "field_name": "owner",
    "field_value": "alice-workspace-id"
  }'

Add Relations

Link two tags to multiple opportunities:

curl -X POST "https://kasar.app/api/v1/bulk" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_relation",
    "object_name": "opportunities",
    "record_ids": ["opp-id-1", "opp-id-2"],
    "relation_field": "tags",
    "target_ids": ["tag-id-1", "tag-id-2"]
  }'

Remove Relations

curl -X POST "https://kasar.app/api/v1/bulk" \
  -H "Authorization: Bearer ksr_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "remove_relation",
    "object_name": "contacts",
    "record_ids": ["contact-id-1", "contact-id-2"],
    "relation_field": "tags",
    "target_ids": ["tag-id-1"]
  }'

Response

The response shape depends on the action performed.

update_field:

{
  "action": "update_field",
  "updated": 3,
  "failed": 0,
  "total": 3
}

add_relation:

{
  "action": "add_relation",
  "added": 4,
  "failed": 0,
  "total": 4
}

remove_relation:

{
  "action": "remove_relation",
  "removed": 2,
  "failed": 0,
  "total": 2
}

Partial Failures

If some records fail (for example, due to permission checks), the response includes an errors array:

{
  "action": "update_field",
  "updated": 2,
  "failed": 1,
  "errors": [
    {
      "record_id": "770a0622-...",
      "code": "PERMISSION_DENIED",
      "message": "You do not have permission to update this record"
    }
  ],
  "total": 3
}

RBAC checks are performed per record. If the user lacks permission on a specific record, that record fails but the rest of the batch proceeds.

Error Responses

Status	Code	Description
400	`INVALID_OBJECT`	The object name does not exist
400	`VALIDATION_ERROR`	Invalid action, missing required fields, or invalid field value
403	`PERMISSION_DENIED`	Token lacks permission for bulk operations

Bulk Operations

On this page