OrbitwriteDocs

API reference

Tags

4 endpoints, served at https://orbitwrite.com/api/v1. Each one lists the credentials it accepts, its parameters and every response it can give.

Endpoints
GET/api/v1/tagsPOST/api/v1/tagsPATCH/api/v1/tags/{tagId}DEL/api/v1/tags/{tagId}

List a workspace's tags#

GET/api/v1/tags

Returns the organization's tags with per-tag post counts, sorted by name. Any member may read; feeds the Tags settings page and the composer's tag suggestions.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Query parameters

organizationIdstringRequired

At least 1 character.

Responses

200TagList

The workspace's tags

Response attributes
tagsTag[]Required
Child attributes
idstringRequired
namestringRequired
colorstringRequired

Palette color id, e.g. "purple" (see the fixed tag palette)

countintegerRequired

Number of posts (composer groups) carrying this tag

createdAtstringRequired

When the tag was created

400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
GET /api/v1/tags
curl -X GET "https://orbitwrite.com/api/v1/tags?organizationId=organizationId" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
Response
{
  "tags": [
    {
      "id": "string",
      "name": "string",
      "color": "string",
      "count": 0,
      "createdAt": "string"
    }
  ]
}

Create a tag#

POST/api/v1/tags

Creates a standalone tag (not yet attached to any post). Owner/admin only. Tag names are unique per workspace, case-insensitively.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Body application/json

organizationIdstringRequired

At least 1 character.

namestringRequired

At least 1 character.

colorstring

Palette color id — stored colors are constrained to the palette

Defaults to "grey".

  • "grey"
  • "dark-grey"
  • "purple"
  • "blue"
  • "teal"
  • "green"
  • "yellow"
  • "orange"
  • "pink"
  • "red"

Responses

200TagMutationResult

The created tag

Response attributes
okbooleanRequired
tagTagRequired
Child attributes
idstringRequired
namestringRequired
colorstringRequired

Palette color id, e.g. "purple" (see the fixed tag palette)

countintegerRequired

Number of posts (composer groups) carrying this tag

createdAtstringRequired

When the tag was created

400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
409Error

Conflicts with an existing resource

Response attributes
errorstringRequired
issuesany[]
POST /api/v1/tags
curl -X POST "https://orbitwrite.com/api/v1/tags" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationId": "string",
  "name": "string"
}'
Response
{
  "ok": true,
  "tag": {
    "id": "string",
    "name": "string",
    "color": "string",
    "count": 0,
    "createdAt": "string"
  }
}

Rename or recolor a tag#

PATCH/api/v1/tags/{tagId}

Owner/admin only. Posts reflect the change automatically — they link to the tag by id.

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Path parameters

tagIdstringRequired

At least 1 character.

Body application/json

organizationIdstringRequired

At least 1 character.

namestringRequired

At least 1 character.

colorstringRequired

Palette color id — stored colors are constrained to the palette

  • "grey"
  • "dark-grey"
  • "purple"
  • "blue"
  • "teal"
  • "green"
  • "yellow"
  • "orange"
  • "pink"
  • "red"

Responses

200TagMutationResult

The updated tag

Response attributes
okbooleanRequired
tagTagRequired
Child attributes
idstringRequired
namestringRequired
colorstringRequired

Palette color id, e.g. "purple" (see the fixed tag palette)

countintegerRequired

Number of posts (composer groups) carrying this tag

createdAtstringRequired

When the tag was created

400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
404Error

The resource does not exist

Response attributes
errorstringRequired
issuesany[]
409Error

Conflicts with an existing resource

Response attributes
errorstringRequired
issuesany[]
PATCH /api/v1/tags/{tagId}
curl -X PATCH "https://orbitwrite.com/api/v1/tags/{tagId}" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationId": "string",
  "name": "string",
  "color": "grey"
}'
Response
{
  "ok": true,
  "tag": {
    "id": "string",
    "name": "string",
    "color": "string",
    "count": 0,
    "createdAt": "string"
  }
}

Delete a tag#

DELETE/api/v1/tags/{tagId}

Owner/admin only. The tag is removed from every post carrying it (cascade on the join table).

Authentication

A signed-in session only. The Orbitwrite app calls this; an API key is refused.

Path parameters

tagIdstringRequired

At least 1 character.

Query parameters

organizationIdstringRequired

At least 1 character.

Responses

200TagDeleteResult

The tag was deleted

Response attributes
okbooleanRequired
400Error

Invalid request

Response attributes
errorstringRequired
issuesany[]
401Error

Not signed in

Response attributes
errorstringRequired
issuesany[]
403Error

Not a member of the organization

Response attributes
errorstringRequired
issuesany[]
404Error

The resource does not exist

Response attributes
errorstringRequired
issuesany[]
DELETE /api/v1/tags/{tagId}
curl -X DELETE "https://orbitwrite.com/api/v1/tags/{tagId}?organizationId=organizationId" \
  -H "Authorization: Bearer $ORBITWRITE_API_KEY"
Response
{
  "ok": true
}