Projects Service

The Projects Service enables you to organize agents and teams into logical projects, providing structure for managing resources across different initiatives, applications, or organizational units.

Quick Start

from kubiya import ControlPlaneClient

client = ControlPlaneClient()

# List all projects
projects = client.projects.list()

# Get the default project
default_project = client.projects.get_default()

# Create a new project
project_data = {
    "name": "E-commerce Platform",
    "description": "Project for e-commerce application"
}
project = client.projects.create(project_data)

Features

Project Management

Create, update, and organize projects

Agent Assignment

Assign agents to projects with roles

Team Assignment

Assign teams to projects

Default Project

Automatic default project for organization

List Projects

Retrieve all projects in your organization:

# List all projects
projects = client.projects.list()

# List with status filter
active_projects = client.projects.list(status_filter="active")
archived_projects = client.projects.list(status_filter="archived")

Parameters:

status_filter (str, optional): Filter by status: ‘active’, ‘inactive’, or ‘archived’

Returns: List of project dictionaries

Get Project

Retrieve a specific project by ID:

project = client.projects.get(project_id="550e8400-e29b-41d4-a716-446655440000")

print(f"Project: {project['name']}")
print(f"Description: {project['description']}")
print(f"Status: {project['status']}")
print(f"Created: {project['created_at']}")

Parameters:

project_id (str, required): Project UUID

Returns: Dictionary containing project details

Get Default Project

Retrieve the default project for your organization:

default_project = client.projects.get_default()

print(f"Default Project ID: {default_project['id']}")
print(f"Name: {default_project['name']}")

Returns: Dictionary containing default project details

The default project is automatically created for your organization. If it doesn’t exist, this method will create it.

Create Project

Create a new project:

project_data = {
    "name": "Mobile App Project",
    "description": "iOS and Android mobile applications",
    "status": "active",
    "metadata": {
        "department": "Engineering",
        "owner": "mobile-team@example.com"
    }
}

project = client.projects.create(project_data)
print(f"Created project: {project['id']}")

Parameters:

project_data (dict, required): Project configuration
- name (str): Project name
- description (str): Project description
- status (str, optional): Project status (default: ‘active’)
- metadata (dict, optional): Additional metadata

Returns: Dictionary containing created project details

Update Project

Update an existing project (partial update):

# Update project name and description
updated_project = client.projects.update(
    project_id="project-uuid",
    project_data={
        "name": "Updated Project Name",
        "description": "New description"
    }
)

# Update status
updated_project = client.projects.update(
    project_id="project-uuid",
    project_data={
        "status": "inactive"
    }
)

# Update metadata
updated_project = client.projects.update(
    project_id="project-uuid",
    project_data={
        "metadata": {
            "budget": "100000",
            "priority": "high"
        }
    }
)

Parameters:

project_id (str, required): Project UUID
project_data (dict, required): Fields to update (partial update)
- name (str, optional): Project name
- description (str, optional): Project description
- status (str, optional): Project status
- metadata (dict, optional): Additional metadata

Returns: Dictionary containing updated project details

Delete Project

Delete a project:

client.projects.delete(project_id="project-uuid")
print("Project deleted successfully")

Parameters:

project_id (str, required): Project UUID

Returns: None (204 No Content on success)

Deleting a project will cascade delete all project-agent and project-team associations. The agents and teams themselves are not deleted.

Agent Management

Add Agent to Project

Add an agent to a project with an optional role:

# Add agent with role
result = client.projects.add_agent(
    project_id="project-uuid",
    agent_id="agent-uuid",
    role="developer"
)

print(f"Agent added with role: {result['role']}")

# Add agent without role
result = client.projects.add_agent(
    project_id="project-uuid",
    agent_id="agent-uuid"
)

Parameters:

project_id (str, required): Project UUID
agent_id (str, required): Agent UUID
role (str, optional): Role for the agent in this project

Returns: Dictionary containing project-agent association details

List Project Agents

List all agents in a project:

