# Projects

## List all projects

> Retrieves a list of all projects accessible by the authenticated user. Projects are returned sorted by creation date (newest first). If an API key is scoped to a specific project, only that project will be returned.\
> \
> \*\*Use Cases:\*\*\
> \- List all projects in your account\
> \- View project organization and structure\
> \- Get project IDs for subsequent device and data operations

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"project.projectItem":{"type":"object","properties":{"created_at":{"description":"Project creation timestamp (ISO 8601 format, UTC)","type":"string"},"description":{"description":"Project description (required, max 500 characters)","type":"string"},"id":{"description":"Unique project identifier (UUID format)","type":"string"},"name":{"description":"Project name (required, max 100 characters)","type":"string"},"tags":{"description":"Optional tags for categorization (alphanumeric and underscore only)","type":"array","items":{"type":"string"}}}}}},"paths":{"/v2/projects":{"get":{"description":"Retrieves a list of all projects accessible by the authenticated user. Projects are returned sorted by creation date (newest first). If an API key is scoped to a specific project, only that project will be returned.\n\n**Use Cases:**\n- List all projects in your account\n- View project organization and structure\n- Get project IDs for subsequent device and data operations","tags":["Projects"],"summary":"List all projects","responses":{"200":{"description":"Projects retrieved successfully - Returns an array of project objects","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/project.projectItem"}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```

## Create a new project

> Creates a new project in your account. Projects are containers for organizing devices and their data. After creation, devices can be added to the project using the devices API.\
> \
> \*\*Required Fields:\*\*\
> \- name: Project name (max 100 characters)\
> \- description: Project description (max 500 characters)\
> \
> \*\*Optional Fields:\*\*\
> \- tags: Array of alphanumeric tags for categorization (e.g., \["production", "us\_west", "temperature\_sensors"])\
> \
> \*\*Permissions:\*\*\
> \- For individual plans: Project created with requester as admin\
> \- For organization plans: Project shared with organization superadmins

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"project.projectItem":{"type":"object","properties":{"created_at":{"description":"Project creation timestamp (ISO 8601 format, UTC)","type":"string"},"description":{"description":"Project description (required, max 500 characters)","type":"string"},"id":{"description":"Unique project identifier (UUID format)","type":"string"},"name":{"description":"Project name (required, max 100 characters)","type":"string"},"tags":{"description":"Optional tags for categorization (alphanumeric and underscore only)","type":"array","items":{"type":"string"}}}}}},"paths":{"/v2/projects":{"post":{"description":"Creates a new project in your account. Projects are containers for organizing devices and their data. After creation, devices can be added to the project using the devices API.\n\n**Required Fields:**\n- name: Project name (max 100 characters)\n- description: Project description (max 500 characters)\n\n**Optional Fields:**\n- tags: Array of alphanumeric tags for categorization (e.g., [\"production\", \"us_west\", \"temperature_sensors\"])\n\n**Permissions:**\n- For individual plans: Project created with requester as admin\n- For organization plans: Project shared with organization superadmins","tags":["Projects"],"summary":"Create a new project","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/project.projectItem"}}},"description":"Project details","required":true},"responses":{"200":{"description":"Project created successfully - Returns the created project with generated ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/project.projectItem"}}}},"400":{"description":"Invalid request body - Check required fields and format","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```

## Get project details

> Retrieves detailed information about a specific project including name, description, creation timestamp, and tags.\
> \
> \*\*Use Cases:\*\*\
> \- View project configuration and metadata\
> \- Verify project details before operations\
> \- Audit project information

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"project.projectItem":{"type":"object","properties":{"created_at":{"description":"Project creation timestamp (ISO 8601 format, UTC)","type":"string"},"description":{"description":"Project description (required, max 500 characters)","type":"string"},"id":{"description":"Unique project identifier (UUID format)","type":"string"},"name":{"description":"Project name (required, max 100 characters)","type":"string"},"tags":{"description":"Optional tags for categorization (alphanumeric and underscore only)","type":"array","items":{"type":"string"}}}}}},"paths":{"/v2/projects/{project_id}":{"get":{"description":"Retrieves detailed information about a specific project including name, description, creation timestamp, and tags.\n\n**Use Cases:**\n- View project configuration and metadata\n- Verify project details before operations\n- Audit project information","tags":["Projects"],"summary":"Get project details","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/project.projectItem"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Project not found or access denied","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```

## Delete a project

> \*\*⚠️ WARNING:\*\* Permanently deletes a project and ALL its associated resources including devices, historical data, dashboards, and configurations. This action cannot be undone.\
> \
> \*\*What Gets Deleted:\*\*\
> \- All devices in the project\
> \- All historical time-series data\
> \- All device configurations and functions\
> \- All aggregated data views\
> \- Project settings and metadata\
> \
> \*\*Prerequisites:\*\*\
> \- Must have admin or owner permissions\
> \- Project must exist and be accessible

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"main.SuccessResponse":{"type":"object","properties":{"action":{"description":"Action that was performed","type":"string"},"message":{"description":"Human-readable success message","type":"string"},"success":{"description":"Operation completed successfully","type":"boolean"}}},"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}":{"delete":{"description":"**⚠️ WARNING:** Permanently deletes a project and ALL its associated resources including devices, historical data, dashboards, and configurations. This action cannot be undone.\n\n**What Gets Deleted:**\n- All devices in the project\n- All historical time-series data\n- All device configurations and functions\n- All aggregated data views\n- Project settings and metadata\n\n**Prerequisites:**\n- Must have admin or owner permissions\n- Project must exist and be accessible","tags":["Projects"],"summary":"Delete a project","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.SuccessResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
```

## Invite users/groups to project

> Share project access with users or groups in your organization. Invited members will receive email notifications and gain access based on their assigned role.\
> \
> \*\*Project Roles:\*\*\
> \
> \| Role | Permissions |\
> \|------|-------------|\
> \| \`owner\` | Full control: read, write, delete, access management, device/function management, aggregated views |\
> \| \`admin\` | Full control: same as owner (read, write, delete, access management, device/function management) |\
> \| \`readwrite\` | Read and modify: read, write, device management, function management, aggregated views (cannot delete project or manage access) |\
> \| \`readonly\` | View only: read project, devices, functions, and aggregated views (no modifications) |\
> \
> \*\*Custom Roles:\*\*\
> In addition to default roles, organizations can create custom roles with specific permission combinations.\
> \
> \*\*Prerequisites:\*\*\
> \- Must have \`access-management\` permission on the project\
> \- Organization plan required for group invitations\
> \- Users must exist in your organization\
> \- Role must be a valid project role ID

```json
{"openapi":"3.0.0","info":{"title":"Qubitro Public API","version":"2.0"},"servers":[{"url":"https://api.qubitro.com"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"description":"Enter your API key with the Bearer prefix, e.g. \"Bearer QB_your_api_key_here\"","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"project.inviteBody":{"type":"object","properties":{"groups":{"description":"List of groups to invite with project roles","type":"array","items":{"$ref":"#/components/schemas/project.Group"}},"users":{"description":"List of users to invite with project roles","type":"array","items":{"$ref":"#/components/schemas/project.User"}}}},"project.Group":{"type":"object","properties":{"id":{"description":"Group ID","type":"string"},"role":{"description":"Project role: \"owner\", \"admin\", \"readwrite\", or \"readonly\"","type":"string"}}},"project.User":{"type":"object","properties":{"email":{"description":"User email address","type":"string"},"role":{"description":"Project role: \"owner\", \"admin\", \"readwrite\", or \"readonly\"","type":"string"}}},"main.SuccessResponse":{"type":"object","properties":{"action":{"description":"Action that was performed","type":"string"},"message":{"description":"Human-readable success message","type":"string"},"success":{"description":"Operation completed successfully","type":"boolean"}}},"main.ErrorResponse":{"type":"object","properties":{"action":{"description":"Action that was attempted","type":"string"},"code":{"description":"Optional error code","type":"string"},"details":{"description":"Optional additional details","type":"string"},"message":{"description":"Human-readable error message","type":"string"},"success":{"description":"Operation failed","type":"boolean"}}}}},"paths":{"/v2/projects/{project_id}/invite":{"post":{"description":"Share project access with users or groups in your organization. Invited members will receive email notifications and gain access based on their assigned role.\n\n**Project Roles:**\n\n| Role | Permissions |\n|------|-------------|\n| `owner` | Full control: read, write, delete, access management, device/function management, aggregated views |\n| `admin` | Full control: same as owner (read, write, delete, access management, device/function management) |\n| `readwrite` | Read and modify: read, write, device management, function management, aggregated views (cannot delete project or manage access) |\n| `readonly` | View only: read project, devices, functions, and aggregated views (no modifications) |\n\n**Custom Roles:**\nIn addition to default roles, organizations can create custom roles with specific permission combinations.\n\n**Prerequisites:**\n- Must have `access-management` permission on the project\n- Organization plan required for group invitations\n- Users must exist in your organization\n- Role must be a valid project role ID","tags":["Projects"],"summary":"Invite users/groups to project","parameters":[{"description":"Project ID (UUID format)","name":"project_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/project.inviteBody"}}},"description":"Users and groups to invite with their project roles","required":true},"responses":{"200":{"description":"Invitation sent successfully - Users will receive email notifications","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.SuccessResponse"}}}},"400":{"description":"Invalid request body - Check email format and role values (must be: owner, admin, readwrite, readonly, or custom role ID)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}},"404":{"description":"Project not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/main.ErrorResponse"}}}}}}}}}
```


---

# 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.qubitro.com/developers/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.