Audience

Store and retrieve contextual information about users in your audience. This data is embedded into your clone's memory, allowing it to personalize responses based on what you know about each user.

List Users

Retrieve a paginated list of all users in your audience.

Endpoint: GET /v3/users

Query parameters:

Parameter	Type	Required	Description
limit	integer	No	Page size (1–1000, default 50)
cursor	string	No	Cursor from previous response's next_cursor
active	boolean	No	Filter by active (true) or revoked (false) status

Example request:

curl "https://api.delphi.ai/v3/users?limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "users": [
    {
      "user_id": "u-123",
      "email": "[e-mail]",
      "name": "Jane Fan",
      "phone_number": "[phone]",
      "tags": ["VIP", "newsletter"],
      "tier": "PUBLIC",
      "active": true,
      "date_joined": "2025-06-15T10:30:00.000Z"
    },
    {
      "user_id": "u-456",
      "email": "[e-mail]",
      "name": "Alex Sub",
      "phone_number": null,
      "tags": [],
      "tier": "INTERNAL",
      "active": true,
      "date_joined": "2025-06-10T08:00:00.000Z"
    }
  ],
  "next_cursor": "2025-06-10T08:00:00.000000+00:00|u-456",
  "has_more": true
}

Response fields:

Field	Type	Description
users	array	List of user objects
next_cursor	string	Pass as cursor to fetch the next page (null when no more results)
has_more	boolean	Whether additional pages exist

User object fields:

Field	Type	Description
user_id	string	UUID of the user
email	string	User's email (may be null)
name	string	Display name (may be null)
phone_number	string	Phone in E.164 format (may be null)
tags	string[]	Tag names applied to this user
tier	string	Access tier: PUBLIC, INTERNAL, or PRIVATE
active	boolean	Whether the user currently has access
date_joined	string	When the user first interacted (ISO 8601)

To page through all results, pass next_cursor from each response as the cursor query parameter until has_more is false. The cursor is opaque — do not parse or construct it manually.

---

Lookup User

Find a user by email or phone number. Returns the user's ID, email and phone if they exist.

Endpoint: POST /v3/users/lookup

Request body:

Field	Type	Required	Description
email	string	No	Email address to look up
phone_number	string	No	Phone number in E.164 format

Exactly one of email or phone_number must be provided.

Example request (by email):

curl -X POST "https://api.delphi.ai/v3/users/lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]"}'

Example request (by phone):

curl -X POST "https://api.delphi.ai/v3/users/lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "[phone]"}'

Example response:

{
  "user_id": "u-123",
  "email": "[e-mail]",
  "phone_number": "[phone]"
}

Response fields:

Field	Type	Description
user_id	string	UUID of the matched user
email	string	User's email (may be null)
phone_number	string	User's phone number (may be null)

Create User Info

Add a piece of information about a user from your audience.

Endpoint: POST /v3/users/{user_id}/info

Path parameters:

Field	Type	Description
user_id	string	UUID of the user

Request body:

Field	Type	Required	Description
info	string	Yes	The information text
info_type	string	Yes	Category of the info (see table below)

Info types:

Value	Description
GOAL	Something the user is trying to achieve
PREFERENCES	User preferences or likes/dislikes
INTERESTS	Topics or areas the user is interested in
PERSONAL_INFO	General personal details
EXPERTISE	Skills or areas of knowledge
SITUATION	Current context or circumstances
BELIEF	Values or beliefs
COMMUNICATION_STYLE	How the user prefers to communicate
EMOTIONAL_STATE	Current emotional context
RELATIONSHIP	How the user relates to you or your work
WHY_DELPHI	Why the user interacts with your clone
HOW_DELPHI	How the user uses your clone
JOURNAL	Freeform notes

Example request:

curl -X POST "https://api.delphi.ai/v3/users/u-123/info" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "Wants to improve their public speaking skills",
    "info_type": "GOAL"
  }'

Example response:

{
  "id": "info-001",
  "text": "Wants to improve their public speaking skills",
  "created_at": "2025-06-15T10:30:00.000Z",
  "updated_at": "2025-06-15T10:30:00.000Z",
  "message_id": null,
  "source": "API",
  "info_type": "GOAL"
}

---

Get User Info

Retrieve all stored information for a user who has interacted with your digital mind.

Endpoint: GET /v3/users/{user_id}/info

Path parameters:

Field	Type	Description
user_id	string	UUID of the user

Example request:

curl "https://api.delphi.ai/v3/users/u-123/info" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "user_id": "u-123",
  "info_items": [
    {
      "id": "info-001",
      "text": "Wants to improve their public speaking skills",
      "created_at": "2025-06-15T10:30:00.000Z",
      "updated_at": "2025-06-15T10:30:00.000Z",
      "message_id": null,
      "source": "API",
      "info_type": "GOAL"
    },
    {
      "id": "info-002",
      "text": "Prefers short, actionable advice",
      "created_at": "2025-06-14T08:00:00.000Z",
      "updated_at": "2025-06-14T08:00:00.000Z",
      "message_id": null,
      "source": "API",
      "info_type": "PREFERENCES"
    }
  ],
  "total_count": 2
}

Items are sorted by newest first.

---

Update User Info

Update a specific piece of information about a user. You can change the text, the info type, or both.

Endpoint: PATCH /v3/users/{user_id}/info/{info_id}

Path parameters:

Field	Type	Description
user_id	string	UUID of the user
info_id	string	ID of the info item to update

Request body:

Field	Type	Required	Description
info	string	No	Updated information text
info_type	string	No	Updated category (see info types in Create User Info)

At least one of info or info_type must be provided.

Example request:

curl -X PATCH "https://api.delphi.ai/v3/users/u-123/info/info-001" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "Wants to improve their public speaking and storytelling skills",
    "info_type": "GOAL"
  }'

Example response:

{
  "id": "info-001",
  "text": "Wants to improve their public speaking and storytelling skills",
  "created_at": "2025-06-15T10:30:00.000Z",
  "updated_at": "2025-06-16T14:22:00.000Z",
  "message_id": null,
  "source": "API",
  "info_type": "GOAL"
}

Response fields:

Field	Type	Description
id	string	ID of the info item
text	string	The updated information text
created_at	string	When the info was originally created (ISO 8601)
updated_at	string	When the info was last updated (ISO 8601)
message_id	string	Associated message ID (may be null)
source	string	Origin of the info (API, MESSAGE, etc.)
info_type	string	Category of the info

The created_at timestamp is preserved from the original record. Only updated_at changes on update.

Delete User Info

Remove a specific piece of information about a user.

Endpoint: DELETE /v3/users/{user_id}/info/{info_id}

Path parameters:

Field	Type	Description
user_id	string	UUID of the user
info_id	string	ID of the info item to delete

Example request:

curl -X DELETE "https://api.delphi.ai/v3/users/u-123/info/info-001" \
  -H "x-api-key: YOUR_API_KEY"

Example response:

{
  "success": true,
  "message": "User info deleted successfully",
  "deleted_info_id": "info-001"
}