Thogits

Thogits are the core entities in the system — knowledge entries that can be tagged with structured schemas. Each thogit has a name, an optional rich-text description, and zero or more tags with typed field values.

POST /thogits

Create a new thogit, optionally applying tags with field values in the same request.

Auth required: Yes

Request body:

Field	Type	Required	Description
`name`	string	Yes	The thogit name
`description`	string	No	Rich-text description (HTML)
`tags`	array	No	Tags to apply on creation
`tags[].tag_ref`	object	Yes	Either `{"New": {"name": "...", "fields": {...}}}` or `{"Existing": "TAG_ULID"}`
`tags[].field_values`	object	No	Field values matching the tag schema

curl -X POST https://app.thogits.com/api/thogits \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{
    "name": "Learn Rust ownership",
    "description": "<p>Deep dive into the borrow checker</p>",
    "tags": [
      {
        "tag_ref": {"Existing": "01HQ3K5P7YGXJV8N2M4W6R0T1S"},
        "field_values": {"priority": "high", "due_date": "2025-06-01"}
      },
      {
        "tag_ref": {"New": {"name": "Language", "fields": {"name": "String"}}},
        "field_values": {"name": "Rust"}
      }
    ]
  }'

Response (200):

{
  "thogit_id": "01HQ4M8R3ZBNWY6K9J2X5V7Q0A"
}

GET /thogits/{thogit_id}

Retrieve a single thogit by its ULID.

Auth required: Yes

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

Response (200):

{
  "id": "01HQ4M8R3ZBNWY6K9J2X5V7Q0A",
  "name": "Learn Rust ownership",
  "description": "<p>Deep dive into the borrow checker</p>",
  "data": {
    "01HQ3K5P7YGXJV8N2M4W6R0T1S": {
      "field_values": {
        "priority": "high",
        "due_date": "2025-06-01"
      },
      "schema_version": 1
    }
  }
}

The data object is keyed by tag ID. Each entry includes the field_values and the schema_version at which those values were stored.

Errors:

Status	Cause
404	Thogit not found or soft-deleted

PUT /thogits/{thogit_id}

Update a thogit’s name and/or description. To update tag field values, use the thogit tags endpoints.

Auth required: Yes

Request body:

Field	Type	Required	Description
`name`	string	No	New name
`description`	string	No	New description (HTML)

curl -X PUT https://app.thogits.com/api/thogits/01HQ4M8R3ZBNWY6K9J2X5V7Q0A \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"name": "Master Rust ownership"}'

Response (200): The updated thogit object.

DELETE /thogits/{thogit_id}

Soft-delete a thogit. The thogit will no longer appear in search results.

Auth required: Yes

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

Response (200): The deleted thogit object.

Errors:

Status	Cause
404	Thogit not found

POST /thogits/search

Search for thogits using a filter. Passing null or omitting the filter returns all thogits.

Auth required: Yes

Request body:

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

Filters support logical combinators (and, or, not) and field-level conditions. See the Concepts: Filtering guide for the full filter syntax.

# Get all thogits
curl -X POST https://app.thogits.com/api/thogits/search \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"filter": null}'

# Search with a text filter
curl -X POST https://app.thogits.com/api/thogits/search \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"filter": {"search": "rust ownership"}}'

Response (200):

[
  {
    "id": "01HQ4M8R3ZBNWY6K9J2X5V7Q0A",
    "name": "Learn Rust ownership",
    "description": "<p>Deep dive into the borrow checker</p>",
    "data": { ... }
  }
]

POST /thogits/bulk

Create multiple thogits in a single request.

Auth required: Yes

Request body:

Field	Type	Required	Description
`thogits`	array	Yes	Array of create-thogit objects (same shape as POST /thogits body)

curl -X POST https://app.thogits.com/api/thogits/bulk \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{
    "thogits": [
      "Item one",
      {"name": "Item two", "tags": [{"tag_ref": {"Existing": "01HQ3K5P7YGXJV8N2M4W6R0T1S"}, "field_values": {}}]}
    ]
  }'

Response (200):

[
  {"thogit_id": "01HQ5A2B3CDEFGHIJK4LMNOP5Q"},
  {"thogit_id": "01HQ5A2B4RSTUVWXYZ6ABCDE7F"}
]

POST /thogits/bulk-delete

Delete all thogits matching a filter. Supports dry-run mode to preview the impact before committing.

Auth required: Yes

Request body:

Field	Type	Required	Description
`filter`	ThogitFilter	Yes	Filter selecting thogits to delete
`dry_run`	boolean	No	If `true`, report matches without deleting (default: `false`)

# Preview what would be deleted
curl -X POST https://app.thogits.com/api/thogits/bulk-delete \
  -H "Content-Type: application/json" \
  -b cookies.txt -c cookies.txt \
  -d '{"filter": {"search": "obsolete"}, "dry_run": true}'

Response (200):

{
  "matched_count": 3,
  "affected_count": 3,
  "affected_ids": [
    "01HQ5A2B3CDEFGHIJK4LMNOP5Q",
    "01HQ5A2B4RSTUVWXYZ6ABCDE7F",
    "01HQ5A2B5GHIJKLMNO8PQRST9U"
  ],
  "dry_run": true
}