Quickstart

This guide walks you through the core API workflow: register, create a tag with a schema, create a thogit, search, update fields, and save a view. Every command is copy-pasteable.

Caution

Thogits is in early alpha. The API may change without notice.

Tip

All curl examples use -b cookies.txt -c cookies.txt to persist the session cookie across requests. The session cookie is HTTPOnly with a 7-day expiry.

The base URL for all API requests is https://app.thogits.com/api/.

1. Register an account

   curl -X POST https://app.thogits.com/api/auth/register \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "email": "alice@example.com",
       "password": "s3cur3pass!"
     }'

   {
     "user_id": "01JQXYZ1234567890ABCDEFGH",
     "email": "alice@example.com",
     "display_name": null,
     "has_totp": false,
     "has_passkey": false,
     "linked_google": false,
     "linked_apple": false
   }

   Registration automatically logs you in. The session cookie is saved to cookies.txt.

2. Create a tag with a schema

   Create a “Task” tag with three typed fields: a Select for status, a Number for priority, and a Date for due date.

   curl -X POST https://app.thogits.com/api/tags \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "name": "Task",
       "fields": {
         "status": {
           "type": "Select",
           "variants": [
             "Todo",
             "In Progress",
             "Done"
           ]
         },
         "priority": "Number",
         "due_date": "Date"
       }
     }'

   {
     "tag_id": "01JQXYZ000TAG00000000TASK",
     "name": "Task",
     "description": null,
     "fields": {
       "status": {
         "type": "Select",
         "variants": [
           "Todo",
           "In Progress",
           "Done"
         ]
       },
       "priority": "Number",
       "due_date": "Date"
     },
     "schema_version": 1,
     "created_at": "2026-04-06T12:00:00Z",
     "updated_at": "2026-04-06T12:00:00Z"
   }

   Note

   Save the tag_id from the response — you’ll need it in the next steps. The examples below use TAG_ID as a placeholder.

3. Create a thogit with that tag

   Create a thogit and attach the Task tag with field values in a single request.

   curl -X POST https://app.thogits.com/api/thogits \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "name": "Write API documentation",
       "description": "Cover all endpoints with curl examples",
       "tags": [{
         "tag_ref": {"Existing": "TAG_ID"},
         "field_values": {
           "status": {"variant": "In Progress"},
           "priority": 1,
           "due_date": "2026-04-10"
         }
       }]
     }'

   {
     "thogit_id": "01JQXYZ000THOGIT00000001"
   }

   You can also create a thogit without tags and attach them later using POST /api/thogits/{thogit_id}/tags.

4. Search thogits with a filter

   Find all thogits tagged “Task” where priority is 2 or less and status is not “Done”.

   curl -X POST https://app.thogits.com/api/thogits/search \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "filter": {
         "and": [
           {"has_tag": "Task"},
           {"Task.priority": {"lte": 2}},
           {"not": {"Task.status": {"match": "Done"}}}
         ]
       }
     }'

   [
     {
       "thogit_id": "01JQXYZ000THOGIT00000001",
       "name": "Write API documentation",
       "description": "Cover all endpoints with curl examples",
       "tags": {
         "01JQXYZ000TAG00000000TASK": {
           "tag_name": "Task",
           "schema_version": 1,
           "field_values": {
             "status": {"variant": "In Progress"},
             "priority": 1,
             "due_date": "2026-04-10"
           }
         }
       },
       "created_at": "2026-04-06T12:00:00Z",
       "updated_at": "2026-04-06T12:00:00Z"
     }
   ]

   Tip

   Filters use tag names (like Task) rather than tag IDs. The server resolves names to IDs automatically. Available operators include eq, neq, gt, gte, lt, lte, match, contains, has_tag, and, or, and not.

5. Update field values

   Mark the task as done by merging new field values. With merge: true, only the specified fields are updated — other fields keep their existing values.

   curl -X PUT https://app.thogits.com/api/thogits/THOGIT_ID/tags/TAG_ID \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "field_values": {
         "status": {"variant": "Done"}
       },
       "merge": true
     }'

   Response: 200 OK with an empty body. The priority and due_date fields remain unchanged.

   Without merge: true, the request would replace all field values, clearing any fields not included in the payload.

6. Create a view

   Save a filtered query as a named view for quick access.

   curl -X POST https://app.thogits.com/api/views \
     -H "Content-Type: application/json" \
     -b cookies.txt -c cookies.txt \
     -d '{
       "name": "Active Tasks",
       "filter": {
         "and": [
           {"has_tag": "Task"},
           {"not": {"Task.status": {"match": "Done"}}}
         ]
       }
     }'

   {
     "view_id": "01JQXYZ000VIEW000000001",
     "user_id": "01JQXYZ1234567890ABCDEFGH",
     "name": "Active Tasks",
     "icon": "\ud83d\udccb",
     "filter": {
       "and": [
         {"has_tag": "01JQXYZ000TAG00000000TASK"},
         {"not": {"01JQXYZ000TAG00000000TASK.status": {"match": "Done"}}}
       ]
     },
     "view_type": "list",
     "settings": {},
     "created_at": "2026-04-06T12:00:00Z",
     "updated_at": "2026-04-06T12:00:00Z"
   }

   Note

   Notice that the stored filter uses tag IDs, not names. The server resolves tag names to IDs when saving the view. You can use either names or IDs in the request.

Next steps

• Authentication — Set up OAuth, 2FA, or passkeys for your account.
• API Reference — Full endpoint documentation with request/response schemas.
• MCP Tools — Connect Claude or other MCP clients to manage your knowledge conversationally.