Tags

Tags define structured schemas that can be applied to thogits. Each tag has a name, optional description, and a set of typed fields. When a tag is applied to a thogit, the thogit gains those fields with validated values.

Schema Types

Each field in a tag schema has one of the following types:

Type	Value	Description
String	`"String"`	Free-text string
Number	`"Number"`	Numeric value (integer or float)
Boolean	`"Boolean"`	True or false
Date	`"Date"`	ISO 8601 date string
Reference	`"Reference"`	ULID referencing another thogit
Select	`{"type": "Select", "variants": [...]}`	Single choice from defined variants
MultiSelect	`{"type": "MultiSelect", "variants": [...]}`	Multiple choices from string variants

Select Variants

Select variants can optionally define their own sub-fields:

{
  "type": "Select",
  "variants": [
    {"name": "Bug", "fields": {"severity": "String"}},
    "Feature",
    "Chore"
  ]
}

MultiSelect Variants

MultiSelect variants are simple string arrays:

{
  "type": "MultiSelect",
  "variants": ["frontend", "backend", "infrastructure"]
}

POST /tags

Create a new tag with a typed schema.

Auth required: Yes

Request body:

Field	Type	Required	Description
`name`	string	Yes	Tag name
`description`	string	No	Description of the tag’s purpose
`fields`	object	Yes	Map of field names to schema types

curl -X POST https://app.thogits.com/api/tags \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{
    "name": "Task",
    "description": "Track work items",
    "fields": {
      "status": {"type": "Select", "variants": ["Todo", "In Progress", "Done"]},
      "priority": "String",
      "due_date": "Date",
      "assignee": "Reference",
      "labels": {"type": "MultiSelect", "variants": ["bug", "feature", "docs"]}
    }
  }'

Response (200): The full tag object including its generated id and schema_version: 1.

{
  "id": "01HQ3K5P7YGXJV8N2M4W6R0T1S",
  "name": "Task",
  "description": "Track work items",
  "fields": {
    "status": {"type": "Select", "variants": ["Todo", "In Progress", "Done"]},
    "priority": "String",
    "due_date": "Date",
    "assignee": "Reference",
    "labels": {"type": "MultiSelect", "variants": ["bug", "feature", "docs"]}
  },
  "schema_version": 1,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}

GET /tags/{tag_id}

Retrieve a single tag by its ULID.

Auth required: Yes

curl https://app.thogits.com/api/tags/01HQ3K5P7YGXJV8N2M4W6R0T1S \
  -b cookies.txt -c cookies.txt

Response (200): The full tag object.

Errors:

Status	Cause
404	Tag not found or soft-deleted

PUT /tags/{tag_id}

Update a tag’s name, description, or fields. Changing the fields schema increments the tag’s schema_version.

Auth required: Yes

Request body:

Field	Type	Required	Description
`name`	string	No	New name
`description`	string	No	New description
`fields`	object	No	Updated field schema (replaces all fields)

curl -X PUT https://app.thogits.com/api/tags/01HQ3K5P7YGXJV8N2M4W6R0T1S \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{
    "fields": {
      "status": {"type": "Select", "variants": ["Todo", "In Progress", "Review", "Done"]},
      "priority": "String",
      "due_date": "Date",
      "assignee": "Reference",
      "labels": {"type": "MultiSelect", "variants": ["bug", "feature", "docs", "security"]}
    }
  }'

Response (200): The updated tag object with incremented schema_version.

DELETE /tags/{tag_id}

Soft-delete a tag. The tag is removed from all thogits that currently use it.

Auth required: Yes

curl -X DELETE https://app.thogits.com/api/tags/01HQ3K5P7YGXJV8N2M4W6R0T1S \
  -b cookies.txt -c cookies.txt

Response (200): The deleted tag object.

Errors:

Status	Cause
404	Tag not found

POST /tags/search

Search for tags using a filter.

Auth required: Yes

Request body:

Field	Type	Required	Description
`filter`	TagFilter \| null	No	Filter criteria

Supported filter shapes:

{"search": "text"} — full-text search across name and description
{"name": {"contains": "text"}} — name substring match
{"and": [filter, ...]} — logical AND
{"or": [filter, ...]} — logical OR
{"not": filter} — logical NOT

curl -X POST https://app.thogits.com/api/tags/search \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"filter": {"name": {"contains": "task"}}}'

Response (200):

[
  {
    "id": "01HQ3K5P7YGXJV8N2M4W6R0T1S",
    "name": "Task",
    "description": "Track work items",
    "fields": { ... },
    "schema_version": 2,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-16T14:00:00Z"
  }
]