agents = client.projects.list_agents(project_id="project-uuid")

for agent_assoc in agents:
    print(f"Agent: {agent_assoc['agent']['name']}")
    print(f"  Role: {agent_assoc.get('role', 'N/A')}")
    print(f"  Added: {agent_assoc['created_at']}")

Parameters:

project_id (str, required): Project UUID

Returns: List of project-agent association dictionaries with nested agent data

Remove Agent from Project

Remove an agent from a project:

client.projects.remove_agent(
    project_id="project-uuid",
    agent_id="agent-uuid"
)
print("Agent removed from project")

Parameters:

project_id (str, required): Project UUID
agent_id (str, required): Agent UUID

Returns: None (204 No Content on success)

Team Management

Add Team to Project

Add a team to a project with an optional role:

# Add team with role
result = client.projects.add_team(
    project_id="project-uuid",
    team_id="team-uuid",
    role="infrastructure"
)

print(f"Team added with role: {result['role']}")

# Add team without role
result = client.projects.add_team(
    project_id="project-uuid",
    team_id="team-uuid"
)

Parameters:

project_id (str, required): Project UUID
team_id (str, required): Team UUID
role (str, optional): Role for the team in this project

Returns: Dictionary containing project-team association details

List Project Teams

List all teams in a project:

teams = client.projects.list_teams(project_id="project-uuid")

for team_assoc in teams:
    print(f"Team: {team_assoc['team']['name']}")
    print(f"  Role: {team_assoc.get('role', 'N/A')}")
    print(f"  Added: {team_assoc['created_at']}")

Parameters:

project_id (str, required): Project UUID

Returns: List of project-team association dictionaries with nested team data

Remove Team from Project

Remove a team from a project:

client.projects.remove_team(
    project_id="project-uuid",
    team_id="team-uuid"
)
print("Team removed from project")

Parameters:

project_id (str, required): Project UUID
team_id (str, required): Team UUID

Returns: None (204 No Content on success)

Complete Example

Here’s a complete example of creating and managing a project:

from kubiya import ControlPlaneClient

client = ControlPlaneClient()

# 1. Create a new project
project_data = {
    "name": "Infrastructure Modernization",
    "description": "Migrate legacy infrastructure to cloud-native",
    "status": "active",
    "metadata": {
        "budget": "500000",
        "deadline": "2024-12-31",
        "priority": "high"
    }
}

project = client.projects.create(project_data)
print(f"Created project: {project['id']}")

# 2. Add agents to the project
agents = [
    {"id": "agent-1-uuid", "role": "cloud-architect"},
    {"id": "agent-2-uuid", "role": "devops-engineer"},
    {"id": "agent-3-uuid", "role": "security-specialist"}
]

for agent in agents:
    result = client.projects.add_agent(
        project_id=project['id'],
        agent_id=agent['id'],
        role=agent['role']
    )
    print(f"Added agent with role: {agent['role']}")

# 3. Add teams to the project
teams = [
    {"id": "team-1-uuid", "role": "infrastructure"},
    {"id": "team-2-uuid", "role": "application"}
]

for team in teams:
    result = client.projects.add_team(
        project_id=project['id'],
        team_id=team['id'],
        role=team['role']
    )
    print(f"Added team with role: {team['role']}")

# 4. List all project resources
print("\nProject Agents:")
project_agents = client.projects.list_agents(project_id=project['id'])
for agent_assoc in project_agents:
    print(f"  - {agent_assoc['agent']['name']} ({agent_assoc.get('role', 'N/A')})")

print("\nProject Teams:")
project_teams = client.projects.list_teams(project_id=project['id'])
for team_assoc in project_teams:
    print(f"  - {team_assoc['team']['name']} ({team_assoc.get('role', 'N/A')})")

# 5. Update project status
updated_project = client.projects.update(
    project_id=project['id'],
    project_data={
        "status": "active",
        "metadata": {
            "phase": "planning",
            "completion": "10%"
        }
    }
)
print(f"\nProject status: {updated_project['status']}")

