End Users

End users are the people using your platform. Each end user gets their own API key, optional budget, and MCP tool connections. Identified by an external_id that you define.

GET/v1/platforms/{platformId}/end-users

Returns a paginated list of end users for the platform.

Auth: Platform key.

Query Parameters

Name	Type	Required	Description
page	integer	Optional	Page number.Default: `1`
limit	integer	Optional	Items per page. Max 100.Default: `20`
external_id	string	Optional	Filter to a single user by your stable ID. Returns the standard list shape (or empty list if not found). Cheaper than scanning pages.

bash

# List all end users
curl "https://api.assistiv.ai/v1/platforms/{platformId}/end-users?page=1&limit=20" \
  -H "Authorization: Bearer sk-plat_your_key"

# Look up by external_id
curl "https://api.assistiv.ai/v1/platforms/{platformId}/end-users?external_id=user-123" \
  -H "Authorization: Bearer sk-plat_your_key"

json

{
  "data": [
    {
      "id": "uuid",
      "platform_id": "uuid",
      "external_id": "user-123",
      "display_name": "Jane Smith",
      "metadata": { "plan": "pro"},
      "is_active": true,
      "created_at": "2026-04-08T10:30:00Z",
      "updated_at": "2026-04-08T10:30:00Z"}
  ],
  "total": 42,
  "page": 1,
  "limit": 20
}

POST/v1/platforms/{platformId}/end-users

Creates a new end user with an auto-generated API key.

Auth: Platform key.

Request Body

Name	Type	Required	Description
external_id	string	Required	Your unique identifier for this user. 1-255 chars. Must be unique per platform.
display_name	string	Optional	Human-readable name. 1-100 chars.
metadata	object	Optional	Arbitrary JSON metadata to attach to the user.

⚠raw_key shown once

api_key.raw_key is only returned in this response. Store it in your database immediately.

ℹIdempotent on external_id

First call returns 201 Created with a new user + key. Repeat calls with the same external_id return 200 OK with the existing user + a fresh key. This exists for retry safety — not as a key-retrieval mechanism. Store the key once, reuse forever.

ℹAuto-budget

If the platform has settings.default_budget_usd configured, a monthly budget is auto-created and returned as budget. An opening ledger row is written so GET /budget/transactions shows full history from minute zero.

bash

curl -X POST https://api.assistiv.ai/v1/platforms/{platformId}/end-users \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user-123",
    "display_name": "Jane Smith",
    "metadata": { "plan": "pro" }
  }'

json

{
  "id": "uuid",
  "platform_id": "uuid",
  "external_id": "user-123",
  "display_name": "Jane Smith",
  "metadata": { "plan": "pro"},
  "is_active": true,
  "created_at": "2026-04-08T10:30:00Z",
  "updated_at": "2026-04-08T10:30:00Z",
  "api_key": {
    "id": "uuid",
    "platform_id": "uuid",
    "end_user_id": "uuid",
    "key_prefix": "sk-eu_10",
    "name": "Default key",
    "scopes": ["inference"],
    "is_active": true,
    "created_at": "2026-04-08T10:30:00Z",
    "raw_key": "sk-eu_103c5bb1fd2bd35d..."},
  "budget": null
}

GET/v1/platforms/{platformId}/end-users/{endUserId}

Retrieves an end user by ID.

Auth: Platform key.

bash

curl https://api.assistiv.ai/v1/platforms/{platformId}/end-users/{endUserId} \
  -H "Authorization: Bearer sk-plat_your_key"

PATCH/v1/platforms/{platformId}/end-users/{endUserId}

Updates an end user's properties.

Auth: Platform key.

Request Body (all optional)

Name	Type	Required	Description
display_name	string	Optional	Updated display name.
metadata	object	Optional	Updated metadata. Replaces the stored object entirely (no deep merge).
is_active	boolean	Optional	Activate or deactivate the end user.

bash

curl -X PATCH https://api.assistiv.ai/v1/platforms/{platformId}/end-users/{endUserId} \
  -H "Authorization: Bearer sk-plat_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Jane D. Smith",
    "metadata": { "plan": "enterprise" },
    "is_active": true
  }'

DELETE/v1/platforms/{platformId}/end-users/{endUserId}

Permanently deletes an end user. Cascades to their API keys, budgets, rate-limit overrides, and MCP connections.

Auth: Platform key. Returns 204 No Content.

bash

curl -X DELETE https://api.assistiv.ai/v1/platforms/{platformId}/end-users/{endUserId} \
  -H "Authorization: Bearer sk-plat_your_key"