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

To be written. This page should take a reader from nothing to a successful response in under five minutes, with no prior Thatch knowledge assumed.

1. Create an account

2. Create an API key

See API keys.

export THATCH_API_KEY="..."

3. Send a request

curl https://api.thatch.cloud/v1/... \
  -H "Authorization: Bearer $THATCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ }'

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.

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. Freeze this against the published OpenAPI document rather than hand-maintaining endpoint tables.

Base URL

https://api.thatch.cloud/v1

Shape of a request

Every request carries a bearer API key (Authentication), sends and receives JSON, and is scoped to one account.

Endpoints

Versioning

Jobs

Note

To be written.

A job is a unit of submitted work with requirements attached. The scheduler places it on a node that satisfies those requirements; the job then carries a state through to completion.

Submit a job

Read job state

Cancel a job

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.

API keys

Note

To be written.

Creating 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

To be written.

Billing & invoices

Note

To be written.

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

To be written. Organise this page by the symptom a customer sees, not by the subsystem at fault — they don’t know which subsystem it is.

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. Check the status page before opening a ticket — it’s updated first.
2. If your problem isn’t reflected there, 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.

Job — a unit of submitted work with requirements attached; the scheduler places it and it carries a state through to completion. See Jobs.

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.

Placement — the scheduler’s decision about which node runs a given job.

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.