Users API
Manage end-users within your tenant.
Overview
Users represent the end-users of your application. Each user has isolated memory storage and can have multiple conversations. The external_ref field allows you to link Raven users to your own user system.
Endpoints
POST
/api/v1/usersCreate a new user for your tenant
users:write
GET
/api/v1/usersList all users for your tenant
users:read
GET
/api/v1/users/:user_idGet a specific user by ID
users:read
PATCH
/api/v1/users/:user_idUpdate user details
users:write
Create User
Create a new user entry for your end-user.
Request
POST /api/v1/usersbash
curl -X POST http://localhost:3000/api/v1/users \
-H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"external_ref": "user-123",
"display_name": "John Doe",
"metadata": {
"plan": "pro",
"source": "web"
}
}'Parameters
| Field | Type | Required | Description |
|---|---|---|---|
external_ref | string | No | Your system's user identifier |
display_name | string | No | Human-readable name |
metadata | object | No | Custom metadata for your use |
Response
Response (201 Created)json
{
"user_id": "usr_abc123xyz",
"tenant_id": "ten_xxxxxxxx",
"external_ref": "user-123",
"display_name": "John Doe",
"metadata": {
"plan": "pro",
"source": "web"
},
"created_at": "2024-01-15T10:30:00Z"
}List Users
Retrieve all users for your tenant with pagination.
GET /api/v1/usersbash
curl -X GET "http://localhost:3000/api/v1/users?limit=20&offset=0" \
-H "Authorization: Bearer rk_live_xxxxxxxxxxxx"Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | number | 20 | Max results per page |
offset | number | 0 | Number of records to skip |
external_ref | string | - | Filter by external reference |
Response (200 OK)json
{
"users": [
{
"user_id": "usr_abc123xyz",
"tenant_id": "ten_xxxxxxxx",
"external_ref": "user-123",
"display_name": "John Doe",
"created_at": "2024-01-15T10:30:00Z"
},
{
"user_id": "usr_def456uvw",
"tenant_id": "ten_xxxxxxxx",
"external_ref": "user-456",
"display_name": "Jane Smith",
"created_at": "2024-01-14T09:15:00Z"
}
],
"total": 42,
"limit": 20,
"offset": 0
}Get User
Retrieve details for a specific user.
GET /api/v1/users/:user_idbash
curl -X GET http://localhost:3000/api/v1/users/usr_abc123xyz \
-H "Authorization: Bearer rk_live_xxxxxxxxxxxx"Response (200 OK)json
{
"user_id": "usr_abc123xyz",
"tenant_id": "ten_xxxxxxxx",
"external_ref": "user-123",
"display_name": "John Doe",
"metadata": {
"plan": "pro",
"source": "web"
},
"conversation_count": 5,
"created_at": "2024-01-15T10:30:00Z"
}Update User
Update user details. Only provided fields will be updated.
PATCH /api/v1/users/:user_idbash
curl -X PATCH http://localhost:3000/api/v1/users/usr_abc123xyz \
-H "Authorization: Bearer rk_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"display_name": "John D.",
"metadata": {
"plan": "enterprise"
}
}'Response (200 OK)json
{
"user_id": "usr_abc123xyz",
"tenant_id": "ten_xxxxxxxx",
"external_ref": "user-123",
"display_name": "John D.",
"metadata": {
"plan": "enterprise"
},
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-16T14:20:00Z"
}User Object
User Schematypescript
interface TenantUser {
user_id: string; // 'usr_xxx' - Raven user ID
tenant_id: string; // Parent tenant ID
external_ref?: string; // Your system's user ID
display_name?: string; // Human-readable name
metadata?: Record<string, unknown>; // Custom data
created_at: string; // ISO 8601 timestamp
updated_at?: string; // Last update timestamp
}