Projects API

The Projects API enables you to manage infrastructure-as-code (IaC) projects within Kubiya. These endpoints allow you to create, retrieve, and manage Terraform-based infrastructure deployments. Use Kubiya as a Terraform backend for GitOps workflows, state management, and agentic 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 projects

GET

Authentication

Token

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

Create a new project

POST

Authentication

Token

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

Request Body

List Projects

Retrieve a list of all projects in your organization.

GET /v1/projects

Headers

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

Response

The response contains an array of project objects. This endpoint internally calls the Tasks API and formats the response as projects.

[
  {
    "id": "project-123456",
    "name": "AWS Infrastructure",
    "description": "Core AWS infrastructure deployment",
    "icons": ["☁️", "🔧"],
    "readme": "# AWS Infrastructure\n\nThis project manages our core AWS infrastructure...",
    "url": "https://github.com/org/terraform-aws",
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-02T00:00:00Z",
    "commit": "abc123def456",
    "providers": [
      {
        "name": "aws"
      }
    ],
    "resources": [
      {
        "name": "vpc",
        "type": "aws_vpc",
        "provider": "aws",
        "variables": [
          {
            "name": "cidr_block",
            "type": "string",
            "description": "VPC CIDR block",
            "default": "10.0.0.0/16",
            "value": "10.0.0.0/16",
            "has_error": false
          }
        ]
      }
    ],
    "variables": [
      {
        "name": "region",
        "type": "string",
        "description": "AWS region",
        "default": "us-west-2",
        "value": "us-west-2",
        "has_error": false,
        "required": true
      }
    ],
    "secrets": [
      {
        "name": "aws_access_key",
        "description": "AWS access key",
        "to_env": "AWS_ACCESS_KEY_ID",
        "value": "******"
      },
      {
        "name": "aws_secret_key",
        "description": "AWS secret key",
        "to_env": "AWS_SECRET_ACCESS_KEY",
        "value": "******"
      }
    ],
    "workflows": [
      {
        "id": "workflow-123456",
        "type": "plan",
        "status": "completed",
        "created_at": "2023-01-01T10:00:00Z",
        "updated_at": "2023-01-01T10:05:00Z",
        "changes_detected": true,
        "plan_output": "Plan: 2 to add, 1 to change, 0 to destroy."
      }
    ]
  }
]

Create Project

Create a new infrastructure project in your organization.

POST /v1/projects

Headers

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

Request Body

{
  "name": "New AWS Infrastructure",
  "description": "Infrastructure for new AWS environment",
  "url": "https://github.com/org/terraform-aws-new",
  "providers": [
    {
      "name": "aws"
    }
  ],
  "variables": [
    {
      "name": "region",
      "type": "string",
      "description": "AWS region",
      "default": "us-west-2"
    },
    {
      "name": "environment",
      "type": "string",
      "description": "Deployment environment",
      "default": "staging"
    }
  ],
  "secrets": [
    {
      "name": "aws_access_key",
      "description": "AWS access key",
      "to_env": "AWS_ACCESS_KEY_ID",
      "value": "actual-access-key"
    },
    {
      "name": "aws_secret_key",
      "description": "AWS secret key",
      "to_env": "AWS_SECRET_ACCESS_KEY",
      "value": "actual-secret-key"
    }
  ]
}

Required Fields

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

Response

{
  "id": "project-123456",
  "name": "New AWS Infrastructure",
  "description": "Infrastructure for new AWS environment",
  "url": "https://github.com/org/terraform-aws-new",
  "status": "pending",
  "created_at": "2023-01-03T00:00:00Z",
  "updated_at": "2023-01-03T00:00:00Z",
  "providers": [
    {
      "name": "aws"
    }
  ],
  "variables": [
    {
      "name": "region",
      "type": "string",
      "description": "AWS region",
      "default": "us-west-2"
    },
    {
      "name": "environment",
      "type": "string",
      "description": "Deployment environment",
      "default": "staging"
    }
  ],
  "secrets": [
    {
      "name": "aws_access_key",
      "description": "AWS access key",
      "to_env": "AWS_ACCESS_KEY_ID",
      "value": "******"
    },
    {
      "name": "aws_secret_key",
      "description": "AWS secret key",
      "to_env": "AWS_SECRET_ACCESS_KEY",
      "value": "******"
    }
  ]
}

Get Project Details

Retrieve detailed information about a specific project.

GET /v1/projects/{project_id}

Path Parameters

Name	Type	Required	Description
`project_id`	string	Yes	ID of the project to retrieve

Headers

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

Response

{
  "id": "project-123456",
  "name": "AWS Infrastructure",
  "description": "Core AWS infrastructure deployment",
  "icons": ["☁️", "🔧"],
  "readme": "# AWS Infrastructure\n\nThis project manages our core AWS infrastructure...",
  "url": "https://github.com/org/terraform-aws",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-02T00:00:00Z",
  "commit": "abc123def456",
  "providers": [
    {
      "name": "aws"
    }
  ],
  "resources": [
    {
      "name": "vpc",
      "type": "aws_vpc",
      "provider": "aws",
      "variables": [
        {
          "name": "cidr_block",
          "type": "string",
          "description": "VPC CIDR block",
          "default": "10.0.0.0/16",
          "value": "10.0.0.0/16",
          "has_error": false
        }
      ]
    }
  ],
  "variables": [
    {
      "name": "region",
      "type": "string",
      "description": "AWS region",
      "default": "us-west-2",
      "value": "us-west-2",
      "has_error": false,
      "required": true
    }
  ],
  "secrets": [
    {
      "name": "aws_access_key",
      "description": "AWS access key",
      "to_env": "AWS_ACCESS_KEY_ID",
      "value": "******"
    },
    {
      "name": "aws_secret_key",
      "description": "AWS secret key",
      "to_env": "AWS_SECRET_ACCESS_KEY",
      "value": "******"
    }
  ],
  "workflows": [
    {
      "id": "workflow-123456",
      "type": "plan",
      "status": "completed",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:05:00Z",
      "changes_detected": true,
      "plan_output": "Plan: 2 to add, 1 to change, 0 to destroy."
    }
  ]
}

