v1 users

Create a new user or return existing user

Create a new user in the UPL system or return existing user.

This endpoint:
- Validates authentication tokens
- Creates a new user with unique email OR returns existing user if email already exists
- Returns user details upon successful creation or retrieval
- Uses "create or get" pattern for idempotent behavior

**Authentication**: Requires valid API key or JWT token in Authorization header

post/v1/users

Request body

emailstring required

User's email address

namestring required

User's full name

org_user_idstring nullable

Organization-specific user ID

persona_idstring nullable

If provided, the new user is automatically linked to this persona (cloning its knowledge graph).

Example request

{
  "email": "user@example.com",
  "name": "John Doe",
  "org_user_id": "org_123456"
}

Response

Successful Response

user_idstring required

Generated user ID

emailstring required

User's email address

namestring required

User's name

org_user_idstring nullable

Organization-specific user ID

created_atstring required

User creation timestamp

successboolean

Whether the user was created successfully

Example response

{
  "created_at": "2024-01-01T00:00:00Z",
  "email": "user@example.com",
  "name": "John Doe",
  "org_user_id": "org_123456",
  "success": true,
  "user_id": "123e4567-e89b-12d3-a456-426614174000"
}

Changes

Changed in 3 of the 29 revisions of this API.12

Mar 23, 202627701839a0701See the full diff
- ○
  added the new optional request property persona_id
  new-optional-request-property
Dec 10, 20255a9a6b9cb07a9See the full diff
- ○
  added the optional property details to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 401 status
  response-optional-property-added
- ○
  added the optional property details to the response with the 500 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 400 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 401 status
  response-optional-property-added
- ○
  added the optional property request_id to the response with the 500 status
  response-optional-property-added
- ○
  added the required property error_code to the response with the 400 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 401 status
  response-required-property-added
- ○
  added the required property error_code to the response with the 500 status
  response-required-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Nov 17, 202593aa65273d4d2See the full diff
- ○
  api tag v1 users added
  api-tag-added
- ○
  api tag v1 main removed
  api-tag-removed
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history