Kubiya LogoKubiya Developer Docs

Tasks API

API endpoints for managing tasks in the Kubiya platform

Tasks API

The Tasks API allows you to manage tasks in your organization, including creating, monitoring, and controlling task execution. Tasks represent units of work that can be executed by runners and agents.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

Endpoints

MethodPathDescription
GET/api/v1/tasksList all tasks
GET/api/v1/tasks/{taskId}Get task details
POST/api/v1/tasksCreate a new task
PUT/api/v1/tasks/{taskId}/cancelCancel a task
GET/api/v1/tasks/{taskId}/logsGet task logs
GET/api/v1/tasks/{taskId}/statusGet task status
GET/api/v1/tasks/agent/{agentId}List tasks for an agent
GET/api/v1/tasks/runner/{runnerId}List tasks for a runner

Common Response Status Codes

Status CodeDescription
200Success
400Bad Request - Invalid parameters or request body
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
500Internal Server Error

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

List Tasks

Retrieve all tasks in your organization.

GET /api/v1/tasks

Query Parameters

NameTypeRequiredDescription
statusstringNoFilter by task status
agentstringNoFilter by agent ID
runnerstringNoFilter by runner ID
limitintegerNoMaximum number of tasks to return (default: 50)
pageintegerNoPage number for pagination
sortstringNoSort by field (created_at, updated_at, status)
orderstringNoSort order (asc, desc)

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "id": "task-123",
    "name": "Deploy Application",
    "description": "Deploy application to production environment",
    "status": "running",
    "progress": 75,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:15:00Z",
    "started_at": "2023-01-01T00:00:00Z",
    "completed_at": null,
    "agent_id": "agent-456",
    "runner_id": "runner-789",
    "metadata": {
      "environment": "production",
      "version": "1.2.0",
      "priority": "high"
    }
  }
]

Get Task Details

Retrieve details for a specific task.

GET /api/v1/tasks/{taskId}

Path Parameters

NameTypeRequiredDescription
taskIdstringYesID of the task

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "id": "task-123",
  "name": "Deploy Application",
  "description": "Deploy application to production environment",
  "status": "running",
  "progress": 75,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:15:00Z",
  "started_at": "2023-01-01T00:00:00Z",
  "completed_at": null,
  "agent_id": "agent-456",
  "runner_id": "runner-789",
  "metadata": {
    "environment": "production",
    "version": "1.2.0",
    "priority": "high"
  },
  "result": {
    "output": {},
    "error": null
  }
}

Create Task

Create a new task.

POST /api/v1/tasks

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Request Body

{
  "name": "Deploy Application",
  "description": "Deploy application to production environment",
  "agent_id": "agent-456",
  "runner_id": "runner-789",
  "metadata": {
    "environment": "production",
    "version": "1.2.0",
    "priority": "high"
  },
  "parameters": {
    "app_name": "my-app",
    "deploy_strategy": "rolling"
  }
}

Required Fields

  • name: Name of the task
  • agent_id: ID of the agent to execute the task
  • runner_id: ID of the runner to use

Response

{
  "id": "task-123",
  "name": "Deploy Application",
  "description": "Deploy application to production environment",
  "status": "pending",
  "progress": 0,
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "started_at": null,
  "completed_at": null,
  "agent_id": "agent-456",
  "runner_id": "runner-789",
  "metadata": {
    "environment": "production",
    "version": "1.2.0",
    "priority": "high"
  }
}

Cancel Task

Cancel a running task.

PUT /api/v1/tasks/{taskId}/cancel

Path Parameters

NameTypeRequiredDescription
taskIdstringYesID of the task to cancel

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "id": "task-123",
  "status": "cancelled",
  "cancelled_at": "2023-01-01T00:30:00Z",
  "cancelled_by": "user@example.com"
}

Get Task Logs

Retrieve logs for a specific task.

GET /api/v1/tasks/{taskId}/logs

Path Parameters

NameTypeRequiredDescription
taskIdstringYesID of the task

Query Parameters

NameTypeRequiredDescription
start_timestringNoFilter logs after this timestamp
end_timestringNoFilter logs before this timestamp
levelstringNoFilter by log level (info, error, debug)
limitintegerNoMaximum number of log entries to return

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "task_id": "task-123",
  "logs": [
    {
      "timestamp": "2023-01-01T00:00:00Z",
      "level": "info",
      "message": "Task started",
      "metadata": {
        "component": "runner",
        "step": "initialization"
      }
    },
    {
      "timestamp": "2023-01-01T00:15:00Z",
      "level": "error",
      "message": "Failed to connect to database",
      "metadata": {
        "component": "database",
        "error_code": "DB001"
      }
    }
  ]
}

Get Task Status

Get the current status of a task.

GET /api/v1/tasks/{taskId}/status

Path Parameters

NameTypeRequiredDescription
taskIdstringYesID of the task

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "id": "task-123",
  "status": "running",
  "progress": 75,
  "started_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:15:00Z",
  "metadata": {
    "current_step": "deploying",
    "steps_completed": 3,
    "total_steps": 4
  }
}

List Tasks for Agent

Retrieve all tasks associated with a specific agent.

GET /api/v1/tasks/agent/{agentId}

Path Parameters

NameTypeRequiredDescription
agentIdstringYesID of the agent

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "id": "task-123",
    "name": "Deploy Application",
    "status": "running",
    "progress": 75,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:15:00Z"
  }
]

List Tasks for Runner

Retrieve all tasks associated with a specific runner.

GET /api/v1/tasks/runner/{runnerId}

Path Parameters

NameTypeRequiredDescription
runnerIdstringYesID of the runner

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "id": "task-123",
    "name": "Deploy Application",
    "status": "running",
    "progress": 75,
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:15:00Z"
  }
]

Tasks are the core unit of work in the Kubiya platform. Monitor task execution and logs to ensure successful operations.

Example Usage

# List all tasks
curl -X GET "https://api.kubiya.ai/api/v1/tasks" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get task details
curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new task
curl -X POST "https://api.kubiya.ai/api/v1/tasks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Application",
    "description": "Deploy application to production environment",
    "agent_id": "agent-456",
    "runner_id": "runner-789",
    "metadata": {
      "environment": "production",
      "version": "1.2.0",
      "priority": "high"
    },
    "parameters": {
      "app_name": "my-app",
      "deploy_strategy": "rolling"
    }
  }'
 
# Cancel a task
curl -X PUT "https://api.kubiya.ai/api/v1/tasks/task-123/cancel" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get task logs
curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123/logs" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get task status
curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123/status" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# List tasks for an agent
curl -X GET "https://api.kubiya.ai/api/v1/tasks/agent/agent-456" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# List tasks for a runner
curl -X GET "https://api.kubiya.ai/api/v1/tasks/runner/runner-789" \
  -H "Authorization: UserKey YOUR_API_KEY"

Common Errors

HTTP StatusDescription
400Bad Request - Invalid request body or missing required fields
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have permission to perform this action
404Not Found - The specified task was not found
409Conflict - Task is in an invalid state for the requested operation
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After managing tasks, you can:

  • Monitor task execution using Runners
  • Configure Agents to execute specific types of tasks
  • Set up Webhooks for task status notifications