# Projects

Projects help you organize maps and manage team permissions.

With these APIs, you can manage the projects in your workspace.

## List projects

> Retrieve all projects accessible to the authenticated user within the workspace.

```json
{"openapi":"3.0.0","info":{"title":"Felt","version":"2.0"},"tags":[{"description":"Projects help you organize maps and manage team permissions.\n\nWith these APIs, you can manage the projects in your workspace.\n","name":"Projects"}],"servers":[{"url":"https://felt.com","variables":{}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"YOUR_API_KEY","scheme":"bearer","type":"http"}},"schemas":{"ProjectReferenceList":{"items":{"$ref":"#/components/schemas/ProjectReference"},"title":"ProjectReferenceList","type":"array"},"ProjectReference":{"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/FeltID"},"links":{"properties":{"self":{"type":"string"}},"type":"object"},"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects.","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"type":"string"},"type":{"enum":["project_reference"],"type":"string"},"visibility":{"enum":["workspace","private"],"type":"string"}},"required":["id","type","name","visibility","max_inherited_permission"],"title":"ProjectReference","type":"object"},"FeltID":{"format":"felt_id","nullable":false,"title":"FeltID","type":"string"},"UnauthorizedError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"header":{"enum":["authorization"],"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"UnauthorizedError","type":"object"},"NotFoundError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"NotFoundError","type":"object"},"JsonErrorResponse":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"pointer":{"type":"string"}},"required":["pointer"],"type":"object"},"title":{"type":"string"}},"required":["title","source","detail"],"type":"object"},"type":"array"}},"required":["errors"],"title":"JsonErrorResponse","type":"object"},"InternalServerError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"InternalServerError","type":"object"}}},"paths":{"/api/v2/projects":{"get":{"callbacks":{},"description":"Retrieve all projects accessible to the authenticated user within the workspace.","operationId":"list_projects","parameters":[{"description":"Only needed when using the API as part of a plugin","in":"query","name":"workspace_id","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectReferenceList"}}},"description":"Projects"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}},"description":"NotFoundError"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}},"description":"InternalServerError"}},"summary":"List projects","tags":["Projects"]}}}}
```

## Create project

> Create a new project with specified name and visibility settings within the workspace.

```json
{"openapi":"3.0.0","info":{"title":"Felt","version":"2.0"},"tags":[{"description":"Projects help you organize maps and manage team permissions.\n\nWith these APIs, you can manage the projects in your workspace.\n","name":"Projects"}],"servers":[{"url":"https://felt.com","variables":{}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"YOUR_API_KEY","scheme":"bearer","type":"http"}},"schemas":{"ProjectCreateParams":{"additionalProperties":false,"properties":{"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects. Only applicable when visibility is \"workspace\".","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"description":"The name to be used for the Project","type":"string"},"visibility":{"description":"Either viewable by all members of the workspace, or private to users who are invited.","enum":["workspace","private"],"type":"string"}},"required":["name","visibility"],"title":"ProjectCreateParams","type":"object"},"Project":{"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/FeltID"},"maps":{"items":{"$ref":"#/components/schemas/MapReference"},"type":"array"},"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects.","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"type":"string"},"type":{"enum":["project"],"type":"string"},"visibility":{"enum":["workspace","private"],"type":"string"}},"required":["id","type","name","visibility","max_inherited_permission","maps"],"title":"Project","type":"object"},"FeltID":{"format":"felt_id","nullable":false,"title":"FeltID","type":"string"},"MapReference":{"additionalProperties":false,"properties":{"created_at":{"format":"date_time","type":"string"},"folder_id":{"nullable":true,"type":"string"},"id":{"$ref":"#/components/schemas/FeltID"},"links":{"properties":{"self":{"type":"string"}},"type":"object"},"project_id":{"nullable":false,"type":"string"},"public_access":{"enum":["private","view_only","view_and_comment","view_comment_and_edit"],"type":"string"},"thumbnail_url":{"description":"A static thumbnail image of the map","nullable":true,"type":"string"},"title":{"type":"string"},"type":{"enum":["map_reference"],"type":"string"},"url":{"type":"string"},"visited_at":{"format":"date_time","nullable":true,"type":"string"}},"required":["id","type","url","title","thumbnail_url","created_at","visited_at","project_id","folder_id","public_access"],"title":"MapReference","type":"object"},"UnauthorizedError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"header":{"enum":["authorization"],"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"UnauthorizedError","type":"object"},"NotFoundError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"NotFoundError","type":"object"},"JsonErrorResponse":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"pointer":{"type":"string"}},"required":["pointer"],"type":"object"},"title":{"type":"string"}},"required":["title","source","detail"],"type":"object"},"type":"array"}},"required":["errors"],"title":"JsonErrorResponse","type":"object"},"InternalServerError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"InternalServerError","type":"object"}}},"paths":{"/api/v2/projects":{"post":{"callbacks":{},"description":"Create a new project with specified name and visibility settings within the workspace.","operationId":"create_project","parameters":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectCreateParams"}}},"description":"Project create params","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"Project"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}},"description":"NotFoundError"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}},"description":"InternalServerError"}},"summary":"Create project","tags":["Projects"]}}}}
```

