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

# Projects API

> Manage projects and team members

# Projects API

Projects are the top-level organizational unit in Corbulo. Each project contains repositories, health assessments, PR analyses, and team members.

***

## List Projects

Returns all projects the authenticated user belongs to.

<CodeGroup>
  ```bash Request theme={null}
  curl "https://app.corbulo.dev/api/v1/projects" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```

  ```json Response theme={null}
  [
    {
      "id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
      "name": "Corbulo",
      "key": "corbulo",
      "description": "Technical debt intelligence platform",
      "settings": {},
      "user_role": "owner",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-03-01T14:22:00Z"
    },
    {
      "id": "a1c2e3f4-5678-9abc-def0-123456789abc",
      "name": "Spring Petclinic",
      "key": "spring-petclinic",
      "description": "Sample Spring Boot application",
      "settings": {},
      "user_role": "member",
      "created_at": "2026-02-20T08:00:00Z",
      "updated_at": "2026-02-28T16:45:00Z"
    }
  ]
  ```
</CodeGroup>

***

## Get Project

Returns a single project by ID.

<CodeGroup>
  ```bash Request theme={null}
  curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```

  ```json Response theme={null}
  {
    "id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
    "name": "Corbulo",
    "key": "corbulo",
    "description": "Technical debt intelligence platform",
    "settings": {},
    "user_role": "owner",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-03-01T14:22:00Z"
  }
  ```
</CodeGroup>

***

## Create Project

Creates a new project and adds the authenticated user as owner.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My New Project",
      "key": "my-new-project",
      "description": "A project for analyzing our backend services"
    }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "d4e5f6a7-8901-2345-6789-abcdef012345",
    "name": "My New Project",
    "key": "my-new-project",
    "description": "A project for analyzing our backend services",
    "settings": {},
    "user_role": "owner",
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:00:00Z"
  }
  ```
</CodeGroup>

### Request Body

| Field         | Type   | Required | Description                   |
| ------------- | ------ | -------- | ----------------------------- |
| `name`        | string | yes      | Project display name          |
| `key`         | string | yes      | URL-safe project key (unique) |
| `description` | string | no       | Project description           |

***

## Update Project

Updates a project's name, description, or settings. Only provided fields are updated.

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Corbulo Platform",
      "description": "Updated description"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
    "name": "Corbulo Platform",
    "key": "corbulo",
    "description": "Updated description",
    "settings": {},
    "user_role": "owner",
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-03-10T12:05:00Z"
  }
  ```
</CodeGroup>

### Request Body

| Field         | Type   | Required | Description                    |
| ------------- | ------ | -------- | ------------------------------ |
| `name`        | string | no       | New project name               |
| `description` | string | no       | New project description        |
| `settings`    | object | no       | Project settings (JSON object) |

***

## Delete Project

Deletes a project. The authenticated user must be a project owner.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "https://app.corbulo.dev/api/v1/projects/d4e5f6a7-8901-2345-6789-abcdef012345" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```
</CodeGroup>

Returns `204 No Content` on success.

***

## List Members

Returns all members of a project.

<CodeGroup>
  ```bash Request theme={null}
  curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/members" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```

  ```json Response theme={null}
  [
    {
      "id": "c1d2e3f4-5678-9abc-def0-111111111111",
      "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
      "user_id": "a0b1c2d3-4567-89ab-cdef-000000000001",
      "role": "owner",
      "created_at": "2026-01-15T10:30:00Z"
    },
    {
      "id": "c1d2e3f4-5678-9abc-def0-222222222222",
      "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
      "user_id": "a0b1c2d3-4567-89ab-cdef-000000000002",
      "role": "member",
      "created_at": "2026-02-01T09:15:00Z"
    }
  ]
  ```
</CodeGroup>

***

## Invite Member

Sends an invitation to join a project. The invited user receives access once they accept.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/invitations" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "email": "teammate@example.com",
      "role": "member"
    }'
  ```

  ```json Response (201 Created) theme={null}
  {
    "id": "e5f6a7b8-9012-3456-7890-abcdef123456",
    "project_id": "b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d",
    "email": "teammate@example.com",
    "role": "member",
    "invited_by_user_id": "a0b1c2d3-4567-89ab-cdef-000000000001",
    "status": "pending",
    "expires_at": "2026-03-17T12:00:00Z",
    "created_at": "2026-03-10T12:00:00Z"
  }
  ```
</CodeGroup>

### Request Body

| Field   | Type   | Required | Description                                                |
| ------- | ------ | -------- | ---------------------------------------------------------- |
| `email` | string | yes      | Email address to invite                                    |
| `role`  | string | no       | Role to assign: `owner` or `member` (defaults to `member`) |

***

## Update Member Role

Changes a member's role in a project. The authenticated user must be a project owner.

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/members/a0b1c2d3-4567-89ab-cdef-000000000002" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "role": "owner"
    }'
  ```

  ```json Response theme={null}
  {
    "status": "ok"
  }
  ```
</CodeGroup>

### Request Body

| Field  | Type   | Required | Description                   |
| ------ | ------ | -------- | ----------------------------- |
| `role` | string | yes      | New role: `owner` or `member` |

***

## Remove Member

Removes a user from a project. Returns `409 Conflict` if attempting to remove the last owner.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/members/a0b1c2d3-4567-89ab-cdef-000000000002" \
    -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."
  ```
</CodeGroup>

Returns `204 No Content` on success.