Tasks API

The Tasks API provides endpoints to manage automation tasks in Kubiya. Tasks are used for managing workflows and automation processes, including infrastructure deployments, configuration management, and other DevOps operations.

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.

List all tasks

GET

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Create a new task

POST

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Request Body

List Tasks

Retrieve a list of all tasks in your organization.

GET /v1/tasks

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	No	application/json

Response

[
  {
    "id": "task-123456",
    "name": "Deploy Application",
    "description": "Automated deployment of the application to production",
    "icons": ["🚀", "⚙️"],
    "readme": "# Deployment Task\n\nThis task handles automated deployments...",
    "url": "https://github.com/org/deployment-tasks",
    "providers": [
      {
        "name": "aws"
      },
      {
        "name": "kubernetes"
      }
    ],
    "resources": [
      {
        "name": "application_deployment",
        "type": "kubernetes_deployment",
        "provider": "kubernetes",
        "variables": [
          {
            "name": "namespace",
            "type": "string",
            "value": "production",
            "default": "default",
            "description": "Kubernetes namespace",
            "has_error": false
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "environment",
        "type": "string",
        "value": "production",
        "default": "staging",
        "description": "Deployment environment",
        "has_error": false,
        "required": true
      }
    ],
    "secrets": [
      {
        "name": "api_key",
        "description": "API key for external service",
        "to_env": "API_KEY",
        "value": "******"
      }
    ]
  }
]

Create Task

Create a new task in your organization.

POST /v1/tasks

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "name": "New Deployment Task",
  "description": "Automated deployment of the application to production",
  "icons": ["🚀", "⚙️"],
  "url": "https://github.com/org/deployment-tasks",
  "providers": [
    {
      "name": "aws"
    }
  ],
  "variables": [
    {
      "name": "environment",
      "type": "string",
      "default": "staging",
      "description": "Deployment environment",
      "required": true
    }
  ],
  "secrets": [
    {
      "name": "api_key",
      "description": "API key for external service",
      "to_env": "API_KEY",
      "value": "secret-value"
    }
  ]
}

Required Fields

name: Name of the task
description: Description of what the task does

Response

{
  "id": "task-123456",
  "name": "New Deployment Task",
  "description": "Automated deployment of the application to production",
  "icons": ["🚀", "⚙️"],
  "url": "https://github.com/org/deployment-tasks",
  "providers": [
    {
      "name": "aws"
    }
  ],
  "variables": [
    {
      "name": "environment",
      "type": "string",
      "default": "staging",
      "description": "Deployment environment",
      "required": true
    }
  ],
  "secrets": [
    {
      "name": "api_key",
      "description": "API key for external service",
      "to_env": "API_KEY",
      "value": "******"
    }
  ]
}

Get Task Details

Retrieve detailed information about a specific task.

GET /v1/tasks/{task_id}

Path Parameters

Name	Type	Required	Description
`task_id`	string	Yes	ID of the task to retrieve

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	No	application/json

Response

{
  "id": "task-123456",
  "name": "Deploy Application",
  "description": "Automated deployment of the application to production",
  "icons": ["🚀", "⚙️"],
  "readme": "# Deployment Task\n\nThis task handles automated deployments...",
  "url": "https://github.com/org/deployment-tasks",
  "providers": [
    {
      "name": "aws"
    },
    {
      "name": "kubernetes"
    }
  ],
  "resources": [
    {
      "name": "application_deployment",
      "type": "kubernetes_deployment",
      "provider": "kubernetes",
      "variables": [
        {
          "name": "namespace",
          "type": "string",
          "value": "production",
          "default": "default",
          "description": "Kubernetes namespace",
          "has_error": false
        }
      ]
    }
  ],
  "variables": [
    {
      "name": "environment",
      "type": "string",
      "value": "production",
      "default": "staging",
      "description": "Deployment environment",
      "has_error": false,
      "required": true
    }
  ],
  "secrets": [
    {
      "name": "api_key",
      "description": "API key for external service",
      "to_env": "API_KEY",
      "value": "******"
    }
  ]
}

Update Task

Update an existing task with new parameters.

PUT /v1/tasks/{task_id}

Path Parameters

Name	Type	Required	Description
`task_id`	string	Yes	ID of the task to update

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "name": "Updated Deployment Task",
  "description": "Updated deployment task with new parameters",
  "variables": [
    {
      "name": "environment",
      "type": "string",
      "value": "production",
      "description": "Deployment environment",
      "required": true
    },
    {
      "name": "version",
      "type": "string",
      "value": "1.2.3",
      "description": "Application version",
      "required": true
    }
  ]
}

