Basic information

Property	Value
Base URL	`/api/v3/conversation`
Authentication	API Key with scope `ayeto.conversation`
Rate Limit	Default limits

🔐 Authentication

API Key

All endpoints require an API key with the permission (scope) ayeto.conversation.

Authentication header

uni-api-key: <YOUR_API_KEY>

API key format

The API key has the following format:

ayeto-{64_random_hex_characters}

Example:

ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

Scopes

To use the conversation endpoints, the API key must have one of the following scopes: - ayeto.conversation - specific scope for conversations - * - wildcard scope (access to all endpoints)

Authentication error responses

Error	Description
`API key not provided`	The `uni-api-key` header is missing or empty.
`API key is invalid`	The API key does not exist, is deactivated, or does not have the required scope.

📋 Available Endpoints

Endpoint	Method	Description
`/api/v3/conversation/find`	POST	Search conversations
`/api/v3/conversation/get`	POST	Get a single conversation
`/api/v3/conversation/delete`	POST	Delete a conversation

📤 Response Model - `PublicConversationView`

All endpoints return conversations in this format:

Field	Type	Description
`id`	`UUID`	Unique identifier of the conversation.
`name`	`string`	Conversation name.
`model`	`string`	ID of the LLM model used.
`img_gen_model`	`string`	ID of the image generation model.
`summary`	`string`	Summary of the conversation (if generated).
`organization_id`	`UUID \\| null`	Organization ID (if the conversation is in an organization context).
`assistant_id`	`UUID \\| null`	Assistant ID (if one was used).
`messages`	`BasicLLMMessageView[]`	List of messages in the conversation.
`created`	`ModelMeta`	Creation metadata.
`updated`	`ModelMeta`	Last update metadata.
`accessed`	`ModelMeta`	Last access metadata.

Message Model - `BasicLLMMessageView`

Field	Type	Description
`id`	`UUID`	Unique identifier of the message.
`timestamp`	`integer`	Unix timestamp of message creation (in milliseconds).
`role`	`string`	Message role: `system`, `user`, `assistant`, `tool`, `internal`.
`content`	`string \\| null`	Text content of the message.
`reasoning_content`	`string \\| null`	Reasoning content (if the model supports it).
`model`	`string \\| null`	ID of the model used for this message.
`img_gen`	`ImgGenMessage \\| null`	Generated image data.

ModelMeta

Field	Type	Description
`user_id`	`UUID \\| null`	ID of the user who performed the action.
`timestamp`	`integer`	Unix timestamp of the action (in milliseconds).

🔍 POST /api/v3/conversation/find

Search conversations with support for filtering, sorting, and pagination.

Request Body - `DbParams`

Parameters are passed as JSON in the request body:

Parameter	Type	Required	Description
`sort_key`	`string`	No	Field to sort by (e.g. `updated.timestamp`, `name`).
`sort_order`	`integer`	No	Sort direction: `0` = ASC, `1` = DESC.
`limit_from`	`integer`	No	Starting index for pagination.
`limit_to`	`integer`	No	Ending index for pagination.
`filters`	`array`	No	Array of filters.

Filters

Filters are passed as an array of conditions:

["field", "operator", "value"]

Supported operators

Operator	Description
`==`	Equals
`!=`	Not equals
`<`	Less than
`>`	Greater than
`<=`	Less than or equal
`>=`	Greater than or equal
`regex`	Regular expression

Filter examples

["name", "regex", ".*test.*"]
["model", "==", "gpt-4o"]
["updated.timestamp", ">", 1735815581000]
["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My conversation",
    "model": "gpt-4o",
    "img_gen_model": "dall-e-3",
    "summary": "Discussion about Python programming...",
    "organization_id": null,
    "assistant_id": null,
    "messages": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "timestamp": 1735815581000,
        "role": "user",
        "content": "Hi, how do I write a function in Python?",
        "reasoning_content": null,
        "model": null,
        "img_gen": null
      },
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "timestamp": 1735815582000,
        "role": "assistant",
        "content": "You define a function in Python using the `def` keyword...",
        "reasoning_content": null,
        "model": "gpt-4o",
        "img_gen": null
      }
    ],
    "created": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815580000
    },
    "updated": {
      "user_id": "880e8400-e29b-41d4-a716-446655440003",
      "timestamp": 1735815582000
    },
    "accessed": {
      "user_id": null,
      "timestamp": 0
    }
  }
]