## Get project

> Retrieve detailed information about a specific project including metadata, permissions, and references to the maps in the project.

```json
{"openapi":"3.0.0","info":{"title":"Felt","version":"2.0"},"tags":[{"description":"Projects help you organize maps and manage team permissions.\n\nWith these APIs, you can manage the projects in your workspace.\n","name":"Projects"}],"servers":[{"url":"https://felt.com","variables":{}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"YOUR_API_KEY","scheme":"bearer","type":"http"}},"schemas":{"Project":{"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/FeltID"},"maps":{"items":{"$ref":"#/components/schemas/MapReference"},"type":"array"},"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects.","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"type":"string"},"type":{"enum":["project"],"type":"string"},"visibility":{"enum":["workspace","private"],"type":"string"}},"required":["id","type","name","visibility","max_inherited_permission","maps"],"title":"Project","type":"object"},"FeltID":{"format":"felt_id","nullable":false,"title":"FeltID","type":"string"},"MapReference":{"additionalProperties":false,"properties":{"created_at":{"format":"date_time","type":"string"},"folder_id":{"nullable":true,"type":"string"},"id":{"$ref":"#/components/schemas/FeltID"},"links":{"properties":{"self":{"type":"string"}},"type":"object"},"project_id":{"nullable":false,"type":"string"},"public_access":{"enum":["private","view_only","view_and_comment","view_comment_and_edit"],"type":"string"},"thumbnail_url":{"description":"A static thumbnail image of the map","nullable":true,"type":"string"},"title":{"type":"string"},"type":{"enum":["map_reference"],"type":"string"},"url":{"type":"string"},"visited_at":{"format":"date_time","nullable":true,"type":"string"}},"required":["id","type","url","title","thumbnail_url","created_at","visited_at","project_id","folder_id","public_access"],"title":"MapReference","type":"object"},"UnauthorizedError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"header":{"enum":["authorization"],"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"UnauthorizedError","type":"object"},"NotFoundError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"NotFoundError","type":"object"},"JsonErrorResponse":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"pointer":{"type":"string"}},"required":["pointer"],"type":"object"},"title":{"type":"string"}},"required":["title","source","detail"],"type":"object"},"type":"array"}},"required":["errors"],"title":"JsonErrorResponse","type":"object"},"InternalServerError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"InternalServerError","type":"object"}}},"paths":{"/api/v2/projects/{project_id}":{"get":{"callbacks":{},"description":"Retrieve detailed information about a specific project including metadata, permissions, and references to the maps in the project.","operationId":"show_project","parameters":[{"description":"","in":"path","name":"project_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"Project"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}},"description":"NotFoundError"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}},"description":"InternalServerError"}},"summary":"Get project","tags":["Projects"]}}}}
```

## Delete project

> Permanently delete a project and all its contained maps and folders.\
> \
> {% hint style="danger" %}\
> Caution: Deleting a project deletes all of the folders and maps inside!\
> {% endhint %}<br>

```json
{"openapi":"3.0.0","info":{"title":"Felt","version":"2.0"},"tags":[{"description":"Projects help you organize maps and manage team permissions.\n\nWith these APIs, you can manage the projects in your workspace.\n","name":"Projects"}],"servers":[{"url":"https://felt.com","variables":{}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"YOUR_API_KEY","scheme":"bearer","type":"http"}},"schemas":{"UnauthorizedError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"header":{"enum":["authorization"],"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"UnauthorizedError","type":"object"},"NotFoundError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"NotFoundError","type":"object"},"JsonErrorResponse":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"pointer":{"type":"string"}},"required":["pointer"],"type":"object"},"title":{"type":"string"}},"required":["title","source","detail"],"type":"object"},"type":"array"}},"required":["errors"],"title":"JsonErrorResponse","type":"object"},"InternalServerError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"InternalServerError","type":"object"}}},"paths":{"/api/v2/projects/{project_id}":{"delete":{"callbacks":{},"description":"Permanently delete a project and all its contained maps and folders.\n\n{% hint style=\"danger\" %}\nCaution: Deleting a project deletes all of the folders and maps inside!\n{% endhint %}\n","operationId":"delete_project","parameters":[{"description":"The ID of the Project to delete. Note: This will delete all Folders and Maps inside the project!","in":"path","name":"project_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}},"description":"NotFoundError"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}},"description":"InternalServerError"}},"summary":"Delete project","tags":["Projects"]}}}}
```