Error Handling

Handle project-related errors:

from kubiya.resources.exceptions import ProjectError

try:
    project = client.projects.get(project_id="invalid-id")
except ProjectError as e:
    print(f"Project error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Best Practices

Project Organization

Clear Boundaries: Define clear project boundaries and scope
Descriptive Names: Use names that clearly indicate the project’s purpose
Consistent Structure: Maintain consistent metadata across projects
Default Project: Use the default project for general-purpose resources

Resource Assignment

Role Definition: Use roles to clarify agent/team responsibilities
Avoid Over-Assignment: Don’t assign resources to too many projects
Review Regularly: Periodically review project memberships
Remove Inactive: Remove agents/teams no longer working on the project

Lifecycle Management

Active Status: Keep only current projects as ‘active’
Archive Completed: Archive completed projects instead of deleting
Track Metadata: Use metadata for budget, deadlines, and ownership
Audit Trail: Maintain history of project changes

Integration with Other Services

Agents: Assign specialized agents based on project needs
Teams: Use teams for collaborative project work
Environments: Link projects to specific environments
Jobs: Associate scheduled jobs with projects

Use Cases

By Department

# Engineering project
engineering = client.projects.create({
    "name": "Engineering - Q1 2024",
    "metadata": {"department": "engineering"}
})

# Marketing project
marketing = client.projects.create({
    "name": "Marketing Automation",
    "metadata": {"department": "marketing"}
})

By Application

# Web application project
web_app = client.projects.create({
    "name": "Web Application",
    "description": "Customer-facing web platform"
})

# Mobile app project
mobile_app = client.projects.create({
    "name": "Mobile App",
    "description": "iOS and Android applications"
})

By Initiative

# Migration project
migration = client.projects.create({
    "name": "Cloud Migration 2024",
    "description": "Migrate on-premise workloads to cloud",
    "metadata": {
        "initiative": "cloud-first",
        "priority": "critical"
    }
})

API Reference

Method	Endpoint Pattern	Description
`list()`	GET /projects	List all projects
`get()`	GET /projects/	Get project by ID
`get_default()`	GET /projects/default	Get default project
`create()`	POST /projects	Create new project
`update()`	PATCH /projects/	Update project
`delete()`	DELETE /projects/	Delete project
`add_agent()`	POST /projects//agents	Add agent to project
`list_agents()`	GET /projects//agents	List project agents
`remove_agent()`	DELETE /projects//agents/	Remove agent
`add_team()`	POST /projects//teams	Add team to project
`list_teams()`	GET /projects//teams	List project teams
`remove_team()`	DELETE /projects//teams/	Remove team

Next Steps

Agents Service

Manage agents to assign to projects

Teams Service

Create teams for project work

Environments Service

Link projects to environments

Jobs Service

Schedule jobs for project tasks

​Quick Start

​Features

Project Management

Agent Assignment

Team Assignment

Default Project

​List Projects

​Get Project

​Get Default Project

​Create Project

​Update Project

​Delete Project

​Agent Management

​Add Agent to Project

​List Project Agents

​Remove Agent from Project

​Team Management

​Add Team to Project

​List Project Teams

​Remove Team from Project

​Complete Example

​Error Handling

​Best Practices

​Project Organization

​Resource Assignment

​Lifecycle Management

​Integration with Other Services

​Use Cases

​By Department

​By Application

​By Initiative

​API Reference

​Next Steps

Agents Service

Teams Service

Environments Service

Jobs Service

Quick Start

Features

List Projects

Get Project

Get Default Project

Create Project

Update Project

Delete Project

Agent Management

Add Agent to Project

List Project Agents

Remove Agent from Project

Team Management

Add Team to Project

List Project Teams

Remove Team from Project

Complete Example

Error Handling

Best Practices

Project Organization

Resource Assignment

Lifecycle Management

Integration with Other Services

Use Cases

By Department

By Application

By Initiative

API Reference

Next Steps