Create Task

Start a new task with AI agents to execute your requirements.

Endpoint

POST https://api.xmz.ai/v1/agentrix/tasks/start

Authentication

Requires API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Prerequisites

Before creating a task, you must first create a chat session. The chat provides the context and agent for task execution. See Create Chat for details.

Execution Modes

Tasks can be executed in three modes:

1. Cloud Mode: Task runs on Agentrix cloud infrastructure (requires cloudId + message)
2. Local Mode: Task runs on your local machine (requires machineId + encryptedMessage + dataEncryptionKey)
3. Sub-task Mode: Task inherits execution context from parent task (requires parentTaskId)

Request Body

Core Required Field

Parameter	Type	Required	Description
chatId	string	Yes	Chat identifier (see Create Chat)

Execution Mode (choose one)

Cloud Mode

Parameter	Type	Required	Description
cloudId	string	Yes*	Cloud cluster identifier
message	object	Yes*	User message with role and content

Local Mode

Parameter	Type	Required	Description
machineId	string	Yes*	Local machine identifier
encryptedMessage	string	Yes*	Base64 encrypted message payload
dataEncryptionKey	string	Yes*	Base64 encryption key
cwd	string	No	Working directory
forceUserCwd	boolean	No	Force use of user cwd (no worktree)

Sub-task Mode

Parameter	Type	Required	Description
parentTaskId	string	Yes*	Parent task ID (inherits execution context)

*One execution mode is required

Optional Configuration

Parameter	Type	Description
customTitle	string	Custom task title (1-200 characters)
agentId	string	Specific agent ID (defaults to first chat agent)
repositoryId	string	Associated repository identifier
baseBranch	string	Git branch name
repositorySourceType	string	Repository source type: temporary, directory, or git-server

Response

Success Response (201 Created)

{
  "taskId": "task-xxx",
  "chatId": "chat-xxx",
  "agentId": "agent-xxx",
  "userId": "user-xxx",
  "state": "pending",
  "machineId": null,
  "cloudId": "cloud-xxx",
  "repositoryId": null,
  "baseBranch": null,
  "title": null,
  "customTitle": "My Task",
  "userCwd": null,
  "forceUserCwd": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Response Fields

Field	Type	Description
taskId	string	Unique task identifier
chatId	string	Chat identifier
agentId	string	Agent identifier executing the task
userId	string	User identifier who created the task
state	string	Task state (e.g., pending, running, completed)
machineId	string | null	Machine ID (if local mode)
cloudId	string | null	Cloud ID (if cloud mode)
repositoryId	string | null	Repository ID
baseBranch	string | null	Git branch name
title	string | null	Auto-generated task title
customTitle	string | null	User-provided custom title
userCwd	string | null	Working directory
forceUserCwd	boolean | null	Force user cwd flag
createdAt	string	ISO 8601 creation timestamp
updatedAt	string	ISO 8601 last update 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"
}

404 Not Found

{
  "code": "CHAT_NOT_FOUND",
  "error": "not_found",
  "message": "Chat not found"
}

Examples

Example 1: Cloud Mode Task

Create a task that runs on cloud infrastructure with a repository context:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "cloudId": "cloud-xxx",
    "message": {
      "role": "user",
      "content": "Fix the authentication bug in login.ts"
    },
    "customTitle": "Fix login bug",
    "repositoryId": "repo-xxx",
    "baseBranch": "develop"
  }'

Example 2: Sub-task Mode

Create a child task that inherits execution context from a parent task:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "parentTaskId": "task-parent-xxx",
    "message": {
      "role": "user",
      "content": "Add unit tests for the fixed code"
    },
    "customTitle": "Add tests"
  }'

Example 3: Simple Cloud Task

Create a basic task without repository context:

curl -X POST https://api.xmz.ai/v1/agentrix/tasks/start \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-xxx",
    "cloudId": "cloud-xxx",
    "message": {
      "role": "user",
      "content": "Explain how async/await works in JavaScript"
    }
  }'

Workflow

1. Create a chat (prerequisite): Use Create Chat to establish a chat session
2. Save the chatId: Store the returned chat ID for use in task creation
3. Create a task: Call this endpoint with the chatId and execution mode
4. Save the taskId: Store the returned task ID for monitoring progress
5. Monitor progress: Use WebSocket or polling to track task status

Related Endpoints

• Create Chat - Required prerequisite for creating tasks
• Create Share Link - Share task results with others
• List Tasks - View all your tasks (GET /v1/tasks)
• Resume Task - Continue a paused task (POST /v1/tasks/:taskId/resume)
• Cancel Task - Cancel a running task (POST /v1/tasks/:taskId/cancel)
• Stop Task - Stop task execution (POST /v1/tasks/:taskId/stop)

Need Help?

• View API Overview for general API information
• Learn about Create Chat for chat setup
• Report issues on GitHub