Core Concepts

The hierarchy and data model behind Th1ngs.

The Three-Level Hierarchy

Anatomy of a Thing

A Thing is the primary entity. It carries:

• Key — unique ID like PROJ-42, auto-generated from the box key.
• Summary — one-line title.
• Description — rich-text body (often populated from email).
• Status — current workflow state (Open, In Progress, Done, …).
• Custom Fields — typed fields defined by the box schema.
• Comments — threaded discussion.
• Attachments — versioned files stored per Thing.
• Relations — links to other Things.
• History — full audit log of every change.

Box Types

Each Box is created from a Box Type — a schema template that pre-configures the custom fields, default workflow, and view layout.

Built-in types include: Tasks, Agile / Software, Project Management, Places, Photo, and Guide.

Permissions

Boxes

Boxes are the containers that group your Things. Each has its own schema, workflow, and access controls.

Creating a Box

Go to Boxes → New Box and choose:

• Name — displayed everywhere.
• Key — short prefix like PROJ. Used in Thing keys (PROJ-1).
• Type — the schema template to start from.
• Visibility — public (anyone) or private (invited users only).

Box Settings

Built-in Box Types

• Tasks — Generic tracker with priority and assignee.
• Agile / Software — Sprints, story points, releases.
• Project Management — Phases, milestones, owners.
• Places — Items with geographic coordinates.
• Photo — Image-centric items with gallery view.
• Guide — Documentation-style knowledge base entries.

Things

Things are the primary objects — tasks, tickets, assets, entries, or anything else you want to track.

Creating a Thing

Click + New in the navbar or from inside a Box. Provide:

• Summary (required) — one-line title.
• Description — body text, often pre-filled from an incoming email.
• Custom Fields — any fields defined by the box schema.
• Status — the starting workflow state.

The Thing Detail Page

From the detail page you can:

• Edit any field inline and save immediately.
• Advance the workflow state via transition buttons.
• Add, read and delete comments.
• Upload files — versioned automatically as report.pdf, report-2.pdf, …
• Create and remove relations to other Things.
• Browse the full change history.

Thing Keys

Every Thing gets a permanent key like PROJ-42. Keys are unique site-wide, human-readable, and searchable. Use them in comments or external tools to reference a specific Thing.

Relations

Link two Things together with a relation type and an optional comment. Relations are bidirectional — both Things show the link. Delete a relation from either side.

Attachments

Files are stored under {boxKey}/{thingId}/ with automatic versioning. Download or delete individual file versions from the Thing page.

Custom Fields

Attach typed metadata to every Thing in a Box. Design the schema that fits your workflow exactly.

Field Types

Managing Fields

Open Box Settings → Custom Fields. From there:

• Add a field — choose its name and type.
• Mark a field as required to block saving if empty.
• Reorder fields — the order determines form and list layout.
• For Select fields, manage the list of allowed option values.

Select-Suggest Providers

Fields of type select-suggest support dynamic option providers. A developer can implement the SelectSuggestProvider interface to fetch options from any external source (e.g. a REST API, a database).

public interface SelectSuggestProvider {
    String getKey();
    List<String> suggest(String query);
}

Register your provider as a Spring bean — it will be auto-discovered and available in the admin field configuration.

Built-in providers: countries — fetches country names from a public REST API with a built-in static fallback.

Workflows

Workflows are YAML-defined state machines that guide Things through a structured lifecycle.

How Workflows Work

A workflow defines:

• States — stages a Thing can be in (Open, In Progress, Done …).
• Transitions — allowed moves between states.
• Conditions — rules that must pass before a transition is allowed.
• Validators — checks at transition time (e.g. a required field must be set).
• Post-functions — actions run automatically after a transition succeeds.

Example Workflow YAML

name: Simple Task Workflow
initial_state: open
states:
  - id: open
    label: Open
    color: "#6366f1"
  - id: in_progress
    label: In Progress
    color: "#f59e0b"
  - id: done
    label: Done
    color: "#22c55e"
transitions:
  - from: open
    to:   in_progress
    label: Start Work
  - from: in_progress
    to:   done
    label: Mark Complete

Assigning a Workflow to a Box

In Box Settings → Workflow, select the workflow schema to use. Changing the workflow doesn't reset existing Thing states — they keep their current state and follow the new transitions going forward.

Agile Boards

Boxes of type Agile / Software render workflow states as swim-lane columns. Drag Things between columns to trigger transitions. Releases (milestones) can be created and Things assigned to them for sprint-style planning.

Email Integration

Connect an IMAP mailbox to a Box and create Things — and add comments — entirely by email.

How It Works

Th1ngs polls the configured inbox on a schedule. For each unread message:

• New thread — creates a new Thing. Subject becomes the summary; email body becomes the description.
• Reply to existing thread — adds a comment to the existing Thing. Quoted previous messages are stripped automatically.
• Attachments — saved directly to the Thing.

Connecting a Mailbox

Go to Box Settings → Email → Connect IMAP Mailbox.

Thread Tracking

Th1ngs tracks email threads using the RFC 2822 Message-ID, In-Reply-To, and References headers. When a Thing is created from an email, its Message-ID is stored. Any future reply — including reply-to-reply chains — will add a comment to the same Thing rather than creating a new one.

Quote Stripping

When a reply becomes a comment, Th1ngs strips the quoted previous messages automatically. It handles:

• >-prefixed quoted lines in plain-text emails.
• Multi-line "On [date] … wrote:" separators (Gmail, Outlook, Apple Mail).
• HTML emails: removes <blockquote>, Gmail quote divs, Yahoo quoted sections, Outlook reply containers, and everything after <hr> dividers.

REST API

Programmatic access to Th1ngs via a JSON REST API. Authenticate with JWT or Personal Access Tokens.

Authentication

• JWT — POST credentials to /rest/api/1/auth/login, then pass the token as Authorization: Bearer <token>.
• Personal Access Tokens — generate in your profile settings; same bearer format.
• Google OAuth2 — for browser-based flows.

Base URL

https://th1ngs.com/rest/api/1/

Key Endpoints

Example

# List Things in box 42
curl -X GET \
  https://th1ngs.com/rest/api/1/boxes/42/things \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

AI / MCP Integration

Th1ngs includes a built-in MCP server — connect Claude, ChatGPT, or any MCP-compatible AI to search and manage your Things.

What is MCP?

The Model Context Protocol is an open standard that lets LLM-based tools connect to external data sources. Th1ngs acts as an MCP server; your AI assistant is the client.

Connecting an AI Assistant

In your AI tool's MCP configuration, point it to:

url:  https://th1ngs.com/mcp/sse
type: sse

No authentication is needed for public boxes. For private boxes, pass a Personal Access Token as a bearer header (depending on your AI client's configuration).

Available Tools

Privacy & Access Control

The MCP server enforces the same access controls as the web UI. Unauthenticated callers can only see public boxes. Private boxes require a valid user token — the same one you'd use for the REST API.