HTTP API: instance

The 4 operations tagged instance, each with its parameters, its body and what it answers.

Change what this installation is called

PATCH /v1/instance

Change this installation's name or its timezone.

Needs instance:admin, which no role carries and only a superuser holds. Deciding what a whole installation is called is not something a member of one workspace in it should be able to do.

An omitted field is left alone, and neither may be set to nothing.

Request body: Update as application/json, required.

Responses

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

Workspaces nobody here can administer

GET /v1/instance/unadministered-workspaces

List the workspaces that nobody who can act may administer.

Needs instance:admin, which no role carries and only a superuser holds, and a credential that is not pinned to one workspace.

An administrator here is somebody whose role in the workspace may administer it and who can still act: not deactivated, and not an agent whose person has been. A workspace with none still works for its members, and none of them can add, regrade or remove a member, or delete it. An administrator of this installation can make somebody its administrator again, themselves included, with POST /v1/workspaces/{id_or_slug}/members or by changing a member's role, whether or not they belong to it.

With leaving, it answers the question to ask before deactivating somebody instead: which workspaces somebody can administer now would nobody be able to administer afterwards.

Parameters

• leaving (string or null, in query): Instead, the ones that would be left with nobody to administer them if this person left.
• 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_WorkspaceOnInstance_. Successful Response
• 422: HTTPValidationError. Validation Error

Private projects nobody here can reach

GET /v1/instance/unreachable-projects

List the private projects that no member who can still act is able to see.

Needs instance:admin, which no role carries and only a superuser holds, and a credential that is neither pinned to one workspace nor narrowed to some projects.

A private project is visible only to its members. When none of them can see it any more - each has been deactivated, answers to somebody who has, has been taken out of the workspace, or is hidden from it by a private project above - nothing can make it public or share it again. This lists those projects by address, title and membership count, and nothing inside them. POST /v1/projects/{id_or_key}/members then lets somebody back in, and an administrator may do that for a project listed here; it is recorded like any other share. member_of_workspace says whether you belong to the project's workspace: where you do not, join it first, with POST /v1/workspaces/{id_or_slug}/members.

With leaving, it answers the question to ask before deactivating somebody instead: which projects that somebody can see now would nobody be able to see afterwards.

Parameters

• leaving (string or null, in query): Instead, the ones that would be left unreachable if this person left.
• 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_UnreachableProject_. Successful Response
• 422: HTTPValidationError. Validation Error

Every workspace on this installation

GET /v1/instance/workspaces

List every workspace here, whether or not the caller is a member.

Needs instance:admin, which no role carries and only a superuser holds.

Discovery, not reach. GET /v1/workspaces lists what this caller can work in and is unchanged; this says what exists, and nothing a workspace contains is widened by it. Anybody holding instance:workspace_create can make a workspace the instance owner is not in, and until this route the owner's answer to what is here silently left it out - an empty list, which reads as nothing being there rather than as something unseen.

Enveloped and unpaginated, like a workspace's members: the number of workspaces on an installation is bounded by how many somebody made.

Parameters

• 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_WorkspaceOnInstance_. Successful Response
• 422: HTTPValidationError. Validation Error