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

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

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 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

Agents API

Configure agents to execute tasks

Runners API

Deploy and manage execution environments

Webhooks API

Set up notifications for task events

Sources API

Manage tool sources for task execution

Kubiya Platform APIs

MCP Server APIs

​Infrastrure as code Tasks API

​Base URL

​Endpoints

​Common Response Status Codes

​Error Response Format

​Task Object

​List Tasks

​Query Parameters

​Headers

​Example Request

​Response

​Get Task Details

​Path Parameters

​Headers

​Example Request

​Response

​Create Task

​Headers

​Request Body

​Example Requests

​Response

​Cancel Task

​Path Parameters

​Headers

​Example Request

​Response

​Get Task Logs

​Path Parameters

​Query Parameters

​Headers

​Example Request

​Response

​Get Task Status

​Path Parameters

​Headers

​Example Request

​Response

​List Tasks for Agent

​Path Parameters

​Headers

​Example Request

​Response

​List Tasks for Runner

​Path Parameters

​Headers

​Example Request

​Response

​Common Errors

​Error Status Codes

​Next Steps

Agents API

Runners API

Webhooks API

Sources API

Infrastrure as code Tasks API

Base URL

Endpoints

Common Response Status Codes

Error Response Format

Task Object

List Tasks

Query Parameters

Headers

Example Request

Response

Get Task Details

Path Parameters

Headers

Example Request

Response

Create Task

Headers

Request Body

Example Requests

Response

Cancel Task

Path Parameters

Headers

Example Request

Response

Get Task Logs

Path Parameters

Query Parameters

Headers

Example Request

Response

Get Task Status

Path Parameters

Headers

Example Request

Response

List Tasks for Agent

Path Parameters

Headers

Example Request

Response

List Tasks for Runner

Path Parameters

Headers

Example Request

Response

Common Errors

Error Status Codes

Next Steps