# Tags

4 endpoints.

## List a workspace's tags

```http
GET https://orbitwrite.com/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:** session cookie.

### Query parameters

- `organizationId` (string, required)

### Responses

#### 200

The workspace's tags

- `tags` (Tag[], required)
  - `id` (string, required)
  - `name` (string, required)
  - `color` (string, required) — Palette color id, e.g. "purple" (see the fixed tag palette)
  - `count` (integer, required) — Number of posts (composer groups) carrying this tag
  - `createdAt` (string, required) — When the tag was created

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

## Create a tag

```http
POST https://orbitwrite.com/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:** session cookie.

### Request body (`application/json`)

- `organizationId` (string, required)
- `name` (string, required)
- `color` (string, optional, one of `grey`, `dark-grey`, `purple`, `blue`, `teal`, `green`, `yellow`, `orange`, `pink`, `red`) — Palette color id — stored colors are constrained to the palette

### Responses

#### 200

The created tag

- `ok` (boolean, required, one of `true`)
- `tag` (Tag, required)
  - `id` (string, required)
  - `name` (string, required)
  - `color` (string, required) — Palette color id, e.g. "purple" (see the fixed tag palette)
  - `count` (integer, required) — Number of posts (composer groups) carrying this tag
  - `createdAt` (string, required) — When the tag was created

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

#### 409

Conflicts with an existing resource

- `error` (string, required)
- `issues` (any[], optional)

## Rename or recolor a tag

```http
PATCH https://orbitwrite.com/api/v1/tags/{tagId}
```

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

**Authentication:** session cookie.

### Path parameters

- `tagId` (string, required)

### Request body (`application/json`)

- `organizationId` (string, required)
- `name` (string, required)
- `color` (string, required, one of `grey`, `dark-grey`, `purple`, `blue`, `teal`, `green`, `yellow`, `orange`, `pink`, `red`) — Palette color id — stored colors are constrained to the palette

### Responses

#### 200

The updated tag

- `ok` (boolean, required, one of `true`)
- `tag` (Tag, required)
  - `id` (string, required)
  - `name` (string, required)
  - `color` (string, required) — Palette color id, e.g. "purple" (see the fixed tag palette)
  - `count` (integer, required) — Number of posts (composer groups) carrying this tag
  - `createdAt` (string, required) — When the tag was created

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

#### 404

The resource does not exist

- `error` (string, required)
- `issues` (any[], optional)

#### 409

Conflicts with an existing resource

- `error` (string, required)
- `issues` (any[], optional)

## Delete a tag

```http
DELETE https://orbitwrite.com/api/v1/tags/{tagId}
```

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

**Authentication:** session cookie.

### Path parameters

- `tagId` (string, required)

### Query parameters

- `organizationId` (string, required)

### Responses

#### 200

The tag was deleted

- `ok` (boolean, required, one of `true`)

#### 400

Invalid request

- `error` (string, required)
- `issues` (any[], optional)

#### 401

Not signed in

- `error` (string, required)
- `issues` (any[], optional)

#### 403

Not a member of the organization

- `error` (string, required)
- `issues` (any[], optional)

#### 404

The resource does not exist

- `error` (string, required)
- `issues` (any[], optional)