Projects

Create, manage, and collaborate on projects. Projects serve as organizational containers for workspaces, volumes, and team collaboration.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Project Object

{
  "id": "proj_abc123",
  "name": "ML Training Pipeline",
  "description": "End-to-end machine learning training and evaluation project",
  "status": "active",
  "category": "machine-learning",
  "visibility": "private",
  "organizationId": "org_xyz",
  "owner": {
    "id": "user_456",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "ownerId": "user_456",
  "collaborators": [
    {
      "userId": "user_789",
      "role": "editor",
      "email": "bob@example.com",
      "name": "Bob Johnson",
      "addedAt": "2025-01-20T09:00:00Z"
    }
  ],
  "sharedWith": ["user_789"],
  "tags": ["ml", "production"],
  "archived": false,
  "defaultDataVolumeId": "vol_def001",
  "attachedVolumeIds": ["vol_def001", "vol_def002"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/projects

List all projects accessible to the authenticated user.

Scope: projects:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by name or description
status	string	No	Filter by status: active, archived
category	string	No	Filter by category
tag	string	No	Filter by tag
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 12,
  "limit": 20,
  "offset": 0,
  "projects": [
    {
      "id": "proj_abc123",
      "name": "ML Training Pipeline",
      "description": "End-to-end machine learning training and evaluation project",
      "status": "active",
      "category": "machine-learning",
      "visibility": "private",
      "organizationId": "org_xyz",
      "ownerId": "user_456",
      "tags": ["ml", "production"],
      "archived": false,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

POST /api/v1/projects

Create a new project.

Scope: projects:write

Request Body

{
  "name": "ML Training Pipeline",
  "description": "End-to-end machine learning training and evaluation project",
  "category": "machine-learning",
  "visibility": "private",
  "tags": ["ml", "production"]
}

Field	Type	Required	Description
name	string	Yes	Project name
description	string	Yes	Project description
category	string	No	Project category
visibility	string	No	Visibility level: private, organization, public (default: private)
tags	array	No	Array of tag strings

Response 201 Created

{
  "projectId": "proj_abc123"
}

---

GET /api/v1/projects/:id

Get a single project by ID.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

Returns the full Project object.

---

PUT /api/v1/projects/:id

Update an existing project.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Request Body

{
  "name": "Updated ML Pipeline",
  "description": "Updated description",
  "category": "data-engineering",
  "visibility": "organization",
  "tags": ["ml", "v2"]
}

Field	Type	Required	Description
name	string	No	Project name
description	string	No	Project description
category	string	No	Project category
visibility	string	No	Visibility level
tags	array	No	Array of tag strings

Response 200 OK

Returns the updated Project object.

---

DELETE /api/v1/projects/:id

Delete a project. This action is irreversible.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 204 No Content

---

POST /api/v1/projects/:id/archive

Archive a project. Archived projects are hidden from default listings but can be restored.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

{
  "message": "Project archived successfully",
  "projectId": "proj_abc123",
  "status": "archived"
}

---

POST /api/v1/projects/:id/restore

Restore an archived project.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

{
  "message": "Project restored successfully",
  "projectId": "proj_abc123",
  "status": "active"
}

---

GET /api/v1/projects/:id/stats

Get aggregate statistics for a project.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

{
  "workspaceCount": 5,
  "volumeCount": 3,
  "totalStorageGb": 128.5,
  "activeWorkspaces": 2
}

---

GET /api/v1/projects/:id/activity

Get the activity log for a project. Returns a paginated list of actions performed within the project.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)

Response 200 OK

{
  "count": 87,
  "limit": 20,
  "offset": 0,
  "activity": [
    {
      "id": "act_001",
      "action": "workspace.created",
      "userId": "user_456",
      "userName": "Jane Smith",
      "details": "Created workspace 'Training Environment'",
      "timestamp": "2025-02-01T14:22:00Z"
    }
  ]
}

---

GET /api/v1/projects/:id/collaborators

List all collaborators on a project.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

{
  "projectId": "proj_abc123",
  "collaborators": [
    {
      "userId": "user_789",
      "role": "editor",
      "email": "bob@example.com",
      "name": "Bob Johnson",
      "addedAt": "2025-01-20T09:00:00Z"
    }
  ]
}

---

POST /api/v1/projects/:id/collaborators

Add a collaborator to a project.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Request Body

{
  "email": "bob@example.com",
  "role": "editor",
  "userId": "user_789"
}

Field	Type	Required	Description
email	string	Yes	Email address of the collaborator
role	string	Yes	Collaborator role: viewer, editor, admin
userId	string	No	User ID (if known; otherwise the user is looked up by email)

Response 201 Created

{
  "message": "Collaborator added successfully",
  "projectId": "proj_abc123",
  "userId": "user_789",
  "role": "editor"
}

---

DELETE /api/v1/projects/:id/collaborators/:userId

Remove a collaborator from a project.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID
userId	string	Yes	User ID of the collaborator to remove

Response 204 No Content

---

PUT /api/v1/projects/:id/collaborators/:userId

Update a collaborator's role on a project.

Scope: projects:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID
userId	string	Yes	User ID of the collaborator

Request Body

{
  "role": "admin"
}

Field	Type	Required	Description
role	string	Yes	New role: viewer, editor, admin

Response 200 OK

{
  "message": "Collaborator role updated",
  "projectId": "proj_abc123",
  "userId": "user_789",
  "role": "admin"
}

---

GET /api/v1/projects/:id/volumes

List all volumes attached to a project.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Response 200 OK

{
  "projectId": "proj_abc123",
  "volumes": [
    {
      "id": "vol_def001",
      "label": "Training Data",
      "name": "training-data",
      "type": "data",
      "sizeGb": 64,
      "status": "bound",
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ]
}

---

GET /api/v1/projects/:id/workspaces

List all workspaces within a project. Returns a paginated list.

Scope: projects:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Project ID

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)

Response 200 OK

{
  "count": 5,
  "limit": 20,
  "offset": 0,
  "projectId": "proj_abc123",
  "workspaces": [
    {
      "id": "ws_ghi789",
      "name": "Training Environment",
      "description": "GPU-enabled workspace for model training",
      "status": "running",
      "environmentType": "jupyter",
      "projectId": "proj_abc123",
      "createdAt": "2025-01-16T11:00:00Z",
      "updatedAt": "2025-02-01T08:00:00Z"
    }
  ]
}