Bulk upsert objects (server token only)

POST

/v1/batch/objects

curl --request POST \
  --url http://localhost:3000/v1/batch/objects \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "objects": [ { "type": "example", "id": "example", "custom": {} } ] }'

Cold-start import. Partial failure is still a 200 — check each item’s ok. Re-running is safe: upsert is idempotent.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

objects

required

Array<object>

>= 1 items <= 100 items

object

type

required

string

id

required

string

custom

required

object

key

additional properties

any

Example^generated

{
  "objects": [
    {
      "type": "example",
      "id": "example",
      "custom": {}
    }
  ]
}

Responses

200

Envelope accepted. Per-item results, ordered and same-length as the input; a failed item never rolls back the rest.

Media typeapplication/json

object

results

required

Array<object>

object

index

required

integer

ok

required

boolean

id

Present when ok for users/activities

string

code

§8 error code, present when not ok

string

Example^generated

{
  "results": [
    {
      "index": 1,
      "ok": true,
      "id": "example",
      "code": "example"
    }
  ]
}

400

Envelope invalid (0 items, more than 100 items, or malformed shape).

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

403

Authenticated but not permitted.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

429

Batch rate limit exceeded. Batch routes charge a separate 600 requests/min window per tenant — never the normal tenant limit.

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

Headers

Retry-After

integer