Thatch Documentation

Note

Draft. This site is being written alongside the platform. Pages marked To be written are placeholders — the structure is settled, the detail is not.

Thatch pools independently-owned, heterogeneous compute and storage nodes into a single coordinated, sovereign-by-region fabric for AI inference. You get one API and one bill; the fabric handles placement, health, and residency across the fleet.

Where to start

Conventions

• Shell examples assume a POSIX shell and curl.
• $THATCH_API_KEY stands in for your API key — never paste a real key into a shared document, issue, or support ticket.
• Anything under Support is safe to link to customers directly.

Improving these docs

Every page has an edit link in the top-right corner that opens a pull request against Thatch-cloud/Thatch.Docs. Corrections are welcome, including from outside the org.

Quickstart

Note

Partly written. Steps 2 and 3 are settled; the sign-up flow in step 1 is still to come.

1. Create an account

2. Create an API key

In the Portal, open Developers and click Create API key.

The key’s secret is shown once, at creation, and cannot be retrieved afterwards. Copy it somewhere safe before you leave the page — if you lose it, the only way forward is to rotate the key. Keys are prefixed thatch_sk_.

export THATCH_API_KEY="..."

See API keys for who may create, rotate, and revoke keys.

3. Send a request

The API is OpenAI-compatible: if you already have code talking to an OpenAI-shaped endpoint, you can point it at Thatch by changing the base URL (https://api.thatch.cloud/v1) and the key.

First, see which models are available to your key:

curl https://api.thatch.cloud/v1/models \
  -H "Authorization: Bearer $THATCH_API_KEY"

Then send a completion request, using a model id from that response:

curl https://api.thatch.cloud/v1/chat/completions \
  -H "Authorization: Bearer $THATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-id>",
    "messages": [
      { "role": "user", "content": "Hello" }
    ]
  }'

4. Next steps

• Core concepts — what a job, node, and region actually are.
• API overview — the full surface.
• Rate limits & quotas — before you scale up.

Core concepts

The vocabulary below is used consistently throughout these docs and in the Portal.

The fabric

Thatch is a decentralised distributed data center: a fleet of independently-owned machines — in substations, towers, and homes — presented as one coordinated region. Nodes are not assumed to be trustworthy; the control plane is what makes the pooled result dependable.

Node

A single participating machine. Each node runs an agent that registers it, reports its capacity, health, and power, and executes the work scheduled onto it. Nodes are heterogeneous: they differ in architecture, accelerators, and available resources.

Control plane

The coordinating layer. It owns registration, scheduling and routing, billing, and residency enforcement. As a customer you only ever talk to the control plane’s API — never to a node directly.

Job

A unit of submitted work, with requirements attached (what it needs to run on). The scheduler decides placement; the job then carries a state and, on completion, an exit result.

Jobs are how the fabric schedules work internally. You do not create them directly: you call the API, and the control plane turns that into placed work on a node that satisfies the requirements.

Region and residency

Work is pinned to a region so data stays inside the jurisdiction you selected. See Data residency.

Authentication

Note

To be written.

Thatch authenticates API requests with a bearer API key issued from the Portal.

curl https://api.thatch.cloud/v1/... \
  -H "Authorization: Bearer $THATCH_API_KEY"

Rules of thumb

• Keys are secrets. Store them in your platform’s secret manager, not in source control, CI logs, or a .env committed by accident.
• Rotate on a schedule, and immediately if a key may have been exposed — see API keys.
• Use one key per application or environment so revoking one doesn’t take everything else down with it.

API overview

Note

To be written. The per-endpoint detail on this page is deliberately thin: it will be generated from the control plane’s OpenAPI contract rather than written by hand, so that it cannot drift. See Endpoint reference below.

Thatch’s customer-facing API is OpenAI-compatible. If you already have code talking to an OpenAI-shaped endpoint, you point it at Thatch by changing the base URL and the key.

Base URL

https://api.thatch.cloud/v1

Authentication

A bearer API key, issued from the Portal and prefixed thatch_sk_:

curl https://api.thatch.cloud/v1/models \
  -H "Authorization: Bearer $THATCH_API_KEY"

A missing or invalid credential is a 401; a valid credential that is not permitted on the route is a 403. See Authentication and Errors.

The surface

All three endpoints are live.

Usage figures here are scoped to the caller. Account-wide billing lives in the Portal — see Usage & metering.

Endpoint reference

The per-endpoint reference is generated from the control plane’s own OpenAPI contract, filtered to the operations that are public, and committed to this repository so it cannot silently disagree with what the API serves. The tooling is in place; it is waiting on the control plane to emit a contract for the serving surface. Until then, this page is the surface.

Versioning

Errors

Note

To be written.

Error response format

Status codes

Retries

Retry 429 and 5xx with exponential backoff and jitter. Never retry 4xx other than 429 — the request will fail identically every time.

Rate limits & quotas

Note

To be written.

Limits

Reading your current usage

When you hit a limit

You get a 429 (Errors). Back off exponentially rather than retrying immediately. If you need a higher ceiling, contact support.

SDKs

Note

To be written.

Until a first-party SDK is published, use the HTTP API directly — see API overview.

Accounts & organisations

Note