📖 POST /api/v3/conversation/get

Get a single conversation by ID.

Query Parameters

Parameter	Type	Required	Description
`entity_id`	`UUID`	Yes	Conversation ID.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My conversation",
  "model": "gpt-4o",
  "img_gen_model": "dall-e-3",
  "summary": "",
  "organization_id": null,
  "assistant_id": null,
  "messages": [...],
  "created": {...},
  "updated": {...},
  "accessed": {...}
}

🗑️ POST /api/v3/conversation/delete

Delete a conversation by ID.

Query Parameters

Parameter	Type	Required	Description
`entity_id`	`UUID`	Yes	ID of the conversation to delete.

Response

Returns the UUID of the deleted conversation:

"550e8400-e29b-41d4-a716-446655440000"

🔧 cURL Examples

1. Get all conversations

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{}'

2. Get conversations with sorting (newest first)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1
  }'

3. Get conversations with pagination (first 10)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 10
  }'

4. Get conversations with a filter (by model)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["model", "==", "gpt-4o"]]
  }'

5. Get conversations with a filter (by name - regex)

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["name", "regex", ".*Python.*"]]
  }'

6. Get conversations for a specific assistant

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["assistant_id", "==", "123e4567-e89b-12d3-a456-426614174000"]]
  }'

7. Get conversations newer than a specific date

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [["created.timestamp", ">", 1735689600000]]
  }'

8. Combine multiple filters

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_key": "updated.timestamp",
    "sort_order": 1,
    "limit_from": 0,
    "limit_to": 20,
    "filters": [
      ["model", "==", "gpt-4o"],
      ["created.timestamp", ">", 1735689600000]
    ]
  }'

9. Get a single conversation by ID

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/get?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

10. Delete a conversation

curl -X POST "https://beta.ayeto.ai/api/v3/conversation/delete?entity_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json"

11. Verbose curl for debugging

curl -v -X POST "https://beta.ayeto.ai/api/v3/conversation/find" \
  -H "uni-api-key: ayeto-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_from": 0,
    "limit_to": 5
  }'

⚠️ Error states

HTTP Status	Description
`400`	Bad request (invalid parameters, incorrect filter format).
`401`	Invalid or missing API key (`uni-api-key` header).
`403`	Insufficient permissions (the user does not have access to the conversation).
`404`	Conversation not found.
`500`	Internal server error.

Example error response

{
  "detail": "not found, id: 550e8400-e29b-41d4-a716-446655440000"
}

🔄 Notes

Permissions: The user can only see their own conversations (conversations they created).
Filters: Multiple filters in the array are applied as an AND condition.
Pagination: For a large number of conversations, we recommend using limit_from and limit_to.
Sorting: Default sorting is not defined; we recommend explicitly specifying sort_key and sort_order.
Timestamp: All timestamps are in milliseconds (Unix epoch * 1000).

Basic information

🔐 Authentication

API Key

Authentication header

API key format

Scopes

Authentication error responses

📋 Available Endpoints

📤 Response Model - PublicConversationView

Message Model - BasicLLMMessageView

ModelMeta

🔍 POST /api/v3/conversation/find

Request Body - DbParams

Filters

Supported operators

Filter examples

Response

📖 POST /api/v3/conversation/get

Query Parameters

Response

🗑️ POST /api/v3/conversation/delete

Query Parameters

Response

🔧 cURL Examples

1. Get all conversations

2. Get conversations with sorting (newest first)

3. Get conversations with pagination (first 10)

4. Get conversations with a filter (by model)

5. Get conversations with a filter (by name - regex)

6. Get conversations for a specific assistant

7. Get conversations newer than a specific date

8. Combine multiple filters

9. Get a single conversation by ID

10. Delete a conversation

11. Verbose curl for debugging

⚠️ Error states

Example error response

🔄 Notes

📤 Response Model - `PublicConversationView`

Message Model - `BasicLLMMessageView`

Request Body - `DbParams`