HTTP API: projects

The 11 operations tagged projects, each with its parameters, its body and what it answers.

List projects

GET /v1/projects

List the projects this caller can see.

Parameters

• workspace_id (string or null, in query): Which workspace, by id or slug.
• parent (string or null, in query): Only projects directly inside this one.
• visibility (string or null, in query): 'public' or 'private'.
• include_archived (boolean, in query): Include archived projects.
• order (string or null, in query): Comma-separated sort fields, '-' reverses.
• limit (integer or null, in query): How many to return. At least 1; capped at the instance's max_page_size.
• cursor (string or null, in query): Continue after a previous page.
• include_total (boolean, in query): Count the whole result.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Collection_Project_. Successful Response
• 422: HTTPValidationError. Validation Error

Create a project

POST /v1/projects

Create a project, optionally inside another.

Request body: Create as application/json, required.

Responses

• 201: Project. Successful Response
• 422: HTTPValidationError. Validation Error

Read one project

GET /v1/projects/{id_or_key}

Return one project, by id or by key.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Project. Successful Response
• 422: HTTPValidationError. Validation Error

Change a project

PATCH /v1/projects/{id_or_key}

Change a project. Omitted fields are untouched; nulls clear (docs/design.md §8.3).

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Request body: Update as application/json, required.

Responses

• 200: Project. Successful Response
• 422: HTTPValidationError. Validation Error

Move a project to the trash

DELETE /v1/projects/{id_or_key}

Soft-delete a project. Its tasks leave the visible world with it, and return with it.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Responses

• 200: Project. Successful Response
• 422: HTTPValidationError. Validation Error

Who can see this project

GET /v1/projects/{id_or_key}/members

List who has been shared into this project.

Needs project:read. Nothing anywhere else answers who can see this, and until this existed the question had no home on any surface.

Enveloped and unpaginated, like a workspace's members and a task's links (§8.4) — a project's membership is bounded by how many people somebody put in it.

A public project ordinarily reports just its owner, and that is honest rather than misleading. The rows say who would still see it if somebody made it private, which is exactly the question anybody about to do that is asking.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.
• format (string or null, in query): 'full' (default), 'compact' for one aligned line per item, or 'ids' for the addresses alone. Compact is roughly a twentieth the size of full.
• fields (string or null, in query): Comma-separated field names to return instead of the whole item, e.g. 'ref,title,due_at'. GET /v1/meta lists what each entity has. Cannot be combined with 'format'.

Responses

• 200: Collection_ProjectMember_. Successful Response
• 422: HTTPValidationError. Validation Error

Let somebody see a private project

POST /v1/projects/{id_or_key}/members

Share a private project with one more person.

Needs project:write, and so does the DELETE. Anybody holding it can already publish the whole project to the workspace by changing its visibility, so naming one person is strictly less disclosure than a flag they have anyway.

Sight only. The row grants nothing but the ability to see the project and what is in it; what somebody may do there is still their workspace role.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Request body: Share as application/json, required.

Responses

• 201: ProjectMember. Successful Response
• 422: HTTPValidationError. Validation Error

Stop somebody seeing a private project

DELETE /v1/projects/{id_or_key}/members/{username}

Take one person's sight of a project away again.

Neither the owner's own row nor the last remaining one can be removed: a private project with no member is one that nobody — including whoever runs the instance — can see or make public again.

Works whatever the project's visibility is. A row on a public project grants nothing today and everything the day somebody makes it private, so leaving it there is deliberate.

Parameters

• id_or_key (string, in path, required)
• username (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Responses

• 204: Successful Response
• 422: HTTPValidationError. Validation Error

Move a project in the tree

POST /v1/projects/{id_or_key}/move

Reparent a project, taking its whole subtree with it.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Request body: Move as application/json, required.

Responses

• 200: Project. Successful Response
• 422: HTTPValidationError. Validation Error

Take a project out of the trash

POST /v1/projects/{id_or_key}/restore

Restore a soft-deleted project, and everything filed in it (docs/design.md §6.9).

DELETE has always said its tasks "come back with it" and nothing brought them back. Tasks and documents gained a restore before their container did, so deleting a project removed every item inside it by a route that read as reversible and was not.

Registered before the parameterised routes below it for routing.check's reason, and POST rather than DELETE ?restore= because it is not a deletion of anything.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Responses

• 200: Project. Successful Response
• 422: HTTPValidationError. Validation Error

What is in force in this project, and where it came from

GET /v1/projects/{id_or_key}/settings

Every setting this project may carry, as it applies here, and where each value came from.

A project inherits what it does not state from the nearest project above it that does, and then from its workspace. Each setting says which of those answered — this project, an ancestor named by its address, the workspace, or nobody, in which case the default applies — because chose grey and inherits grey look the same and are cleared differently.

Needs project:read.

Parameters

• id_or_key (string, in path, required)
• workspace_id (string or null, in query): Which workspace, by id or slug.

Responses

• 200: SettingsInForce. Successful Response
• 422: HTTPValidationError. Validation Error