> 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 group of users. Because of that the word and `group` and the `project` are the same thing in the API.

## Endpoints

## Get Projects

<mark style="color:blue;">`GET`</mark> `https://cubicl.io/api/v1/groups`

#### Query Parameters

| Name      | Type    | Description                                                                                                                                         |
| --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| parent    | string  | <p>Parent project id.</p><p>If not set, gets all projects in the organization.</p>                                                                  |
| recursive | boolean | <p>Set <code>false</code> to get only direct children.</p><p>Set <code>true</code> to get all descendants.</p><p>Default is <code>false</code>.</p> |

{% tabs %}
{% tab title="200: OK Project list" %}

```typescript
Project[]
```

{% endtab %}
{% endtabs %}

## Data

#### Projects

```typescript
type Project = {
    _id: string;
    name: string;
    // Projects can have multiple parents. The root project has no parents.
    parents: string[] | null;
    // Admin user ids
    admins: string[];
    // Member user ids
    members: string[];
    // Child group ids
    groups: string[];
    // Task state definitions. Exists only when states are customized. Read
    // Task States section for more info.
    taskStates?: TaskState[];
    // Permissions set in the project. Only exists when project permissions
    // are customized. Read the Permissions section for more info.
    perms?: {
        members: PermissionLevels,
        everybody: PermissionLevels,
        // An object where keys are userIds and values are permission levels object
        users?: {
            [userId: string]: PermissionLevels,
        }
    }
}
```

#### Task States

```typescript
type TaskState = {
    name: string;
    type: 'waiting' | 'active' | 'completed' | 'suspended';
    color: string; // Hex color code
    textColor: string; // Hex color code
    // Shows whether this is the state tasks will be created in when the task
    // state is not specified in Create Task endpoint.
    isDefault?: boolean;
}
```

If task states are customized in the project, taskStates property will hold the list of task state definition objects. Otherwise, default values below are used.

<pre class="language-typescript"><code class="lang-typescript"><strong>[
</strong>	{
		name : 'cb_waiting',
		type : 'waiting',
		color : '#f39c12',
		textColor : '#fff',
		isDefault : true
	},
	{
		name : 'cb_active',
		type : 'active',
		color : '#2ecc71',
		textColor : '#fff'
	},
	{
		name : 'cb_completed',
		type : 'completed',
		color : '#d8d8d8',
		textColor : '#333'
	},
	{
		name : 'cb_suspended',
		type : 'suspended',
		color : '#7d5fff',
		textColor : '#fff'
	}
]
</code></pre>

#### Permissions

Permissions are set and checked in 4 steps in the following order:

1. Admins: Admins can perform all actions on the project. An admin has admin privilege in all descendant projects as well even if they are not a member of those projects.
2. User Permissions: If permissions are customized for a user, they will be used without checking the following steps. User permissions are available under `perms.users` property.
3. Project Members: General permissions are set for project members and other users. If the user is a project member, these permissions will be used without checking the following step.
4. Non-Project Members: These permission levels are defined in the `perms.everybody` property.

Permission levels are set for each main feature in the project, separately.

```typescript
type FeaturePermLevels = {
    // Used in Tasks, Calendar and Time Chart pages
    tasks: 'none' | 'view' | 'contribute' | 'edit' | 'manage',
    files: 'none' | 'view' | 'edit' | 'manage',
    gantt: 'none' | 'view' | 'edit',
    reports: 'none' | 'view',
}
```