Projects Service

Organize and manage projects with agent and team associations using the Kubiya SDK

The Projects Service provides comprehensive management of projects through the Kubiya platform. Projects help you organize resources by grouping agents and teams together, enabling better access control and resource management.

Projects: detailed guide

This page focuses on the project-specific parts of the SDK: creation, configuration, agent/team associations, and common patterns.

If you haven’t set up a ControlPlaneClient yet, see the Client Quick Start at Client Overview for initialization and authentication instructions.

Create a project example

The following example demonstrates creating a project using the Control Plane SDK:

from kubiya.control_plane_client import ControlPlaneClient

client = ControlPlaneClient()

project_data = {
    "name": "production-infrastructure",
    "key": "PRODINFRA",
    "description": "Production infrastructure management project",
    "restrict_to_environment": False,
    "policy_ids": []
}

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

Core Operations

List Projects

Retrieve a list of projects with optional status filtering:

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

# Filter by status
active_projects = client.projects.list(status_filter="active")
archived_projects = client.projects.list(status_filter="archived")

for project in projects:
    print(f"Project: {project['name']} - Status: {project.get('status')}")

Parameters:

Parameter	Type	Default	Description
status_filter	str	None	Filter by status: active, inactive, archived

Get Project Details

Fetch a single project’s details by UUID:

project = client.projects.get("project-uuid-here")
print(project)

Get Default Project

Get or create the default project for the organization:

default_project = client.projects.get_default()
print(f"Default project: {default_project['name']}")

This will create the default project if it doesn’t exist.

Create Project

Create a new project:

project_data = {
    "name": "staging-environment",
    "key": "STAGING",
    "description": "Staging environment resources",
    "restrict_to_environment": False,
    "policy_ids": []
}

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

Project configuration fields:

Field	Type	Required	Description
name	str	Yes	Project name
key	str	Yes	Unique project key (e.g., PROD, STAGING)
description	str	No	Project description
restrict_to_environment	bool	No	Restrict project to specific environment (default: False)
policy_ids	list	No	List of policy IDs to apply to the project

Update Project

Update an existing project’s configuration (partial update - only provided fields are updated):

update_data = {
    "description": "Updated project description",
    "status": "active"
}

updated = client.projects.update("project-uuid", update_data)
print(updated)

Delete Project

Permanently remove a project by UUID:

client.projects.delete("project-uuid")

---

Agent Management

Add Agent to Project

Add an agent to a project with an optional role:

result = client.projects.add_agent(
    project_id="project-uuid",
    agent_id="agent-uuid",
    role="developer"  # Optional role
)
print(f"Agent added to project: {result}")

List Agents in Project

Retrieve all agents associated with a project:

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

for agent_assoc in agents:
    agent = agent_assoc.get('agents', {})
    print(f"Agent: {agent.get('name')} - Role: {agent_assoc.get('role')}")

Remove Agent from Project

Remove an agent from a project:

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

---

Team Management

Add Team to Project

Add a team to a project with an optional role:

result = client.projects.add_team(
    project_id="project-uuid",
    team_id="team-uuid",
    role="maintainer"  # Optional role
)
print(f"Team added to project: {result}")

List Teams in Project

Retrieve all teams associated with a project:

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

for team_assoc in teams:
    team = team_assoc.get('teams', {})
    print(f"Team: {team.get('name')} - Role: {team_assoc.get('role')}")

Remove Team from Project

Remove a team from a project:

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

---

Error Handling

The Projects Service raises ProjectError for API errors:

from kubiya.resources.exceptions import ProjectError

try:
    project = client.projects.get("non-existent-project")
except ProjectError as e:
    print(f"Project operation failed: {e}")

---

Best Practices

• Use descriptive project names that reflect the project’s scope
• Assign appropriate roles when adding agents and teams
• Use status filters to manage active vs archived projects
• Organize related agents and teams in the same project
• Use the default project for general-purpose resources
• Archive projects instead of deleting them to preserve history

---

Common Patterns

Set Up a Complete Project

# Create project
project = client.projects.create({
    "name": "customer-support",
    "key": "SUPPORT",
    "description": "Customer support automation project",
    "restrict_to_environment": False,
    "policy_ids": []
})

# Add agents with roles
client.projects.add_agent(project["id"], "triage-agent-uuid", role="triage")
client.projects.add_agent(project["id"], "response-agent-uuid", role="responder")
client.projects.add_agent(project["id"], "escalation-agent-uuid", role="escalation")

# Add teams
client.projects.add_team(project["id"], "support-team-uuid", role="primary")

# List all resources
print("Agents in project:")
for agent_assoc in client.projects.list_agents(project["id"]):
    print(agent_assoc)

print("Teams in project:")
for team_assoc in client.projects.list_teams(project["id"]):
    print(team_assoc)

Archive Inactive Projects

# Find and archive inactive projects
projects = client.projects.list(status_filter="active")

for project in projects:
    # Check if project has no recent activity (custom logic)
    agents = client.projects.list_agents(project["id"])
    teams = client.projects.list_teams(project["id"])

    if not agents and not teams:
        client.projects.update(project["id"], {"status": "archived"})
        print(f"Archived empty project: {project['name']}")