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.

curl "https://app.corbulo.dev/api/v1/projects" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

[
  {
    "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"
  }
]

Get Project

Returns a single project by ID.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

{
  "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"
}

Create Project

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

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"
  }'

{
  "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"
}

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.

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"
  }'

{
  "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"
}

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.

curl -X DELETE "https://app.corbulo.dev/api/v1/projects/d4e5f6a7-8901-2345-6789-abcdef012345" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

Returns 204 No Content on success.

List Members

Returns all members of a project.

curl "https://app.corbulo.dev/api/v1/projects/b3d7f1a2-4e5c-6d8a-9b0c-1e2f3a4b5c6d/members" \
  -H "Authorization: Bearer ok_live_a1b2c3d4e5f6..."

[
  {
    "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"
  }
]

Invite Member

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

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"
  }'

{
  "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"
}

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.

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"
  }'

{
  "status": "ok"
}

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.

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..."

Returns 204 No Content on success.

​Projects API

​List Projects

​Get Project

​Create Project

​Request Body

​Update Project

​Request Body

​Delete Project

​List Members

​Invite Member

​Request Body

​Update Member Role

​Request Body

​Remove Member

Projects API

List Projects

Get Project

Create Project

Request Body

Update Project

Request Body

Delete Project

List Members

Invite Member

Request Body

Update Member Role

Request Body

Remove Member