Response

{
  "id": "task-123456",
  "name": "Updated Deployment Task",
  "description": "Updated deployment task with new parameters",
  "variables": [
    {
      "name": "environment",
      "type": "string",
      "value": "production",
      "description": "Deployment environment",
      "required": true
    },
    {
      "name": "version",
      "type": "string",
      "value": "1.2.3",
      "description": "Application version",
      "required": true
    }
  ]
}

Run Task

Execute a task with specific parameters.

POST /v1/tasks/{task_id}/run

Path Parameters

Name	Type	Required	Description
`task_id`	string	Yes	ID of the task to run

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Request Body

{
  "variables": {
    "environment": "production",
    "version": "1.2.3"
  },
  "plan_only": false
}

Response

{
  "run_id": "run-123456",
  "task_id": "task-123456",
  "status": "running",
  "started_at": "2023-01-01T00:00:00Z",
  "variables": {
    "environment": "production",
    "version": "1.2.3"
  }
}

Example Usage

List Tasks

curl -X GET "https://api.kubiya.ai/v1/tasks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create a Task

curl -X POST "https://api.kubiya.ai/v1/tasks" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deploy Application",
    "description": "Deploys the application to production",
    "url": "https://github.com/organization/deploy-scripts",
    "providers": [
      {
        "name": "kubernetes"
      }
    ],
    "variables": [
      {
        "name": "environment",
        "type": "string",
        "description": "Deployment environment",
        "default": "staging"
      }
    ]
  }'

Get Task Details

curl -X GET "https://api.kubiya.ai/v1/tasks/task-123456" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Update a Task

curl -X PUT "https://api.kubiya.ai/v1/tasks/task-123456" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Deployment Task",
    "description": "Updated deployment task with new parameters",
    "variables": [
      {
        "name": "environment",
        "type": "string",
        "value": "production",
        "description": "Deployment environment",
        "required": true
      }
    ]
  }'

Run a Task

curl -X POST "https://api.kubiya.ai/v1/tasks/task-123456/run" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "environment": "production",
      "version": "1.2.3"
    },
    "plan_only": false
  }'

Common Errors

HTTP Status	Description
400	Bad Request - Missing required fields or invalid parameter
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key doesn't have permission for this operation
404	Not Found - Task not found
409	Conflict - A task with this name already exists
500	Internal Server Error - Unexpected server error

Data Types

Task

Field	Type	Description
`id`	string	Unique identifier for the task
`name`	string	Human-readable name for the task
`description`	string	Description of what the task does
`icons`	string[]	Array of emoji icons representing the task
`readme`	string	Markdown documentation for the task
`url`	string	Source URL for the task (e.g., GitHub repository)
`providers`	Provider[]	Infrastructure providers used by this task
`resources`	Resource[]	Resources managed by this task
`variables`	Variable[]	Variables that can be configured for this task
`secrets`	Secret[]	Secrets used by this task

Variable

Field	Type	Description
`name`	string	Variable name
`type`	string	Data type (string, number, boolean, etc.)
`value`	any	Current value (optional)
`default`	any	Default value (optional)
`description`	string	Human-readable description
`required`	boolean	Whether this variable is required
`has_error`	boolean	Whether there's an error with this variable
`error_detail`	string	Detailed error message if has_error is true
`error_summary`	string	Summary of the error if has_error is true

Secret

Field	Type	Description
`name`	string	Secret name
`description`	string	Human-readable description
`to_env`	string	Environment variable name to map this secret to
`value`	string	Secret value (masked in responses)

Task Execution

While the Tasks API manages task definitions, execution of tasks is typically handled through the following mechanisms:

Direct Execution: Tasks can be executed directly through the Execution API
Event-Driven: Tasks can be triggered by webhook events
Scheduled: Tasks can be executed on a schedule

The execution details and status tracking are handled through separate API endpoints.

Task Variables and Secrets

Tasks can have variables and secrets that control their behavior:

Variables: Configuration options that can be set at task creation or execution time
Secrets: Sensitive information (like API keys) that are securely stored and made available during task execution

Common Use Cases

Tasks in Kubiya are commonly used for:

Application Deployments: Automate the deployment of applications to various environments
Infrastructure Management: Provision and configure infrastructure resources
CI/CD Integration: Integrate with continuous integration and deployment pipelines
Automated Remediation: Fix common issues automatically when triggered by alerts
Scheduled Maintenance: Perform routine maintenance tasks on a schedule

For detailed examples of task implementations, refer to the Task Examples Guide.

Tasks API

List all tasks

Create a new task

On this page