Skip to main content

​
Task Management

Submit tasks to agents, monitor their progress, and retrieve results.

​
Submit Task

Submit a new task to an agent.

​
Endpoint

POST /agent/request/:id

​
Authentication

Requires JWT token or Platform API key.

​
Path Parameters

ParameterTypeDescription
idstringAgent UUID

​
Request Body

FieldTypeRequiredDescription
messagestringYesTask description/instructions
prioritynumberNoPriority level 1-10 (default: 5)
timeout_overridenumberNoOverride default timeout (seconds)
metadataobjectNoCustom metadata
callback_modestringNoResult delivery: poll or webhook (default: poll)
webhook_urlstringConditionalRequired if callback_mode is webhook

​
Example Request

curl -X POST https://api.app.shinzo.ai/agent/request/agt_abc123def456 \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review the code in /workspace/src and provide feedback",
    "priority": 7,
    "metadata": {
      "project": "frontend-app"
    }
  }'

​
Response

{
  "task_id": "tsk_xyz789abc123",
  "status": "queued",
  "created_at": "2025-01-20T10:00:00Z",
  "estimated_start": "2025-01-20T10:00:05Z",
  "poll_url": "https://api.app.shinzo.ai/agent/agt_abc123def456/task/tsk_xyz789abc123",
  "cancel_url": "https://api.app.shinzo.ai/agent/agt_abc123def456/task/tsk_xyz789abc123/cancel"
}

​
Status Codes

CodeDescription
202Task accepted and queued
400Invalid request
401Invalid authentication
404Agent not found
503Agent unavailable (paused, stopped, or error state)

​
Get Task Status

Get the current status and results of a task.

​
Endpoint

GET /agent/:id/task/:taskId

​
Authentication

Requires JWT token or Platform API key.

​
Path Parameters

ParameterTypeDescription
idstringAgent UUID
taskIdstringTask UUID

​
Example Request

curl -X GET https://api.app.shinzo.ai/agent/agt_abc123def456/task/tsk_xyz789abc123 \
  -H "Authorization: Bearer <jwt_token>"

​
Response (Running)

{
  "task_id": "tsk_xyz789abc123",
  "status": "running",
  "created_at": "2025-01-20T10:00:00Z",
  "started_at": "2025-01-20T10:00:05Z",
  "progress": {
    "current_step": "Analyzing code structure",
    "steps_completed": 2,
    "total_steps": 5
  }
}

​
Response (Completed)

{
  "task_id": "tsk_xyz789abc123",
  "status": "completed",
  "created_at": "2025-01-20T10:00:00Z",
  "started_at": "2025-01-20T10:00:05Z",
  "completed_at": "2025-01-20T10:02:30Z",
  "result": {
    "summary": "Code review completed successfully",
    "findings": [
      {
        "file": "src/utils.js",
        "line": 42,
        "severity": "warning",
        "message": "Consider using optional chaining here"
      }
    ]
  }
}

​
Task States

StateDescription
queuedWaiting to start
runningCurrently executing
awaiting_inputNeeds user input
completedFinished successfully
failedEncountered an error
cancelledCancelled by user

​
Send Message to Task

Send a message or input to a running task (useful when task is awaiting_input).

​
Endpoint

POST /agent/:id/task/:taskId/message

​
Authentication

Requires JWT token or Platform API key.

​
Request Body

FieldTypeRequiredDescription
messagestringYesMessage to send to the task

​
Example Request

curl -X POST https://api.app.shinzo.ai/agent/agt_abc123def456/task/tsk_xyz789abc123/message \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"message": "Yes, proceed with the refactoring"}'

​
Response

{
  "task_id": "tsk_xyz789abc123",
  "status": "running",
  "message_received": true
}

​
Cancel Task

Cancel a running or queued task.

​
Endpoint

POST /agent/:id/task/:taskId/cancel

​
Authentication

Requires JWT token or Platform API key.

​
Example Request

curl -X POST https://api.app.shinzo.ai/agent/agt_abc123def456/task/tsk_xyz789abc123/cancel \
  -H "Authorization: Bearer <jwt_token>"

​
Response

{
  "task_id": "tsk_xyz789abc123",
  "status": "cancelled",
  "cancelled_at": "2025-01-20T10:01:00Z"
}

​
Status Codes

CodeDescription
200Task cancelled successfully
400Task cannot be cancelled (already completed/failed)
404Task not found