POST
/
api
/
v1
/
tasks
Tasks API
curl --request POST \
  --url https://api.kubiya.ai/api/v1/api/v1/tasks \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "name": "<string>",
  "description": "<string>",
  "agent_id": "<string>",
  "runner_id": "<string>",
  "metadata": {},
  "parameters": {}
}'

Infrastrure as code Tasks API

The Tasks API allows you to manage IAC tasks in your organization, including creating, monitoring, and controlling their execution lifecycle. Tasks are powered behind the scenes using Terraform and allows a flexible interface for users and agents to consume infrastrcuture automations from within workflows

Base URL

https://api.kubiya.ai/api/v1/tasks
All endpoints require authentication with a valid API key.

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": {}
  }
}

Task Object

{
  "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
  }
}

List Tasks

Retrieve all tasks in your organization.
GET /api/v1/tasks

Query Parameters

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

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks" \
  -H "Authorization: UserKey $KUBIYA_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

taskId
string
required
ID of the task

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123" \
  -H "Authorization: UserKey $KUBIYA_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

Authorization
string
required
UserKey YOUR_API_KEY
Content-Type
string
required
application/json

Request Body

name
string
required
Name of the task
description
string
Description of the task
agent_id
string
required
ID of the agent to execute the task
runner_id
string
required
ID of the runner to use
metadata
object
Additional metadata for the task
parameters
object
Task-specific parameters

Example Requests

curl -X POST "https://api.kubiya.ai/api/v1/tasks" \
  -H "Authorization: UserKey $KUBIYA_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"
    }
  }'

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

taskId
string
required
ID of the task to cancel

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X PUT "https://api.kubiya.ai/api/v1/tasks/task-123/cancel" \
  -H "Authorization: UserKey $KUBIYA_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

taskId
string
required
ID of the task

Query Parameters

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

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123/logs" \
  -H "Authorization: UserKey $KUBIYA_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

taskId
string
required
ID of the task

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks/task-123/status" \
  -H "Authorization: UserKey $KUBIYA_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

agentId
string
required
ID of the agent

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks/agent/agent-456" \
  -H "Authorization: UserKey $KUBIYA_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

runnerId
string
required
ID of the runner

Headers

Authorization
string
required
UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/tasks/runner/runner-789" \
  -H "Authorization: UserKey $KUBIYA_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"
  }
]

Common Errors

{
  "error": {
    "code": "not_found",
    "message": "Task not found",
    "details": {
      "taskId": "task-123"
    }
  }
}

Error Status Codes

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