List users across all tenants.

GET

/users

const url = 'https://shiftagent.example.com/users?limit=20&status=active';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://shiftagent.example.com/users?limit=20&status=active' \
  --header 'Authorization: Bearer <token>'

Cross-tenant listing over the key’s whole subtree — each user shows its tenant_id. Filter with ?tenant_id=, ?email= (exact match), or ?status=. Serves integration-wide reconciliation sweeps and support tooling.

Authorizations

integrationKey

Parameters

Query Parameters

limit

integer

default: 20 >= 1 <= 100

Page size (1–100).

starting_after

string

Cursor: return items after this object ID (forward pagination). Use the id of the last item of the previous page.

ending_before

string

Cursor: return items before this object ID (backward pagination). Mutually exclusive with starting_after.

tenant_id

string

/^tnt_[A-Za-z0-9]+$/

Restrict to one tenant.

email

string format: email

Exact-match filter on email.

status

string

Allowed values: active suspended

Filter by user status.

Responses

200

A page of users.

application/json

object

object

required

Envelope discriminator.

string

Allowed value: list

data

required

The page of items.

Array

has_more

required

Whether more items exist beyond this page.

boolean

next_cursor

Opaque cursor for the next page (pass as starting_after). Null when has_more is false.

string | null

data

required

Array<object>

A host-system end user within one tenant. Effective skills = union over assigned roles of each role’s resolved skills.

object

object

required

string

Allowed value: user

required

string

/^usr_[A-Za-z0-9]+$/

tenant_id

required

string

/^tnt_[A-Za-z0-9]+$/

external_id

required

Host system’s user ID (namespaced by the adapter). Unique per tenant; natural key for upsertUserByExternalId.

string

<= 255 characters

email

required

Optional profile field — enrichable after creation.

string | null format: email

display_name

required

Optional profile field — enrichable after creation.

string | null

<= 255 characters

status

required

suspended (deactivated) users fail token exchange and cannot start conversations; they are never auto re-provisioned by upsert.

string

Allowed values: active suspended

role_ids

required

Assigned roles (also manageable via assignUserRole).

Array<string>

default_repository_id

required

Per-user repository override in the resolution cascade.

string | null

/^rep_[A-Za-z0-9]+$/

storage

required

S3-style storage bucket attached to a user or conversation. Platform-assigned automatically at creation; host-owned buckets can be linked via update (provider: "external").

object

provider

required

platform — bucket provisioned and owned by the deployment; external — host-linked BYO bucket.

string

Allowed values: platform external

bucket_uri

required

S3-style URI of the bucket root (e.g. s3://bucket/prefix).

string

metadata

required

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object

<= 50 properties

key

additional properties

string

<= 500 characters

created_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

updated_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

Example

{
  "object": "list",
  "data": [
    {
      "object": "user",
      "status": "active",
      "storage": {
        "provider": "platform"
      }
    }
  ]
}

400

Bad request — malformed body/parameters or an invalid parameter combination (e.g. neither or both of user_id/tenant_id on listConversations, or both pagination cursors).

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

bad_request

Invalid parameter combination

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Invalid request",
  "status": 400,
  "detail": "Exactly one of user_id or tenant_id is required.",
  "request_id": "req_01hzx8bad001"
}

401

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}