Update Project

Update an existing project with new parameters.

PUT /v1/projects/{project_id}

Path Parameters

Name	Type	Required	Description
`project_id`	string	Yes	ID of the project to update

Headers

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

Request Body

{
  "name": "Updated AWS Infrastructure",
  "description": "Updated infrastructure configuration",
  "variables": [
    {
      "name": "region",
      "type": "string",
      "value": "us-east-1",
      "description": "AWS region"
    },
    {
      "name": "environment",
      "type": "string",
      "value": "production",
      "description": "Deployment environment"
    }
  ]
}

Response

{
  "id": "project-123456",
  "name": "Updated AWS Infrastructure",
  "description": "Updated infrastructure configuration",
  "variables": [
    {
      "name": "region",
      "type": "string",
      "value": "us-east-1",
      "description": "AWS region"
    },
    {
      "name": "environment",
      "type": "string",
      "value": "production",
      "description": "Deployment environment"
    }
  ]
}

Run Terraform Plan

Generate a Terraform plan for a project.

POST /v1/projects/{project_id}/plan

Path Parameters

Name	Type	Required	Description
`project_id`	string	Yes	ID of the project to plan

Headers

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

Request Body

{
  "variables": {
    "region": "us-east-1",
    "environment": "production"
  }
}

Response

{
  "workflow_id": "workflow-234567",
  "project_id": "project-123456",
  "type": "plan",
  "status": "running",
  "started_at": "2023-01-03T10:00:00Z"
}

Apply Terraform Plan

Apply a previously generated Terraform plan.

POST /v1/projects/{project_id}/apply

Path Parameters

Name	Type	Required	Description
`project_id`	string	Yes	ID of the project to apply

Headers

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

Request Body

{
  "workflow_id": "workflow-234567", 
  "auto_approve": true
}

Response

{
  "workflow_id": "workflow-345678",
  "project_id": "project-123456",
  "type": "apply",
  "status": "running",
  "started_at": "2023-01-03T10:10:00Z"
}

Get Workflow Status

Retrieve the status of a specific workflow (plan or apply).

GET /v1/projects/{project_id}/workflows/{workflow_id}

Path Parameters

Name	Type	Required	Description
`project_id`	string	Yes	ID of the project
`workflow_id`	string	Yes	ID of the workflow to check

Headers

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

Response

{
  "id": "workflow-234567",
  "project_id": "project-123456",
  "type": "plan",
  "status": "completed",
  "started_at": "2023-01-03T10:00:00Z",
  "completed_at": "2023-01-03T10:05:00Z",
  "changes_detected": true,
  "plan_output": "Plan: 2 to add, 1 to change, 0 to destroy."
}

Example Usage

List Projects

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

Create a Project

curl -X POST "https://api.kubiya.ai/v1/projects" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New AWS Infrastructure",
    "description": "Infrastructure for new AWS environment",
    "url": "https://github.com/org/terraform-aws-new",
    "providers": [
      {
        "name": "aws"
      }
    ],
    "variables": [
      {
        "name": "region",
        "type": "string",
        "description": "AWS region",
        "default": "us-west-2"
      }
    ]
  }'

Get Project Details

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

Update a Project

curl -X PUT "https://api.kubiya.ai/v1/projects/project-123456" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated AWS Infrastructure",
    "description": "Updated infrastructure configuration",
    "variables": [
      {
        "name": "region",
        "type": "string",
        "value": "us-east-1",
        "description": "AWS region"
      }
    ]
  }'

Run Terraform Plan

curl -X POST "https://api.kubiya.ai/v1/projects/project-123456/plan" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "region": "us-east-1",
      "environment": "production"
    }
  }'

Apply Terraform Plan

curl -X POST "https://api.kubiya.ai/v1/projects/project-123456/apply" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "workflow-234567", 
    "auto_approve": true
  }'

Common Errors

HTTP Status	Description
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Missing or invalid API key
403	Forbidden - Insufficient permissions to access the project
404	Not Found - Project or workflow not found
409	Conflict - A project with this name already exists
500	Internal Server Error - Unexpected server error

Projects in Kubiya are integrated with Terraform to provide infrastructure-as-code capabilities. The API allows you to manage the entire lifecycle of infrastructure projects, from planning to applying changes.

Project States

Projects in Kubiya can have the following states:

State	Description
`pending`	Project has been created but not yet initialized
`active`	Project is fully operational and ready for use
`failed`	Project initialization or operation has failed
`updating`	Project is currently being updated
`deleting`	Project is in the process of being deleted
`error`	Project is in an error state

Projects API

List all projects

Create a new project

On this page