API Reference

Agents Chat

Interact with specialized AI personas through the agents chat endpoint. Each persona has unique characteristics, expertise, conversation styles, and can be enhanced with custom training data for domain-specific knowledge.

Download README

POST https://api.lumyx-ai.site/v1/agents/chat/completions

Creates a response using a specific AI persona with specialized knowledge and conversation style.

Billing & Credits

This endpoint requires a positive account balance. Costs are calculated based on token usage and deducted from your account. If your balance is insufficient, you will receive a 402 Payment Required error.

Conversation History & Logging

To save conversation history and use the conversation_id parameter for multi-turn chats, you must enable Detailed Logging in your API Key settings. If disabled, chats are stateless and won't be saved.

Quick Example

Request

curl -X POST https://api.lumyx-ai.site/v1/agents/chat/completions \
  -H "Authorization: Bearer nova_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": 1,
    "messages": [
      {
        "role": "user",
        "content": "Help me optimize this Python function for better performance"
      }
    ],
    "model": "nova_1_1",
    "stream": false
  }'

Request Parameters

Body Parameters

persona_id required integer

ID of the AI persona to use. Must be a valid persona ID. You can get available persona IDs from the /api/v1/personas endpoint. Common examples:

1 - Code Assistant (Programming and software development)
3 - Business Analyst (Business strategy and analysis)
4 - Learning Tutor (Education and skill development)
5 - Research Assistant (Information gathering and analysis)

messages required array

A list of messages comprising the conversation. Each message must have:

role - Either "user" or "assistant"
content - The message content (string for text, array for vision)

Vision Support

For vision-enabled models, the content can be an array containing text and image parts. Images must be provided as base64 encoded strings in data URL format.

model optional string

ID of the base model to use. If not specified, uses the persona's default model. Supports all models from the chat completions endpoint.

temperature optional number

Sampling temperature between 0 and 2. If not specified, uses the persona's default temperature setting.

max_tokens optional integer

Maximum number of tokens to generate. Default is unlimited (model capacity).

stream optional boolean

If set to true, partial message deltas will be sent as Server-Sent Events (SSE). Default is false.

conversation_id optional integer

ID of an existing agents conversation to continue. If not provided, a new conversation will be created.

top_k optional integer

Limits the next token selection to the K most likely tokens.

min_p optional number

Sets a minimum probability threshold for tokens to be considered.

repetition_penalty optional number

Penalizes repeated tokens. Values > 1.0 reduce repetition.

seed optional integer

If specified, acts as a seed for deterministic generation.

stop optional string/array

Up to 4 sequences where the API will stop generating further tokens.

reasoning optional object

Unified reasoning configuration for thinking models. Options:

effort - Reasoning depth: xhigh, high, medium, low, minimal
max_tokens - Maximum tokens for reasoning (Claude, Gemini)
exclude - If true, reasoning is not returned in response
enabled - Enable reasoning with default settings

reasoning_effort optional (legacy) string

Deprecated: Use reasoning.effort instead. Automatically converted.

stream_options optional object

Streaming options. Set include_usage: true to receive token usage in final chunk.

Response Format

Example Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699896916,
  "model": "nova_1_1",
  "context_left": 1998379,
  "context_total": 2000000,
  "persona": {
    "id": 1,
    "name": "Code Assistant",
    "description": "Expert programming assistant for coding, debugging, and development tasks"
  },
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'd be happy to help optimize your Python function! To provide the best recommendations, could you share the specific function you'd like me to review?",
        "tool_calls": null,
        "reasoning_content": null
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 52,
    "total_tokens": 97
  },
  "conversation_id": 462
}

The response format is similar to chat completions with these additional fields:

Additional Response Fields

object string

The object type, always "chat.completion" for agents chat.

persona object

Information about the persona used:

id - Persona numeric identifier
name - Display name of the persona
description - Brief description of expertise

conversation_id integer

ID of the conversation for continuing multi-turn chats.

Available Personas

You can list all available personas using the personas endpoint, or use these common ones:

Code Assistant

Expert programming assistant for coding, debugging, and development tasks.

1

Business Analyst

Professional business consultant for strategy, analysis, and planning.

3

Learning Tutor