To be written.

You manage your account in the Thatch Portal. If your login belongs to more than one organisation, you choose which one you are viewing.

API keys

Note

Partly written. Creating a key and who may manage one is settled below; the rest of this page is still to come.

Creating a key

In the Portal, open Developers and click Create API key.

The key’s secret is shown once, at creation, and cannot be retrieved afterwards. Copy it somewhere safe before you leave the page — if you lose it, the only way forward is to rotate the key. See Authentication.

Who can manage a key:

• Any member of an organisation can create keys for it, and can rotate or revoke the keys they created.
• Organisation admins can manage every key in the organisation, including keys created by other members.
• A key with no recorded creator is admin-only: an organisation’s admins — and Thatch’s own — can manage it, but a member cannot.
• An API key can never manage keys. Creating, rotating and revoking happen in the Portal as a signed-in member, never by authenticating with a key.

Rotating a key

Create the replacement first, deploy it, confirm traffic has moved, then revoke the old key. Revoking before the replacement is live causes an outage.

Revoking a key

If a key leaks

Revoke it immediately, then rotate. Anything committed to a public repository, pasted into a ticket, or printed in a CI log should be treated as leaked even if you deleted it afterwards — assume it was scraped.

Usage & metering

Note

Partly written. Who can see your usage is settled below; the metering detail is still to come.

Viewing your usage

Sign in to the Thatch Portal and open Cost & Usage. Signing in is enough: every member of an organisation can see that organisation’s usage there, and no API key is required to view it. If your login belongs to more than one organisation, you choose which one you are viewing, and the page shows that organisation’s usage.

Reading usage over the API is different: GET /v1/usage always requires a thatch_sk_ API key. See API overview and API keys.

Billing & invoices

Note

Partly written. Who can see your billing and when a month closes are settled below; the rest of this page is still to come.

Viewing your billing

Sign in to the Thatch Portal and open Billing. Signing in is enough: every member of an organisation can see that organisation’s billing there, and no API key is required to view it.

If your login belongs to more than one organisation, you choose which one you are viewing, and the page shows that organisation’s billing.

The API is a different surface. Calls to /v1/chat/completions, /v1/models and /v1/usage always authenticate with a thatch_sk_ API key — a sign-in session is not a credential for them. See API keys and Authentication.

When a month closes

Billing runs in calendar months, and a month is not closed the instant it ends: a billing month becomes closable at 00:00 New Zealand time on day 2 of the following month, after a 24-hour grace period.

For example, September 2026 became closable at 00:00 NZDT on Friday 2 October 2026.

Until October 2026 the grace period was 48 hours, and a month became closable on day 3 of the following month. A shorter grace cannot lose or double-bill usage.

For a billing question that isn’t answered here, contact support.

Data residency

Important

To be written. This page carries compliance weight — every claim on it must be something the platform actually enforces and can evidence.

Thatch is sovereign-by-region: work is pinned to a region so that data stays inside the jurisdiction you selected.

Choosing a region

What is enforced

Evidencing it

Troubleshooting

Note

Partly written. This page is organised by the symptom a customer sees, not by the subsystem at fault — they don’t know which subsystem it is. The sections marked TODO below are the parts still to come.

401 Unauthorized on every request

Check that the header is Authorization: Bearer <key>, that the key hasn’t been revoked, and that you’re not sending a key from a different environment. See Authentication.

Requests suddenly return 429

You’ve hit a rate limit. See Rate limits & quotas.

A job never leaves its initial state

Intermittent 5xx

Retry with backoff. If it persists, check Status & incidents before opening a ticket.

FAQ

Note

To be written. Only add a question here once it has actually been asked twice.

What is Thatch?

A decentralised distributed data center: independently-owned machines pooled into one coordinated, sovereign-by-region fabric for AI inference. See Core concepts.

Who can see my data?

Where does my work physically run?

Inside the region you selected — see Data residency.

How am I billed?

See Usage & metering.

Can I run Thatch on my own hardware / contribute a node?

Status & incidents

Note

To be written.

During an incident

1. Contact support with your request IDs and timestamps (in UTC).

Contact support

Note

To be written.

What to include

A ticket with these details is usually resolved in one round trip instead of three:

• Request IDs for the failing calls, and timestamps in UTC.
• The exact error returned — status code and body.
• What you expected instead, and when it last worked.
• The region you’re operating in.

Warning

Never include an API key, password, or any other secret in a ticket. If a secret has already been sent to us, treat it as leaked: revoke and rotate it — see API keys.

Glossary

Control plane — the coordinating layer that owns registration, scheduling and routing, billing, and residency enforcement. Customers talk only to its API.

DDDC — decentralised distributed data center. The category Thatch is in: pooling independently-owned, heterogeneous machines into one coordinated fabric.

Fabric — the pooled fleet presented as a single coordinated region.

Node — one participating machine, running the node agent that registers it, reports capacity, health, and power, and executes scheduled work.

Node agent — the software running on a node that connects it to the control plane.

Region — the jurisdictional boundary work is pinned to. See Data residency.

Residency — the guarantee that work and its data stay inside a chosen region.

Trust-minimised — the fleet is coordinated without requiring the individual nodes, or their owners, to be trusted.