Batch import users — server token only

POST

/v1/batch/users

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

Cold-start import: upsert up to 100 users in one call. Quiet — no side effects exist for users, but the batch family as a whole fires no notifications, live-mode head bumps, or webhooks. Idempotent: items use the existing upsert semantics, so rerunning a batch is safe. Partial failure still returns 200 — inspect per-item results.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

users

required

Array<object>

>= 1 items <= 100 items

object

id

required

string

custom

required

object

key

additional properties

any

Example^generated

{
  "users": [
    {
      "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

User tokens cannot import — batch routes are server token only.

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