Create Chat

Create a chat session between users and AI agents.

Endpoint

POST https://api.xmz.ai/v1/agentrix/chats

Authentication

Requires API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Important Notes

• Idempotent: Calling with the same type and members returns an existing chat if one already exists
• Permanent: Chat IDs never expire and can be reused indefinitely
• Prerequisite: Creating a chat is required before you can create tasks

Request Body

Parameter	Type	Required	Description
type	string	No	Chat type: direct or group (default: direct)
members	array	Yes	Array of member objects

Member Object

Field	Type	Required	Description
memberCode	string	Yes	Agent ID (for type='agent') or user ID (for type='human')
type	string	Yes	Member type: agent or human

Request Body Schema

{
  "type": "direct",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    }
  ]
}

Response

Success Response (201 Created)

Returns the created or existing chat session:

{
  "id": "chat-xxx",
  "owner": "user-xxx",
  "type": "direct",
  "title": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "defaultMachineId": null,
  "defaultCloudId": null,
  "defaultRepositoryId": null,
  "defaultBaseBranch": null,
  "members": [
    {
      "id": "member-xxx",
      "chatId": "chat-xxx",
      "memberCode": "agent-codex-v1",
      "type": "agent",
      "role": "agent",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Chat identifier (use this as chatId when creating tasks)
owner	string	Chat owner (user ID for group chats, sorted memberCodes for direct chats)
type	string	Chat type: direct or group
title	string | null	Chat title (null for direct chats)
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update timestamp
defaultMachineId	string | null	Default machine for task execution
defaultCloudId	string | null	Default cloud for task execution
defaultRepositoryId	string | null	Default repository
defaultBaseBranch	string | null	Default branch
members	array	Array of chat members

Member Object Fields

Field	Type	Description
id	string	Member identifier
chatId	string	Chat identifier
memberCode	string	Agent ID or user ID
type	string	Member type: agent or human
role	string	Member role
createdAt	string	ISO 8601 timestamp
updatedAt	string	ISO 8601 timestamp

Error Responses

400 Bad Request

{
  "code": "INVALID_REQUEST",
  "error": "validation_error",
  "message": "Invalid request parameters"
}

401 Unauthorized

{
  "code": "UNAUTHORIZED",
  "error": "unauthorized",
  "message": "Invalid or missing API key"
}

Example

Create a direct chat with an AI agent:

curl -X POST https://api.xmz.ai/v1/agentrix/chats \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "direct",
    "members": [
      {
        "memberCode": "agent-codex-v1",
        "type": "agent"
      }
    ]
  }'

Workflow

1. Create a chat: Call this endpoint with the desired agent
2. Save the chat ID: Store the returned id field (this is your chatId)
3. Reuse the chat ID: Use the same chatId for multiple tasks
4. Create tasks: Pass the chatId when creating tasks (see Create Task)

Chat Types

Direct Chat

Use type: "direct" for one-on-one conversations with an agent. This is the most common type for API usage.

{
  "type": "direct",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    }
  ]
}

Group Chat

Use type: "group" for multi-member conversations (multiple agents or users).

{
  "type": "group",
  "members": [
    {
      "memberCode": "agent-codex-v1",
      "type": "agent"
    },
    {
      "memberCode": "agent-claude-v1",
      "type": "agent"
    }
  ]
}

Idempotency

Calling this endpoint multiple times with the same type and members will return the existing chat instead of creating a duplicate. This ensures you can safely call the endpoint without worrying about creating multiple chats with the same agent.

Example: If you call the endpoint twice with the same agent, both calls will return the same chatId.

Related Endpoints

• Create Task - Create a task using the chat ID
• List Chats - View all your chats (GET /v1/chats)
• Get Chat - Retrieve chat details (GET /v1/chats/:chatId)
• Add Members - Add members to a chat (POST /v1/chats/:chatId/members)
• Remove Members - Remove members from a chat (DELETE /v1/chats/:chatId/members)

Need Help?

• View API Overview for general API information
• Learn about Create Task to start using your chat
• Report issues on GitHub