[ STEP 03 / INTEGRATION ]

End Users

apiv0.1.0sdk@assistiv/sdk@0.2.0

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.

typescript

import { Assistiv } from "@assistiv/sdk";

const platform = new Assistiv({ apiKey: process.env.ASSISTIV_PLATFORM_KEY! });

// Paginated list
const page1 = await platform.endUsers(platformId).list({ page: 1, limit: 20 });

// Look up by your stable external_id (returns standard list shape)
const lookup = await platform.endUsers(platformId).list({ q: "user-123" });

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.

typescript

import { Assistiv } from "@assistiv/sdk";

const platform = new Assistiv({ apiKey: process.env.ASSISTIV_PLATFORM_KEY! });

const user = await platform.endUsers(platformId).create({
  external_id: "user-123",
  display_name: "Jane Smith",
  metadata: { plan: "pro" },
});

// raw_key is returned ONCE — store it now.
const endUserKey = user.api_key.raw_key;

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.

typescript

const user = await platform.endUsers(platformId).get(endUserId);

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.

typescript

const updated = await platform.endUsers(platformId).update(endUserId, {
  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.

typescript

await platform.endUsers(platformId).delete(endUserId);
// Cascades to api_keys, budgets, rate-limit overrides, MCP connections.