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

Method	Path	Description
GET	`/api/v1/tasks`	List all tasks
GET	`/api/v1/tasks/{taskId}`	Get task details
POST	`/api/v1/tasks`	Create a new task
PUT	`/api/v1/tasks/{taskId}/cancel`	Cancel a task
GET	`/api/v1/tasks/{taskId}/logs`	Get task logs
GET	`/api/v1/tasks/{taskId}/status`	Get 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 Code	Description
200	Success
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal 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

Name	Type	Required	Description
`status`	string	No	Filter by task status
`agent`	string	No	Filter by agent ID
`runner`	string	No	Filter by runner ID
`limit`	integer	No	Maximum number of tasks to return (default: 50)
`page`	integer	No	Page number for pagination
`sort`	string	No	Sort by field (created_at, updated_at, status)
`order`	string	No	Sort order (asc, desc)

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`taskId`	string	Yes	ID of the task

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/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

Name	Type	Required	Description
`taskId`	string	Yes	ID of the task to cancel

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`taskId`	string	Yes	ID of the task

Query Parameters

Name	Type	Required	Description
`start_time`	string	No	Filter logs after this timestamp
`end_time`	string	No	Filter logs before this timestamp
`level`	string	No	Filter by log level (info, error, debug)
`limit`	integer	No	Maximum number of log entries to return

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`taskId`	string	Yes	ID of the task

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`runnerId`	string	Yes	ID of the runner

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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 Status	Description
400	Bad Request - Invalid request body or missing required fields
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to perform this action
404	Not Found - The specified task was not found
409	Conflict - Task is in an invalid state for the requested operation
500	Internal 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

Tasks API

On this page