Documentation

Integration guides and API reference for the Thing Event System.

What is TES?

The Thing Event System (TES) is an immutable event store with a GraphQL API. Every entity lifecycle — physical items, AI agent sessions, invoices, subscriptions — is tracked as append-only events with automatic AI enrichment and vector search.

Every mutation emits an event that is processed asynchronously. This means creates and updates are eventually consistent — poll the entity after ~500ms to see the updated state.

Connect to the API

All requests go through a single GraphQL endpoint. You need an OAuth token and your client ID.

POST /api/graphql

Headers:
  Content-Type: application/json
  Authorization: Bearer <your-token>
  X-Client-Id: <your-client-id>

Tip: See the OAuth tab for how to obtain a token, or generate one from the dashboard for quick testing.

Create Your First Thing

A "thing" is any physical item you want to track. Here's the simplest way to create one:

mutation CreateThing($input: ThingInput!) {
  createThing(input: $input) {
    success
    message
    eventId
  }
}

# Variables
{
  "input": {
    "name": "Blue Running Shoes",
    "holder_id": "customer_123",
    "holder_type": "customer",
    "statuses": [{ "parent_status": "sold", "status": "sold" }],
    "source": "my-app"
  }
}

Core Entities

TES has four core entity types:

ThingsPhysical items tracked through their lifecycle (products, returns, inventory)

ProductsProduct catalog entries that things can be linked to (auto-matched by AI)

HoldersEntities that hold things — customers, warehouses, stores, carriers

LocationsPhysical places where things are stored or processed

Key Operations

createThingCreate a new thing with initial status

addThingStatusProgress a thing through its lifecycle (captured, received, processing, ...)

transferThingTransfer ownership to a new holder (updates FK + edge history)

changeThingLocationMove a thing to a new location (updates FK + edge history)

updateThingUpdate general attributes (name, condition, data, etc.)

searchThingsSemantic search by text, image, or similarity

Lifecycle Stages

Things progress through stages that represent their journey:

Production:   manufactured → sourced
Inventory:    in_stock → in_transit → delivered
Customer:     sold → in_use
Capture:      captured → identified → valued
Return:       returned → received
Processing:   processing → inspecting → refurbishing
Outcomes:     processed → certified → listed → resold
End States:   recycled → donated → disposed

Typical Return Flow

Here's a common pattern for processing a return:

// 1. Customer initiates return
addThingStatus(id, { parent_status: "captured", status: "return_initiated" })

// 2. Item arrives at warehouse — transfer ownership + set location
addThingStatus(id, { parent_status: "received", status: "received" })
transferThing(id, { holder_id: "warehouse_1", holder_type: "warehouse" })
changeThingLocation(id, { location_id: "loc_receiving" })

// 3. Inspect and process
addThingStatus(id, { parent_status: "processing", status: "inspecting" })

// 4. Route to outcome: resell, refurbish, recycle, or donate
addThingStatus(id, { parent_status: "certified", status: "quality_certified" })

Ready to build

Start emitting events in minutes

Free tier includes 10,000 events per month with AI enrichment and vector search. No credit card required.

Create free account Try the GraphQL API