Patient tutor for education and skill development.

4

Research Assistant

Thorough researcher for information gathering and analysis.

5

List All Personas

curl -X GET https://api.lumyx-ai.site/v1/personas \
  -H "Authorization: Bearer nova_your_api_key_here"

Using Your Custom Personas

You can create and use your own custom personas through the Lumyx AI interface and access them via API.

Creating Custom Personas

Create your own personas through the web interface:

Visit https://lumyx-ai.site/agents/personas
Click "Create New Persona"
Define the persona's name, description, and system prompt
Add custom training data (optional but recommended)
Set visibility (private or public)
Save and get the persona ID for API use

Finding Your Persona IDs

To use your custom personas via API, you need their numeric IDs. Look for personas with "is_owned": true:

Custom Persona Response

{
  "id": 15,
  "name": "My Marketing Expert",
  "description": "Custom persona for marketing campaigns and social media",
  "category": "Business",
  "is_public": false,
  "is_owned": true,
  "has_training_data": true
}

Chat with Custom Persona

Once you have the persona ID, use it exactly like public personas:

Request

curl -X POST https://api.lumyx-ai.site/v1/agents/chat/completions \
  -H "Authorization: Bearer nova_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": 15,
    "messages": [
      {
        "role": "user",
        "content": "Create a social media campaign for our new product launch"
      }
    ],
    "model": "nova_1_1"
  }'

🔒 Private Personas

Only you can access via API. Perfect for sensitive business data.

🌍 Public Personas

Anyone can access via API. Great for sharing useful personas.

Training Data and Custom Knowledge

Personas can be enhanced with custom training data to provide specialized knowledge. When a persona has training data, it's automatically included in the conversation context.

📝 Text Knowledge

General facts, information, and domain knowledge

❓ Q&A Pairs

Specific question-answer combinations for common scenarios

⭐ Examples

Sample conversations, responses, or behavior patterns

📄 Documents

Reference materials, guidelines, or documentation

Automatic Integration

Training data is automatically injected into the system prompt - no changes needed to your API calls!

Training Data Management

You can programmatically manage training data for your personas using dedicated API endpoints:

GET /api/v1/personas/{id}/training-data

Retrieve all training data for a specific persona.

Get Training Data

curl -X GET https://api.lumyx-ai.site/v1/personas/123/training-data \
  -H "Authorization: Bearer nova_your_api_key_here"

POST /api/v1/personas/{id}/training-data

Add new training data to a persona (only for personas you own).

Add Training Data

curl -X POST https://api.lumyx-ai.site/v1/personas/123/training-data \
  -H "Authorization: Bearer nova_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "text",
    "title": "React Hooks Knowledge",
    "content": "React Hooks are functions that let you use state and other React features in functional components..."
  }'

Request Parameters:

type - Required. One of: text, qa_pair, example, document, knowledge
title - Optional. Title for the training data
content - Required. The training content (max 10,000 characters)
metadata - Optional. Additional data (for Q&A pairs: {"question": "..."})

PUT /api/v1/personas/{id}/training-data/{dataId}

Update existing training data.

DELETE /api/v1/personas/{id}/training-data/{dataId}

Delete training data from a persona.

Streaming Responses

Enable streaming to receive response tokens as they're generated:

Streaming Request

curl -X POST https://api.lumyx-ai.site/v1/agents/chat/completions \
  -H "Authorization: Bearer nova_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": 1,
    "messages": [{"role": "user", "content": "Explain async/await in JavaScript"}],
    "stream": true
  }'

        Streaming Response Chunks
    
        data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699896916,"model":"nova_1_1","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699896916,"model":"nova_1_1","choices":[{"index":0,"delta":{"content":"Async"},"finish_reason":null}]}

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1699896916,"model":"nova_1_1","choices":[{"index":0,"delta":{"content":"/await"},"finish_reason":null}]}

data: [DONE]

Error Responses

Status Code	Description
`400 Bad Request`	Missing or invalid parameters
`401 Unauthorized`	Invalid or missing API key
`404 Not Found`	Persona not found or inaccessible
`429 Too Many Requests`	Rate limit exceeded
`500 Server Error`	Internal server error

For detailed error handling guidance, see the error handling documentation.