# 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',
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cubicl.io/api-integration/projects.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.