## Update project

> Update project properties including name and visibility settings.

```json
{"openapi":"3.0.0","info":{"title":"Felt","version":"2.0"},"tags":[{"description":"Projects help you organize maps and manage team permissions.\n\nWith these APIs, you can manage the projects in your workspace.\n","name":"Projects"}],"servers":[{"url":"https://felt.com","variables":{}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"bearerFormat":"YOUR_API_KEY","scheme":"bearer","type":"http"}},"schemas":{"ProjectUpdateParams":{"additionalProperties":false,"properties":{"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects. Only applicable when visibility is \"workspace\".","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"description":"The name to be used for the Project","type":"string"},"visibility":{"description":"Either viewable by all members of the workspace, or private to users who are invited.","enum":["workspace","private"],"type":"string"}},"title":"ProjectUpdateParams","type":"object"},"Project":{"additionalProperties":false,"properties":{"id":{"$ref":"#/components/schemas/FeltID"},"maps":{"items":{"$ref":"#/components/schemas/MapReference"},"type":"array"},"max_inherited_permission":{"description":"The maximum permission level workspace members inherit on team-visible projects.","enum":["view_only","view_and_contribute","view_and_edit"],"nullable":false,"type":"string"},"name":{"type":"string"},"type":{"enum":["project"],"type":"string"},"visibility":{"enum":["workspace","private"],"type":"string"}},"required":["id","type","name","visibility","max_inherited_permission","maps"],"title":"Project","type":"object"},"FeltID":{"format":"felt_id","nullable":false,"title":"FeltID","type":"string"},"MapReference":{"additionalProperties":false,"properties":{"created_at":{"format":"date_time","type":"string"},"folder_id":{"nullable":true,"type":"string"},"id":{"$ref":"#/components/schemas/FeltID"},"links":{"properties":{"self":{"type":"string"}},"type":"object"},"project_id":{"nullable":false,"type":"string"},"public_access":{"enum":["private","view_only","view_and_comment","view_comment_and_edit"],"type":"string"},"thumbnail_url":{"description":"A static thumbnail image of the map","nullable":true,"type":"string"},"title":{"type":"string"},"type":{"enum":["map_reference"],"type":"string"},"url":{"type":"string"},"visited_at":{"format":"date_time","nullable":true,"type":"string"}},"required":["id","type","url","title","thumbnail_url","created_at","visited_at","project_id","folder_id","public_access"],"title":"MapReference","type":"object"},"UnauthorizedError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"header":{"enum":["authorization"],"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"UnauthorizedError","type":"object"},"NotFoundError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"NotFoundError","type":"object"},"JsonErrorResponse":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"pointer":{"type":"string"}},"required":["pointer"],"type":"object"},"title":{"type":"string"}},"required":["title","source","detail"],"type":"object"},"type":"array"}},"required":["errors"],"title":"JsonErrorResponse","type":"object"},"InternalServerError":{"properties":{"errors":{"items":{"properties":{"detail":{"type":"string"},"source":{"properties":{"parameter":{"type":"string"}},"type":"object"},"title":{"type":"string"}},"type":"object"},"type":"array"}},"title":"InternalServerError","type":"object"}}},"paths":{"/api/v2/projects/{project_id}/update":{"post":{"callbacks":{},"description":"Update project properties including name and visibility settings.","operationId":"update_project","parameters":[{"description":"The ID of the project to update","in":"path","name":"project_id","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectUpdateParams"}}},"description":"Project update params","required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}},"description":"Project"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}},"description":"UnauthorizedError"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotFoundError"}}},"description":"NotFoundError"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonErrorResponse"}}},"description":"Unprocessable Entity"},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerError"}}},"description":"InternalServerError"}},"summary":"Update project","tags":["Projects"]}}}}
```