Tags

Tags help you organise Links inside a workspace.

Tags describe Links. They do not replace Activity Groups. Activity Groups contain related activity, while tags are lightweight labels.

Each Developer API tag has an immutable opaque public ID. The ID is a ULID string and is not the internal database ID.

List tags

GET /api/v1/tags

Example:

curl https://api.jaww.ws/api/v1/tags \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY"

Successful response:

{
  "tags": [
    {
      "id": "01K0M5ABCD7EFGHJKMNPQRSTVW",
      "name": "Cops & Coffee",
      "slug": "cops-coffee",
      "colour": "#2563eb",
      "description": "Demo workspace content"
    }
  ]
}

Create a tag

POST /api/v1/tags

Request fields:

Field	Required	Type	Notes
name	Yes	string	1 to 100 characters
slug	No	string	1 to 120 characters. Lowercase letters, numbers and hyphens. Auto-generated from name when omitted
colour	No	string	Maximum 32 characters
description	No	string	Maximum 255 characters

Example:

curl -X POST https://api.jaww.ws/api/v1/tags \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY" \
  -d '{
    "name": "Coffee tasting",
    "slug": "coffee-tasting",
    "colour": "#2563eb",
    "description": "Links for coffee tasting events"
  }'

Successful response:

201 Created

{
  "message": "Tag created successfully.",
  "tag": {
    "id": "01K0M5ABCD7EFGHJKMNPQRSTVW",
    "name": "Coffee tasting",
    "slug": "coffee-tasting",
    "colour": "#2563eb",
    "description": "Links for coffee tasting events"
  }
}

Update a tag

PATCH /api/v1/tags/{id}

Use the public tag ID returned by the list or create endpoint.

Request fields:

Field	Required	Type	Notes
name	No	string	1 to 100 characters
slug	No	string or null	1 to 120 characters when present
colour	No	string or null	Maximum 32 characters
description	No	string or null	Maximum 255 characters

Example:

curl -X PATCH https://api.jaww.ws/api/v1/tags/01K0M5ABCD7EFGHJKMNPQRSTVW \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY" \
  -d '{
    "description": "Updated event Links"
  }'

Delete a tag

DELETE /api/v1/tags/{id}

Example:

curl -X DELETE https://api.jaww.ws/api/v1/tags/01K0M5ABCD7EFGHJKMNPQRSTVW \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_BYTES_API_KEY"

Successful deletion returns:

204 No Content

Deleting a tag removes the tag from Links in the workspace. It does not delete the Links.

Identifier rules

• Use the id returned by the Developer API.
• Do not use or infer numeric database IDs.
• The public ID is immutable.
• The human-readable slug can be used for display and Link filtering, but it is not the stable resource identifier.

Common errors

Duplicate tag name

422 Unprocessable Content

Duplicate tag slug

422 Unprocessable Content

Tag not found

404 Not Found

{
  "message": "Tag not found."
}