HTTP API: vocabulary
The 12 operations tagged vocabulary, each with its parameters, its body and what it answers.
The ways two items can relate here
GET /v1/link-types
Return this workspace's link types. Enveloped; see :func:list_statuses.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.
Responses
200:Collection_LinkType_. Successful Response422:HTTPValidationError. Validation Error
Add a link type
POST /v1/link-types
Add a way two items can relate.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.
Request body: CreateLinkType as application/json, required.
Responses
201:LinkType. Successful Response422:HTTPValidationError. Validation Error
Rename a link type
PATCH /v1/link-types/{which}
Rename a link type, or reword either end of it.
Parameters
which(string(uuid), in path, required)
Request body: UpdateLinkType as application/json, required.
Responses
200:LinkType. Successful Response422:HTTPValidationError. Validation Error
Remove a link type
DELETE /v1/link-types/{which}
Remove a link type nothing is joined by.
Parameters
which(string(uuid), in path, required)
Responses
204: Successful Response422:HTTPValidationError. Validation Error
The statuses this workspace has
GET /v1/statuses
Return this workspace's statuses, in the order a client should show them.
Enveloped like every other listing, with has_more always false — §5.7's link
listing settled that a bare array is the one shape a caller cannot tell complete from
truncated, and always false here is a statement rather than a shrug: a workspace's
vocabulary is bounded by how many somebody wrote.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.entity_type(stringornull, in query): Narrow to what they apply to: task, project or document.
Responses
200:Collection_Status_. Successful Response422:HTTPValidationError. Validation Error
Add a status
POST /v1/statuses
Add a status to this workspace's vocabulary.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.
Request body: CreateStatus as application/json, required.
Responses
201:Status. Successful Response422:HTTPValidationError. Validation Error
Rename or reposition a status
PATCH /v1/statuses/{which}
Change a status without changing what it means.
Parameters
which(string(uuid), in path, required)
Request body: UpdateStatus as application/json, required.
Responses
200:Status. Successful Response422:HTTPValidationError. Validation Error
Remove a status
DELETE /v1/statuses/{which}
Remove a status nothing is in, and that is not the default.
Parameters
which(string(uuid), in path, required)
Responses
204: Successful Response422:HTTPValidationError. Validation Error
The tags this workspace has
GET /v1/tags
Return this workspace's tags as things to curate — id, name and what it means.
No usage counts here, and /v1/meta is where they stay. §5.5's table says List (with
usage counts) and /v1/meta already answers exactly that, narrowed to the tasks this
caller can see — a tag used only in a private project they are not a member of does not
appear. Recomputing that beside a curation listing would either duplicate a
disclosure-sensitive aggregate or publish an unscoped one.
Paged like every other listing here (SR#1572). It used to return every row and accept
no limit, honestly — has_more was false because there genuinely was no more — but a
tag is minted as a side effect of the ordinary write path, on every surface, so the response
grew without anybody deciding it should. domain/paging.size is one definition of a page
size that both clients share, and this route was an exception nobody chose: it was written
before that machinery and never revisited.
total is opt-in now and used to be free. It was computed because the query fetched
every row anyway; §8.4 makes it a second query about the same question, which is what it
now costs.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.limit(integerornull, in query): How many to return. At least 1; capped at the instance's max_page_size.cursor(stringornull, in query): Continue after a previous page.include_total(boolean, in query): Count the whole result.
Responses
200:Collection_TagEntry_. Successful Response422:HTTPValidationError. Validation Error
Declare a tag
POST /v1/tags
Declare a tag before anybody uses it, and say what it means here.
Parameters
workspace_id(stringornull, in query): Which workspace, by id or short name. Needed when you can reach several.
Request body: CreateTag as application/json, required.
Responses
201:TagEntry. Successful Response422:HTTPValidationError. Validation Error
Rename a tag, or say what it means
PATCH /v1/tags/{which}
Rename a tag, or write down what it means in this workspace.
Parameters
which(string(uuid), in path, required)
Request body: UpdateTag as application/json, required.
Responses
200:TagEntry. Successful Response422:HTTPValidationError. Validation Error
Remove a tag
DELETE /v1/tags/{which}
Remove a tag, and with it every application of it.
Parameters
which(string(uuid), in path, required)
Responses
204: Successful Response422:HTTPValidationError. Validation Error