Heddwove Start weaving

Docs

Config, credits, and the mill API.

Base URL https://api.heddwove.xyz. OpenAPI lives in the console at /portal/openapi.json. Bearer tokens start with hdw_live_ or hdw_test_.

Quickstart

Install the SDK, write a loom file, and create a run. Warp includes $25 of credits when Rahul’s team issues your first live token.

terminal
npm install @heddwove/sdk
export HEDDWOVE_TOKEN=hdw_test_8f3a
npx heddwove apply heddwove.config.ts
npx heddwove run desk_7f3k "triage inbound mail"

Mail [email protected] from your work address to receive a test token the same weekday. Mill SSO tokens come from the same address.

Config schema

A loom file exports one or more loom() or team() objects. Required keys: identity or a parent team, can (skill list), and limits.

Field Type Meaning
identity business or personal KYC packet the partner collects from a human
threads.mail boolean or domain string Mailbox and DNS on the mill
threads.card.capUsd number Hard authorization cap
threads.postgres boolean Dedicated database
limits.approve string[] Skills that wait on a human
limits.models map of tool to class Routing policy for this loom

Auth

Send Authorization: Bearer hdw_live_…. Test tokens may call every route against the sandbox mill. Live tokens debit credits. Rotate a token with POST /v1/tokens/rotate. Revoke with POST /v1/tokens/revoke.

curl
curl -X POST https://api.heddwove.xyz/v1/looms \
  -H "Authorization: Bearer $HEDDWOVE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"support","config_ref":"heddwove.config.ts"}'

Credits

Credits are prepaid usage. Warp loads $25. Cloth loads $200 per invoice and those credits linger 90 days. Burn order: lingering included credits, then purchased top-ups, then on-demand Warp. Negative balances pause new routes and card authorizations.

Routing policies

Classes A, B, and frontier. A tool that names a class may only receive models in that class. If every model in the class is unavailable, the route fails closed and writes route.denied to the audit log.

POST /v1/route
{
  "loom_id": "loom_7f3k",
  "turn": 12,
  "tool": "research.batch",
  "policy": "class-b",
  "messages": [
    {"role": "user", "content": "Summarize inbound tickets from 09:00 IST."}
  ]
}

Webhooks

Subscribe at POST /v1/webhooks. Events: run.completed, approval.needed, card.declined, route.denied, credit.low. Signatures use HMAC-SHA256 in header X-Heddwove-Signature over the raw body. Retry 8 times over 12 hours.

Local dev

npx heddwove mill local starts a mill on 127.0.0.1:8787 with the test token baked in. Cards, filings, and KYC calls stub to fixtures. Model routes call heddwove-small-1 in the sandbox. Live money movement stays off on localhost.

Limits

Resource Warp Cloth Mill
Looms 8 80 contract
Concurrent runs 4 40 contract
Route payload 256 KB 1 MB 4 MB
Audit retention 14 days 1 year 3 years
Webhook endpoints 2 12 unlimited

API

Five routes cover the mill. Full OpenAPI is in the portal.

surface
POST /v1/looms
POST /v1/runs
POST /v1/route
GET  /v1/audit
POST /v1/cards

POST /v1/looms

Creates a loom from a config ref. Response includes loom_id, thread inventory, and remaining credits.

201
{
  "loom_id": "loom_7f3k",
  "name": "support",
  "threads": ["postgres", "mail", "card"],
  "credits_remaining": 24.18,
  "status": "ready"
}

POST /v1/runs

Starts a durable run. Pass input as the first user turn. The mill writes board state before each tool.

request
{
  "loom_id": "loom_7f3k",
  "input": "Triage inbound mail from this morning.",
  "sleep_after": "15m"
}

POST /v1/route

Routes one model call through policy. See the product page for a billed response body.

GET /v1/audit

Query with loom_id, from, to, and optional skill. Returns primitive calls in order, including denials.

POST /v1/cards

Issues a virtual card on the partner network. Body: loom_id, label, cap_usd. Humans must have completed KYC for that identity before the partner mints the card.

201
{
  "card_id": "card_22ae",
  "last4": "4471",
  "cap_usd": 100,
  "network": "partner_visa",
  "state": "active"
}

Status

Checked 13 August 2026, 16:00 IST. All mill components are weaving.

  • API api.heddwove.xyz operational
  • Routing heddwove-small-1 operational
  • Durable runtime operational
  • Card partner operational
  • Mail and DNS operational

Last incident: 29 July 2026, 14:12 to 14:41 IST. Frontier pass-through queued while a provider region stalled. Class B routes continued. Postmortem mailed to Cloth and Mill seats from [email protected].