---
title: "Projects API"
description: "Create, read, update, and delete TraceRTM projects"
keywords: [projects, project management, api, crud]
---

# Projects API

The Projects API allows you to manage TraceRTM projects, which are containers for items, links, and traceability data.

## Base Endpoint

```
/api/v1/projects
```

## List Projects

Retrieve a list of all projects.

### Endpoint

```
GET /api/v1/projects
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `skip` | integer | No | Number of projects to skip (default: 0) |
| `limit` | integer | No | Maximum projects to return (default: 100, max: 1000) |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/projects?skip=0&limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "total": 10,
  "projects": [
    {
      "id": "proj_abc123",
      "name": "Authentication System",
      "description": "OAuth 2.0 authentication implementation",
      "metadata": {
        "team": "backend",
        "status": "active"
      }
    },
    {
      "id": "proj_def456",
      "name": "Payment Gateway",
      "description": "Payment processing integration",
      "metadata": {
        "team": "fintech",
        "status": "planning"
      }
    }
  ]
}
```

### Python Example

```python
from tracertm import TraceRTM

client = TraceRTM(api_key="rtm_live_abc123...")

# List all projects
projects = client.projects.list(skip=0, limit=50)

print(f"Total projects: {projects.total}")
for project in projects.projects:
    print(f"{project.id}: {project.name}")
```

## Get Project

Retrieve a specific project by ID.

### Endpoint

```
GET /api/v1/projects/{project_id}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID |

### Request Example

```bash
curl -X GET "https://api.tracertm.dev/v1/projects/proj_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"
```

### Response

```json
{
  "id": "proj_abc123",
  "name": "Authentication System",
  "description": "OAuth 2.0 authentication implementation",
  "metadata": {
    "team": "backend",
    "status": "active",
    "created_by": "user_123"
  }
}
```

### Python Example

```python
project = client.projects.get("proj_abc123")
print(f"Project: {project.name}")
print(f"Description: {project.description}")
print(f"Metadata: {project.metadata}")
```

## Create Project

Create a new project.

### Endpoint

```
POST /api/v1/projects
```

### Request Body

```json
{
  "name": "New Project",
  "description": "Project description",
  "metadata": {
    "team": "backend",
    "status": "active"
  }
}
```

### Request Example

```bash
curl -X POST "https://api.tracertm.dev/v1/projects" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Project",
    "description": "Project description",
    "metadata": {
      "team": "backend"
    }
  }'
```

### Response

```json
{
  "id": "proj_new_xyz789",
  "name": "New Project",
  "description": "Project description",
  "metadata": {
    "team": "backend"
  }
}
```

### Python Example

```python
new_project = client.projects.create(
    name="New Project",
    description="Project description",
    metadata={
        "team": "backend",
        "status": "active"
    }
)

print(f"Created project: {new_project.id}")
```

## Update Project

Update an existing project.

### Endpoint

```
PUT /api/v1/projects/{project_id}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID to update |

### Request Body

```json
{
  "name": "Updated Project Name",
  "description": "Updated description",
  "metadata": {
    "team": "frontend",
    "status": "active"
  }
}
```

### Request Example

```bash
curl -X PUT "https://api.tracertm.dev/v1/projects/proj_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Project Name",
    "description": "Updated description"
  }'
```

### Response

```json
{
  "id": "proj_abc123",
  "name": "Updated Project Name",
  "description": "Updated description",
  "metadata": {
    "team": "frontend",
    "status": "active"
  }
}
```

### Python Example

```python
updated_project = client.projects.update(
    project_id="proj_abc123",
    name="Updated Project Name",
    description="Updated description",
    metadata={
        "team": "frontend"
    }
)

print(f"Updated project: {updated_project.name}")
```

## Delete Project

Delete a project and all its associated items and links.

**Warning**: This action is irreversible and will delete all items, links, and data in the project.

### Endpoint

```
DELETE /api/v1/projects/{project_id}
```

### Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | string | Yes | Project ID to delete |

### Request Example

```bash
curl -X DELETE "https://api.tracertm.dev/v1/projects/proj_abc123" \
  -H "Authorization: Bearer $TOKEN"
```

### Response

```json
{
  "success": true,
  "message": "Project deleted successfully"
}
```

### Python Example

```python
result = client.projects.delete("proj_abc123")
print(result.message)  # "Project deleted successfully"
```

## Project Metadata

Projects can include custom metadata:

```json
{
  "metadata": {
    "team": "backend",
    "status": "active",
    "priority": "high",
    "owner": "user_123",
    "tags": ["api", "authentication"],
    "custom_field": "value"
  }
}
```

## Error Responses

### Project Not Found

```json
{
  "error": {
    "code": "not_found",
    "message": "Project not found"
  }
}
```

### Validation Error

```json
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": [
      {
        "field": "name",
        "message": "Name is required"
      }
    ]
  }
}
```

### Permission Denied

```json
{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions to delete project"
  }
}
```

## Best Practices

### 1. Use Descriptive Names

```python
# ✅ Good: Descriptive name
project = client.projects.create(
    name="Authentication System - OAuth 2.0",
    description="OAuth 2.0 authentication implementation"
)

# ❌ Bad: Vague name
project = client.projects.create(name="Project 1")
```

### 2. Organize with Metadata

Use metadata to organize projects:

```python
project = client.projects.create(
    name="Payment Gateway",
    metadata={
        "team": "fintech",
        "status": "active",
        "priority": "high",
        "tags": ["payment", "integration"]
    }
)
```

### 3. Validate Before Delete

Always confirm before deleting:

```python
# Get project details first
project = client.projects.get("proj_abc123")
print(f"Deleting project: {project.name}")

# Confirm deletion
if confirm("Are you sure?"):
    client.projects.delete("proj_abc123")
```

## Related Documentation

- [Items API](./02-artifacts) - Manage items in projects
- [Links API](./04-relationships) - Create relationships
- [Export/Import API](./10-batch-operations) - Export project data
