> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/sdk/client-overview) for initialization and authentication instructions.

### Create a project example

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

```python theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
project = client.projects.get("project-uuid-here")
print(project)
```

### Get Default Project

Get or create the default project for the organization:

```python theme={null}
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:

```python theme={null}
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):

```python theme={null}
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:

```python theme={null}
client.projects.delete("project-uuid")
```

***

## Agent Management

### Add Agent to Project

Add an agent to a project with an optional role:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
client.projects.remove_team("project-uuid", "team-uuid")
print("Team removed from project")
```

***

## Error Handling

The Projects Service raises `ProjectError` for API errors:

```python theme={null}
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

```python theme={null}
# 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

```python theme={null}
# 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']}")
```