> For the complete documentation index, see [llms.txt](https://docs.cubicl.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cubicl.io/api-integration/projects.md).

# Projects

Projects are created as a user group. In the API, `group` and `project` mean the same thing.

## List projects

> Returns projects in the organization. If \`parent\` is omitted, the organization's main project is returned.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Projects are created as a user group. In the API, `group` and `project` mean the same thing."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"ProjectList":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"Project":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/ObjectId"},"name":{"type":"string"},"parents":{"type":"array","items":{"type":"string"},"nullable":true,"description":"The main project has no parent"},"admins":{"type":"array","items":{"type":"string"}},"members":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"},"description":"Subproject IDs"},"gantt":{"type":"string"},"private":{"type":"boolean"},"orgId":{"type":"string"},"no":{"type":"string","description":"Project number"},"typeId":{"type":"string","description":"`pt-client`, `pt-design`, `pt-randd`, `pt-sales`, `pt-standard`, or custom"},"status":{"type":"string","enum":["waiting","active","completed"]},"priority":{"type":"string","enum":["low","medium","high","critical"]},"icon":{"type":"string"},"estimatedFinish":{"type":"number","nullable":true},"workDays":{"type":"array","items":{"type":"boolean"},"description":"Monday–Sunday"},"workHours":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"}}},"workTimesActive":{"type":"boolean"},"taskStates":{"type":"array","items":{"$ref":"#/components/schemas/TaskState"}},"perms":{"type":"object","properties":{"members":{"$ref":"#/components/schemas/PermissionLevels"},"everybody":{"$ref":"#/components/schemas/PermissionLevels"},"users":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PermissionLevels"}}}},"archivedAt":{"type":"number"},"customerId":{"type":"string"},"customTaskFields":{"type":"array","items":{"$ref":"#/components/schemas/CustomTaskField"}},"taskShownFields":{"type":"object"},"customFieldValues":{"type":"object","additionalProperties":true},"autoArchivingEnabled":{"type":"boolean"},"estimatedTimeEnabled":{"type":"boolean"},"autoAddingGanttChartSettings":{"type":"string","enum":["none","only-with-dates","all"]},"autoChangeSupportRequestState":{"type":"object"},"defaultPage":{"type":"string"},"defaultTaskView":{"type":"string"},"hiddenPages":{"type":"array","items":{"type":"string"}}}},"TaskState":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["waiting","active","completed","suspended","cancelled"]},"color":{"type":"string","description":"Hex color"},"textColor":{"type":"string"},"isDefault":{"type":"boolean"}}},"PermissionLevels":{"type":"object","properties":{"tasks":{"type":"string","enum":["none","view","contribute","edit","manage"]},"files":{"type":"string","enum":["none","view","edit","manage"]},"gantt":{"type":"string","enum":["none","view","edit"]},"reports":{"type":"string","enum":["none","view"]}}},"CustomTaskField":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"deleted":{"type":"boolean","description":"Deleted in the UI but still shown on tasks where it has a value"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/groups":{"get":{"tags":["Projects"],"summary":"List projects","operationId":"listProjects","parameters":[{"name":"parent","in":"query","description":"Parent project ID. If omitted, the organization's main project is returned.","schema":{"$ref":"#/components/schemas/ObjectId"}},{"name":"recursive","in":"query","description":"`false`: first-level subprojects only. `true`: all levels.","schema":{"type":"boolean","default":false}},{"name":"onlyNonArchived","in":"query","description":"`true`: non-archived projects only.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"Project list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectList"}}}},"422":{"$ref":"#/components/responses/ValidationFailed"}},"description":"Returns projects in the organization. If `parent` is omitted, the organization's main project is returned."}}}}
```

## Get project by ID

> Returns the project with the given ID. Returns 403 for projects the user cannot access or that belong to another organization.

```json
{"openapi":"3.0.3","info":{"title":"Cubicl API","version":"1.0.0"},"tags":[{"name":"Projects","description":"Projects are created as a user group. In the API, `group` and `project` mean the same thing."}],"servers":[{"url":"https://cubicl.io/api/v1","description":"Cubicl production API"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Access token from the Integrations page. Header: `Authorization: Bearer YOUR_ACCESS_TOKEN`."}},"parameters":{"IdPath":{"name":"id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ObjectId"},"description":"Record ID"}},"schemas":{"ObjectId":{"type":"string","description":"MongoDB ObjectId"},"Project":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/ObjectId"},"name":{"type":"string"},"parents":{"type":"array","items":{"type":"string"},"nullable":true,"description":"The main project has no parent"},"admins":{"type":"array","items":{"type":"string"}},"members":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"string"},"description":"Subproject IDs"},"gantt":{"type":"string"},"private":{"type":"boolean"},"orgId":{"type":"string"},"no":{"type":"string","description":"Project number"},"typeId":{"type":"string","description":"`pt-client`, `pt-design`, `pt-randd`, `pt-sales`, `pt-standard`, or custom"},"status":{"type":"string","enum":["waiting","active","completed"]},"priority":{"type":"string","enum":["low","medium","high","critical"]},"icon":{"type":"string"},"estimatedFinish":{"type":"number","nullable":true},"workDays":{"type":"array","items":{"type":"boolean"},"description":"Monday–Sunday"},"workHours":{"type":"object","properties":{"start":{"type":"number"},"end":{"type":"number"}}},"workTimesActive":{"type":"boolean"},"taskStates":{"type":"array","items":{"$ref":"#/components/schemas/TaskState"}},"perms":{"type":"object","properties":{"members":{"$ref":"#/components/schemas/PermissionLevels"},"everybody":{"$ref":"#/components/schemas/PermissionLevels"},"users":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/PermissionLevels"}}}},"archivedAt":{"type":"number"},"customerId":{"type":"string"},"customTaskFields":{"type":"array","items":{"$ref":"#/components/schemas/CustomTaskField"}},"taskShownFields":{"type":"object"},"customFieldValues":{"type":"object","additionalProperties":true},"autoArchivingEnabled":{"type":"boolean"},"estimatedTimeEnabled":{"type":"boolean"},"autoAddingGanttChartSettings":{"type":"string","enum":["none","only-with-dates","all"]},"autoChangeSupportRequestState":{"type":"object"},"defaultPage":{"type":"string"},"defaultTaskView":{"type":"string"},"hiddenPages":{"type":"array","items":{"type":"string"}}}},"TaskState":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string","enum":["waiting","active","completed","suspended","cancelled"]},"color":{"type":"string","description":"Hex color"},"textColor":{"type":"string"},"isDefault":{"type":"boolean"}}},"PermissionLevels":{"type":"object","properties":{"tasks":{"type":"string","enum":["none","view","contribute","edit","manage"]},"files":{"type":"string","enum":["none","view","edit","manage"]},"gantt":{"type":"string","enum":["none","view","edit"]},"reports":{"type":"string","enum":["none","view"]}}},"CustomTaskField":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"deleted":{"type":"boolean","description":"Deleted in the UI but still shown on tasks where it has a value"}}},"ErrorCodeMessage":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer","description":"Application error code. Not an HTTP status code."},"message":{"type":"string"}}},"ValidationError":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}},"responses":{"Forbidden":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorCodeMessage"}}}},"NotFound":{"description":"Not found"},"ValidationFailed":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/groups/{id}":{"get":{"tags":["Projects"],"summary":"Get project by ID","description":"Returns the project with the given ID. Returns 403 for projects the user cannot access or that belong to another organization.","operationId":"getProject","parameters":[{"$ref":"#/components/parameters/IdPath"}],"responses":{"200":{"description":"Project details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}}}}
```
