API Overview

Caution

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

The Thogits REST API provides full programmatic access to all features — creating and managing thogits, defining tag schemas, filtering, views, and more. This page covers the conventions shared across all endpoints.

Base URL

All API routes are prefixed with /api:

https://app.thogits.com/api/

All API examples in this documentation use the production URL above.

Authentication

Most endpoints require an authenticated session. Thogits uses session cookies — after logging in via /api/auth/login, the server sets an HTTP-only cookie that must be included in subsequent requests.

For curl, use the cookie jar flags:

# Login and save the session cookie
curl -X POST https://app.thogits.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123"}' \
  -b cookies.txt -c cookies.txt

# Use the saved cookie for authenticated requests
curl https://app.thogits.com/api/thogits/01JTEST1234567890ABCDE \
  -b cookies.txt -c cookies.txt

For browser-based clients, include credentials: "include" in fetch requests.

Tip

The only endpoints that do not require authentication are GET /api/health, the OAuth callback routes, and POST /api/auth/register / POST /api/auth/login.

Content Type

All request and response bodies use JSON:

Content-Type: application/json

IDs

Thogits uses ULIDs (Universally Unique Lexicographically Sortable Identifiers) for all entity IDs. ULIDs are 26-character base32-encoded strings that are sortable by creation time:

01HQ3K5P7YGXJV8N2M4W6R0T1S

OpenAPI Specification

The full OpenAPI spec is available at runtime:

• JSON spec: GET /api/openapi.json
• Swagger UI: GET /api/swagger-ui/

The Swagger UI provides an interactive explorer for trying out endpoints directly in the browser.

Error Format

All error responses follow a consistent JSON structure:

{
  "error": "NotFound",
  "message": "Thogit not found",
  "path": "/api/thogits/01JTEST1234567890ABCDE",
  "suggestion": "Check the thogit ID and try again",
  "details": {}
}

Field	Type	Description
error	string	Error code (e.g., NotFound, BadRequest, Conflict)
message	string	Human-readable description
path	string	The request path that triggered the error
suggestion	string	Optional hint for resolving the error
details	object	Optional additional context

Status Codes

Code	Meaning
200	Success
400	Bad request — invalid input, validation failure
401	Unauthorized — no session or session expired
404	Not found — entity does not exist or was soft-deleted
409	Conflict — duplicate (e.g., applying a tag already on a thogit)
500	Internal server error

Soft Deletes

Both thogits and tags support soft deletes. When you delete a thogit or tag, it is marked as deleted rather than permanently removed. Soft-deleted entities:

• No longer appear in search results
• Cannot be fetched by ID (return 404)
• Can be restored via the audit log or future restore endpoints
• Maintain their audit trail

This ensures data is never permanently lost through normal API operations.