This is the full developer documentation for Tanzanite # Tanzanite Documentation > Orchestrate autonomous AI agents from a native app — plan work, run tools, ship results. ## Start here [Section titled “Start here”](#start-here) Install & first run Download Tanzanite, sign in, create your first project, and run your first agent. [Get set up →](/using/getting-started/) Task how-tos Step-by-step guides: import a local folder, schedule a run, add a skill, configure the harness. [Browse how-tos →](/using/how-to/) Account, billing & limits Credits, what a run costs, and the budgets and guardrails that keep spending in check. [Manage your account →](/using/account-billing/) Troubleshooting & FAQ Common errors, a stuck agent, sync issues, and connecting a repo — fixes for the things that come up most. [Find a fix →](/using/troubleshooting/) ## For AI assistants reading this site [Section titled “For AI assistants reading this site”](#for-ai-assistants-reading-this-site) This documentation is machine-readable. A condensed index of every page lives at [`/llms.txt`](/llms.txt) and the full concatenated docs at [`/llms-full.txt`](/llms-full.txt), so your own AI assistant — or Claude inside Tanzanite — can answer “how do I do X in Tanzanite” from the real docs. Every HTML page also has a `text/markdown` alternate — request a page with `Accept: text/markdown` to get clean Markdown. # API reference > Every /v1 endpoint — host-app connection, projects and sessions, agent keys and the resource×verb permission matrix, object-plane routes, spend primitives, size limits and the shared error taxonomy. Every endpoint below is on `https://api.tanzanite.ai`. All of `/v1` is versioned: changes are additive only, and anything breaking arrives as `/v2`. See [the two API surfaces](/developers/overview/#the-two-api-surfaces). `/v1` serves two kinds of caller with two kinds of `tanzanite_…` key: * **A host app** — a product that signs its users in with Tanzanite ([Connect](/developers/connect/)) and runs Tanzanite sessions for them. Its key is the user’s connection to that app, issued by the Connect exchange, and it reaches the [host-app routes](#route-index--host-apps-and-spend-primitives): connection, projects, sessions, tickets and the spend primitives, gated by scopes. * **An agent key** — the account holder’s own key for their own software (ADR-0117). It reaches the object plane and the hosted gadget backends, gated by the `resource.verb` permissions below. ## Authentication [Section titled “Authentication”](#authentication) | Credential | Header | Reaches | | ---------- | --------------------------------------------------------------------------------- | ---------------------------- | | Session | `Authorization: Bearer ` | `/api/*` (the app) and `/v1` | | Agent key | `Authorization: Bearer tanzanite_agent_…` or `X-Tanzanite-Key: tanzanite_agent_…` | `/v1` agent-key routes only | A key calling `/api/*` gets `403 {"error":"not_available_to_api_keys"}` — key minting, billing, 2FA, account settings and secrets are not part of the public contract, whatever the key was granted. Keys are their own records in `agentKeys/{id}`, managed at `/api/agent-keys` (list, mint with step-up, revoke). They are not host-app connections and never appear in one. ## Permissions [Section titled “Permissions”](#permissions) A key’s grants are a list of `resource.verb` chosen when it is minted: ```json { "permissions": ["gadgets.read", "stores.read", "stores.write", "vaults.read"] } ``` | Resource | Verbs | Covers | | -------------- | --------------------------- | --------------------------------------------------------------------------------- | | `gadgets` | read, write, delete, deploy | Gadget documents, gadget types, per-gadget rate limits | | `stores` | read, write, delete | Gadget stores and sync floors | | `vaults` | read, write, delete | The account vault’s cloud copy | | `artifacts` | read, write, delete | Artifact files and metadata | | `settings` | read, write | Account settings (`server-managed` keys are refused) | | `workstations` | read, deploy | Workstation state (read) and deploy/recall (deploy) — never a running workstation | | `permissions` | read | The account’s permission policy (read-only) | | `spend` | read, write | Hosted gadget backends (`/v1/llm`, `/v1/image`, `/v1/video`) | A missing grant is denied with `403 {"error":"insufficient_permission","required":"store.write"}`. `resource.*` and `*` are accepted. A key cannot widen its own grants, write the permission policy, mint keys, or answer a prompt. ## Headers [Section titled “Headers”](#headers) | Header | Direction | Notes | | ----------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `Authorization: Bearer tanzanite_…` | Request | A host app’s connection key (`tanzanite_` + hex) or an agent key (`tanzanite_agent_…`). The two never reach each other’s routes. Backend only. | | `Authorization: Bearer ` | Request | A signed-in user’s session instead of a key. | | `X-Tanzanite-Key: tanzanite_…` | Request | Equivalent alternative to the key header. | | `X-Tanzanite-Embed-Ticket` | Request | A session-scoped ticket, for browsers. Session routes only. | | `Idempotency-Key` | Request | Optional on the spend endpoints. Up to 200 characters, valid 24 hours. | | `Content-Type: application/json` | Request | Required on every body-carrying call. | ## Route index — object plane [Section titled “Route index — object plane”](#route-index--object-plane) | Method | Path | Permission | | ----------------------- | ----------------------------- | -------------------------------------- | | `GET` | `/v1/gadgets` | `gadgets.read` | | `POST` `PATCH` `DELETE` | `/v1/gadgets[/:id]` | `gadgets.write` / `gadgets.delete` | | `GET` `PUT` | `/v1/gadgets/:id/limits` | `gadgets.read` / `gadgets.write` | | `GET` | `/v1/stores/…` | `stores.read` | | `PUT` `DELETE` | `/v1/stores/…` | `stores.write` / `stores.delete` | | `GET` | `/v1/vaults/…` | `vaults.read` | | `PUT` `DELETE` | `/v1/vaults/…` | `vaults.write` / `vaults.delete` | | `GET` | `/v1/artifacts/…` | `artifacts.read` | | `POST` `DELETE` | `/v1/artifacts/…` | `artifacts.write` / `artifacts.delete` | | `GET` `PATCH` | `/v1/settings` | `settings.read` / `settings.write` | | `GET` | `/v1/permissions/policy` | `permissions.read` | | `GET` | `/v1/workstations/:id/state` | `workstations.read` | | `POST` | `/v1/workstations/:id/deploy` | `workstations.deploy` | An agent key reads and writes objects; it does **not** run a workstation — no presence, no live gadgets, no lease. ### Size limits [Section titled “Size limits”](#size-limits) | Object | Limit | | --------------- | ------------------------------------------------- | | Gadget document | 1 MB | | Store document | 4 MB | | Vault file | streamed; per-file cap enforced by the vault lane | | Artifact | capped by the artifact lane | ## Route index — host apps and spend primitives [Section titled “Route index — host apps and spend primitives”](#route-index--host-apps-and-spend-primitives) | Method | Path | Scope | | -------- | ------------------------------------------------------------------------------------------- | ---------------------- | | `GET` | [`/v1/connection`](#get-v1connection) | none | | `DELETE` | [`/v1/connection`](#delete-v1connection) | none | | `POST` | [`/v1/stream-ticket`](#post-v1stream-ticket) | none | | `POST` | [`/v1/sessions/:id/embed-ticket`](#post-v1sessionsidembed-ticket) | none | | `POST` | [`/v1/sessions`](#post-v1sessions) | `agent.sessions` | | `GET` | [`/v1/sessions/:id`](#get-v1sessionsid) | `agent.sessions` | | `POST` | [`/v1/sessions/:id/signal`](#post-v1sessionsidsignal) | `agent.sessions` | | `POST` | [`/v1/sessions/:id/human-input/:inputId`](#post-v1sessionsidhuman-inputinputid) | `agent.sessions` | | `GET` | [`/v1/sessions/:id/messages`](#get-v1sessionsidmessages) | `agent.sessions` | | `GET` | [`/v1/sessions/:id/subagents/:childId/messages`](#get-v1sessionsidsubagentschildidmessages) | `agent.sessions` | | `POST` | [`/v1/projects`](#post-v1projects) | `projects` | | `GET` | [`/v1/projects`](#get-v1projects) | `projects` | | `GET` | [`/v1/projects/:id`](#get-v1projectsid) | `projects` | | `PATCH` | [`/v1/projects/:id`](#patch-v1projectsid) | `projects` | | `GET` | [`/v1/projects/:id/sessions`](#get-v1projectsidsessions) | `projects` | | `POST` | [`/v1/media/generate`](#post-v1mediagenerate) | `media.generate` | | `GET` | [`/v1/media/jobs/:jobId`](#get-v1mediajobsjobid) | `media.generate` | | `POST` | [`/v1/media/vision`](#post-v1mediavision) | `media.vision` | | `POST` | [`/v1/media/transcribe`](#post-v1mediatranscribe) | `media.vision` | | `POST` | [`/v1/completions`](#post-v1completions) | `completions` | | `POST` | [`/v1/decisions`](#post-v1decisions) | `decisions` | | `GET` | [`/v1/estimates`](#get-v1estimates) | none | | `GET` | `/v1/usage` | any spend scope (read) | | `GET` | `/v1/models` | any spend scope (read) | | `GET` | [`/v1/wallet`](#get-v1wallet) | any spend scope | ## Connection [Section titled “Connection”](#connection) ### `GET /v1/connection` [Section titled “GET /v1/connection”](#get-v1connection) **Auth** tenant key · **Scope** none Who this key is. Call it at start-up to confirm a stored key still authenticates and still holds the scopes your feature needs, rather than discovering both from a `403` in front of a user. ```json { "id": "conn_9f3…", "hostAppId": "acme-studio", "subject": "Qm9Ft4c…", "name": "Acme Studio", "status": "active", "scopes": ["agent.sessions", "projects", "media.generate"], "hostAppVersion": 3, "toolCount": 7, "baseUrl": "https://api.acme.example/v2" } ``` `status` is `active`, `suspended` or `revoked`; only `active` authenticates. `hostAppVersion` is the definition version the user consented at — compare it against what a capability needs before you use one that is newer. `subject` is your app’s stable id for the key’s user, the same one the Connect exchange returned ([Connect](/developers/connect/)); a personal access token has none (`null`). ### `DELETE /v1/connection` [Section titled “DELETE /v1/connection”](#delete-v1connection) **Auth** tenant key · **Scope** none Revoke this connection. ```json { "id": "conn_9f3…", "status": "revoked" } ``` **Immediate and final.** The key stops authenticating, running sessions fail closed at their next round, and there is no un-revoke — the user reconnects through [Connect](/developers/connect/), which mints a new connection. Call this when a user disconnects your app on **your** side. You do not need to call it before a reconnect: the platform already revokes a user’s previous connection to the same app. ## Tickets [Section titled “Tickets”](#tickets) Tickets exist so a browser can stream a session without ever holding the tenant key. Both are short-lived and **session-scoped**: a ticket reaches session routes only, and never a connection-scoped one. A widget holding a ticket therefore cannot create sessions, cannot list projects, and cannot spend money on its own — your backend does all of that, then hands the browser a ticket for the one session it should see. ### `POST /v1/stream-ticket` [Section titled “POST /v1/stream-ticket”](#post-v1stream-ticket) **Auth** tenant key · **Scope** none Mint a ticket for the WebSocket stream. ### `POST /v1/sessions/:id/embed-ticket` [Section titled “POST /v1/sessions/:id/embed-ticket”](#post-v1sessionsidembed-ticket) **Auth** tenant key · **Scope** none Mint a multi-use embed ticket bound to one session. This is what an embedded widget uses: pass it, with the `sessionId` and the API base URL, to a ticket-only [SDK client](/developers/sdk/#ticket-only-mode-browsers). Send it as `X-Tanzanite-Embed-Ticket` on session routes. Tickets expire; mint a fresh one when the widget reconnects rather than caching one indefinitely. ### Streaming [Section titled “Streaming”](#streaming) Session events arrive over a WebSocket at `wss://api.tanzanite.ai/v1/stream`, authenticated with a stream ticket or an embed ticket. The [SDK](/developers/sdk/#streaming) handles the connection, the reconnect backoff and the resync marker for you; the event shapes are listed there. ## Sessions [Section titled “Sessions”](#sessions) ### `POST /v1/sessions` [Section titled “POST /v1/sessions”](#post-v1sessions) **Auth** tenant key · **Scope** `agent.sessions` · **Spends** ```json { "projectId": "proj_7bd…", "goal": "Add three ambush encounters to the crypt level.", "context": { "sceneId": "scene_main" }, "guardrails": { "maxSubagents": 2, "requireToolApproval": false } } ``` | Field | Required | Notes | | ------------ | -------- | --------------------------------------------------------------------- | | `projectId` | Yes | The project to run in. There is no implicit project. | | `goal` | Yes | What the agent should accomplish. | | `context` | No | Pinned onto every tool call; the pin wins over model-supplied values. | | `guardrails` | No | `maxSubagents`, `requireToolApproval`. | `201`: ```json { "sessionId": "sess_4c1…", "roundId": "round_1", "status": "queued" } ``` **Errors** | Status | Body | | ------ | ------------------------------------------------------------------------------ | | `400` | `{ "error": "project_required" }` | | `403` | `{ "error": "insufficient_scope", "scope": "agent.sessions" }` | | `403` | `{ "error": "reconsent_required", "hostAppVersion": 3, "requiredVersion": 4 }` | | `402` | `{ "error": "insufficient_credits" }` | | `402` | `{ "error": "host_app_spend_cap" }` | | `429` | `{ "error": "too_many_sessions", "limit": 3 }` | ### `GET /v1/sessions/:id` [Section titled “GET /v1/sessions/:id”](#get-v1sessionsid) **Auth** tenant key or embed ticket · **Scope** `agent.sessions` ```json { "id": "sess_4c1…", "status": "orchestrating", "projectId": "proj_7bd…", "hostAppId": "acme-studio", "goal": "Add three ambush encounters to the crypt level.", "cost": { "totalCost": 0.184, "totalTokens": 41233, "promptTokens": 37110, "completionTokens": 4123, "ownCost": 0.121, "subagentsCost": 0.043, "mediaCost": 0.02 }, "createdAt": "2026-09-10T09:12:04.221Z", "updatedAt": "2026-09-10T09:14:51.008Z", "completedAt": "2026-09-10T09:14:51.008Z", "completionReport": "…", "context": { "usedTokens": 42310, "contextWindow": 200000, "compactAtTokens": 153600, "estimated": false, "compacting": false } } ``` `completedAt`, `completionReport` and `error` are present only when they apply. `context` is how full the model’s context window is: `null` until the first LLM call has been measured; `compactAtTokens` is where the agent compacts on its own (`null` when compaction is off); `estimated` is true right after a compaction, before the next call measures it. The stream’s `context` frame carries the same reading as it changes. `cost.totalCost` is USD, **billed** — the whole of what the session cost the user: its own work, every subagent’s, and the `/v1` spend you attributed to its tool calls (Tanzanite sends your tool endpoint an `X-Tanzanite-Tool-Call` token; forward it unchanged on the media, vision, decisions and completions requests you make while serving that call). Each dollar is counted once, so a host app that reads only `cost.totalCost` has the right total. `ownCost`, `subagentsCost` and `mediaCost` break it down — they sum to `totalCost` — and each is **absent** when it is 0 or unknown (`mediaCost` is absent for a session whose host-app spend predates the breakdown; `totalCost` still includes it). `/v1` spend made without the header belongs to no session and is in none of them. The token counts are the session’s own agent’s. A running session’s cost can trail a few seconds behind its spend; a completed one is final. The sessions list’s `cost` and the stream’s `cost_update` / `complete` `totalCost` are this same whole figure. `status` is one of the SDK’s `SESSION_STATUSES`; `complete`, `failed`, `cancelled` and `enqueue_error` (the session could not be started) are terminal — treat the list as open and keep a default branch. `404` if the session does not exist or belongs to another connection’s user. ### `POST /v1/sessions/:id/signal` [Section titled “POST /v1/sessions/:id/signal”](#post-v1sessionsidsignal) **Auth** tenant key or embed ticket · **Scope** `agent.sessions` ```json { "type": "redirect", "message": "Two encounters, not three — the level is short." } ``` | `type` | Extra fields | Effect | | ---------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pause` | `reason` | Halt after the current step. | | `resume` | `newBudget` | Continue; optionally raise the cost budget. | | `cancel` | `reason` | Stop for good. | | `redirect` | `message` | Push a new instruction into the running session. | | `compact` | — | Compact the agent’s context now. Running: it compacts after its current step. Idle (`complete`, `failed`, `cancelled`, `waiting_human`): a compaction starts at once. | `redirect` is how you say “not that, do this instead” without cancelling and paying for a fresh start. Every signal answers `202 { sessionId, signal, message }`. `compact` adds `mode` — `"latched"` (after the current step) or `"started"` (with the compaction’s `roundId`). A refused `compact` answers `409 { error, code }`: | `code` | Meaning | | --------------------- | -------------------------------------------------------------------- | | `compaction_running` | A compaction is already in flight. | | `nothing_to_compact` | No LLM call has been measured yet. | | `compaction_disabled` | Compaction is off for this session. | | `not_compactable` | The session’s status allows neither (e.g. `paused`, `waiting_wake`). | ### `POST /v1/sessions/:id/human-input/:inputId` [Section titled “POST /v1/sessions/:id/human-input/:inputId”](#post-v1sessionsidhuman-inputinputid) **Auth** tenant key or embed ticket · **Scope** `agent.sessions` Answer a question the agent asked. `inputId` comes from the `human_input_needed` event. ```json { "approved": true } ``` Send `choiceId` for a selection, `freeText` for a clarification, `approved` for a confirmation, an approval or a tool approval. A session that is never answered stays waiting rather than timing out into a decision on your behalf. ### `GET /v1/sessions/:id/messages` [Section titled “GET /v1/sessions/:id/messages”](#get-v1sessionsidmessages) **Auth** tenant key or embed ticket · **Scope** `agent.sessions` Query: `limit` (rounds per page), `after` (a previous page’s `lastRoundId`). ```json { "sessionId": "sess_4c1…", "messages": [ { "roundId": "round_3", "role": "assistant", "content": "…", "timestamp": "2026-09-10T09:13:02.114Z" } ], "hasMore": true, "lastRoundId": "round_3" } ``` `role` is `user`, `assistant`, `system` or `tool`; `toolName` and `toolCallId` are present on tool messages. ### `GET /v1/sessions/:id/subagents/:childId/messages` [Section titled “GET /v1/sessions/:id/subagents/:childId/messages”](#get-v1sessionsidsubagentschildidmessages) **Auth** tenant key or embed ticket · **Scope** `agent.sessions` A subagent’s transcript, paged exactly like [`GET /v1/sessions/:id/messages`](#get-v1sessionsidmessages) (same query, same response, with `sessionId` set to the subagent). `childId` is the `subagentId` from the `subagent_spawned` event. Authorized through the parent: the caller needs the session (its embed ticket is enough), and `childId` must be one of that session’s subagents. Anything else is `404` with `{ "error": "Subagent not found" }` — a ticket still cannot reach any other session. ## Projects [Section titled “Projects”](#projects) ### `POST /v1/projects` [Section titled “POST /v1/projects”](#post-v1projects) **Auth** tenant key · **Scope** `projects` ```json { "externalId": "level_42", "label": "Level 42 — Crypt", "url": "https://studio.acme.example/levels/42" } ``` | Field | Required | Limit | | ------------ | -------- | --------------- | | `externalId` | Yes | 200 characters | | `label` | Yes | 200 characters | | `url` | No | 2048 characters | Idempotent per **connected user × host app × `externalId`**. `201` with `created: true` for a new project, `200` with `created: false` when it already existed. Both are success. ```json { "project": { "id": "proj_7bd…", "name": "Level 42 — Crypt", "externalRef": { "hostAppId": "acme-studio", "externalId": "level_42", "label": "Level 42 — Crypt", "url": "https://studio.acme.example/levels/42" }, "hostAppId": "acme-studio", "createdAt": "2026-09-10T09:12:04.221Z", "updatedAt": "2026-09-10T09:12:04.221Z" }, "created": true } ``` The user is part of the idempotency key on purpose — see [why the user is in the key](/developers/projects-and-sessions/#why-the-user-is-in-the-key). ### `GET /v1/projects` [Section titled “GET /v1/projects”](#get-v1projects) **Auth** tenant key · **Scope** `projects` Query: `limit`. ```json { "projects": [ /* ProjectInfo */ ], "limit": 50 } ``` Only **this** host app’s projects, for **this** user. The query is scoped server-side and there is no parameter that widens it. ### `GET /v1/projects/:id` [Section titled “GET /v1/projects/:id”](#get-v1projectsid) **Auth** tenant key · **Scope** `projects` ```json { "project": { /* ProjectInfo */ } } ``` A `404` here is the **lifecycle signal**: the user deleted the project. There is no webhook — drop your mapping and create a fresh project on next use. See [project lifecycle](/developers/projects-and-sessions/#project-lifecycle--there-is-no-webhook). ### `PATCH /v1/projects/:id` [Section titled “PATCH /v1/projects/:id”](#patch-v1projectsid) **Auth** tenant key · **Scope** `projects` ```json { "label": "Level 42 — Catacombs", "url": "https://studio.acme.example/levels/42" } ``` | Field | Required | Limit | | ------- | ----------------------- | ---------------------------------------------------- | | `label` | At least one of the two | 200 characters | | `url` | At least one of the two | 2048 characters; absolute http(s). `null` clears it. | Rename an entity. `POST /v1/projects` never changes an existing project — on a repeat it returns the **first** project’s fields unchanged, which is what makes it safe to call on every open — so when a user renames the thing on your side, or your deep links move, this is how the new label or `url` reaches Tanzanite. `name` follows `label`. `externalId` is not writable: it is the idempotency key, and a different id is a different entity. See [renaming an entity](/developers/projects-and-sessions/#renaming-an-entity). `200`: ```json { "project": { /* ProjectInfo, with the new label and url */ } } ``` **Errors** | Status | Body | | ------ | --------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `{ "error": "invalid_request", "message": "…" }` — empty patch, a field over its limit, or a `url` that is not an absolute http(s) URL. | | `404` | `{ "error": "Project not found" }` — the same answer as `GET`, for a deleted project and for one this connection cannot reach. | ### `GET /v1/projects/:id/sessions` [Section titled “GET /v1/projects/:id/sessions”](#get-v1projectsidsessions) **Auth** tenant key · **Scope** `projects` Query: `limit`, `after` (the `sessionId` of the last row of the previous page). ```json { "sessions": [ { "sessionId": "sess_4c1…", "status": "complete", "message": "Add three ambush encounters to the crypt level.", "createdAt": "2026-09-10T09:12:04.221Z", "updatedAt": "2026-09-10T09:14:51.008Z", "completedAt": "2026-09-10T09:14:51.008Z", "cost": 0.184, "hostAppId": "acme-studio" } ], "hasMore": false, "limit": 50 } ``` Newest first, 50 per page by default and 200 at most. `message` is the goal the session was created with; all three timestamps are ISO 8601, and `completedAt` is absent while a session is still running. ## Media [Section titled “Media”](#media) ### `POST /v1/media/generate` [Section titled “POST /v1/media/generate”](#post-v1mediagenerate) **Auth** tenant key · **Scope** `media.generate` · **Spends** · **Optional `Idempotency-Key`** ```json { "mediaType": "image", "prompt": "A moss-covered stone archway at dusk", "model": null, "size": "1024x1024", "aspectRatio": null, "resolution": null, "quality": null, "seed": null, "sourceImage": null, "projectId": "proj_7bd…" } ``` `sourceImage` is either a URL the platform can fetch, or inline `base64` plus `mimeType`. With `"mediaType": "speech"` the body is `{ "input" (≤ 4000 chars), "model"?, "voice"?, "format"?: "mp3" | "wav", "speed"?, "instructions"?, "projectId"? }` and the result carries `mimeType` (`audio/mpeg` or `audio/wav` — the model decides), `durationMs`, `model`, `voice`, `chars`, `costUSD` and `costSource` (`provider-actual` — OpenRouter’s record of the call — or `catalog`), plus `generationId` / `provider` when known, beside `url` / `storagePath` — see [Generate speech](/developers/media/#generate-speech). ```json { "mediaType": "image", "url": "https://storage.example/signed/…", "expiresAt": "2026-09-10T10:12:04.000Z", "storagePath": "media/…/7f3c1e.png", "mimeType": "image/png", "width": 1024, "height": 1024, "model": "…", "costUSD": 0.042, "idempotent": false } ``` **Synchronous, with a 90-second server-side ceiling.** Set your HTTP client timeout above it — the default 30 seconds will abort a healthy call. `url` expires after 60 minutes; `storagePath` is the durable handle. Full contract on the [Media](/developers/media/) page. **Errors** | Status | Body | | ------ | -------------------------------------------------------------------------------------------------------------- | | `400` | `{ "error": "unsupported_media_type" }` — `video` is not served in v1. | | `402` | `{ "error": "insufficient_credits" }` | | `402` | `{ "error": "host_app_spend_cap" }` | | `403` | `{ "error": "insufficient_scope", "scope": "media.generate" }` | | `409` | `{ "error": "idempotency_key_reused" }` | | `409` | `{ "error": "idempotency_in_progress" }` — the first request under this key is still running; nothing charged. | | `504` | `{ "error": "media_timeout", "ceilingMs": 90000 }` — nothing charged. | **`mediaType: "model"` is the asynchronous exception**: it answers `202` with a job (or `200` with the finished job on an idempotent replay), and the same scope covers polling it. Request, result and error codes are on the [Media](/developers/media/#generate-a-3d-model) page; 3D-specific errors are `400 invalid_request`, `429 too_many_jobs` and `503 model_generation_unavailable`. **`mediaType: "audio"`** (music and sound effects: `kind`, `prompt`, `durationSec`, `loop`, `bpm`, `key`, `layers`, `channels`, `format: "wav"`) is a job of the same shape, on the same poll; see [Media](/developers/media/#generate-music-and-sound-effects). Its own errors are `400 invalid_request`, `429 too_many_jobs` and `503 media_unavailable`; a refused prompt is a failed job (`prompt_blocked`). **`mediaType: "motion"`** (an animation clip on the humanoid skeleton: `prompt`, `duration`, `loop`, `inPlace`, `quality: draft | standard`, `name`) is a job of the same shape too; its result is one GLB (a bare skeleton + one animation) and a summary — see [Media](/developers/media/#generate-a-motion-clip). Its own errors are `400 invalid_request`, `429 too_many_jobs` and `503 motion_generation_unavailable`; a refused prompt is a failed job (`content_refused`), uncharged. ### `GET /v1/media/jobs/:jobId` [Section titled “GET /v1/media/jobs/:jobId”](#get-v1mediajobsjobid) **Auth** tenant key · **Scope** `media.generate` · **Free** (reads a job; the spend happened at `POST`) Returns the job the `POST` accepted — `queued`, `running`, `succeeded` (with `result`) or `failed` (with `error`) — while it is under 24 hours old. A job that belongs to another connection is `404 job_not_found`, the same as one that does not exist. Poll no faster than `pollAfterMs`; the response carries `Retry-After` while the job is pending and `Cache-Control: no-store`. ### `POST /v1/media/vision` [Section titled “POST /v1/media/vision”](#post-v1mediavision) **Auth** tenant key · **Scope** `media.vision` · **Spends** ```json { "images": [{ "url": "https://storage.example/signed/…" }], "question": "Does the archway read as passable?", "measuredContext": "1024x1024 PNG generated from: a moss-covered stone archway at dusk.", "model": null, "projectId": "proj_7bd…" } ``` `images` takes 1 to 4 entries. More than four is refused rather than truncated. ```json { "text": "…", "model": "…", "costUSD": 0.003, "truncated": false, "imageCount": 1 } ``` ### `POST /v1/media/transcribe` [Section titled “POST /v1/media/transcribe”](#post-v1mediatranscribe) **Auth** tenant key · **Scope** `media.vision` · **Spends** · **Optional `Idempotency-Key`** Speech-to-text for a short clip (push-to-talk). The answer is the bare words spoken — no labels, no bracketed events — and `""` when nothing was said. ```json { "audio": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2VibUKHgQRChYEC…", "mimeType": "audio/webm;codecs=opus", "language": "en", "prompt": "Brannoc, Eldermoor", "model": null, "projectId": "proj_7bd…" } ``` `audio` is bare base64 (no `data:` prefix), at most 2 MB decoded. `mimeType` is one of `audio/webm`, `audio/ogg`, `audio/mp4`, `audio/wav`, `audio/mpeg` (a `;codecs=` parameter and common aliases accepted). `language` is an optional BCP-47 hint; `prompt` (≤ 500 characters) lists names and words to expect and is read as a spelling hint, never as instructions. A clip that is too big, empty, not base64 or of an unsupported type is a `400 invalid_request` before any spend. ```json { "text": "Brannoc, open the gate.", "language": "en", "durationMs": 2380, "durationEstimated": false, "model": "openrouter/google/gemini-3.5-flash-lite", "costUSD": 0.0011, "idempotent": false } ``` `language` echoes the hint (`null` without one). `durationEstimated` is `true` when the container did not state its length and it was estimated from the size. A replay under the same `Idempotency-Key` answers `idempotent: true` and `costUSD: 0`. `502 transcription_failed` bills what the failed call spent; past the 90 s ceiling, `504 media_timeout` charges nothing. Details: [Media → Transcribe speech](/developers/media/#transcribe-speech). ## Completions [Section titled “Completions”](#completions) ### `POST /v1/completions` [Section titled “POST /v1/completions”](#post-v1completions) **Auth** tenant key · **Scope** `completions` · **Spends** · **Optional `Idempotency-Key`** One model call, no harness. For the parts of a host app that want a model but not an agent: a rewrite, a classification, a structured extraction. If the work needs tools, a plan, or more than one turn, create a [session](/developers/projects-and-sessions/) instead. ```json { "messages": [ { "role": "system", "content": "You rewrite level descriptions." }, { "role": "user", "content": "Crypt, dark, three rooms." } ], "model": null, "maxTokens": 512, "temperature": 0.4, "reasoning": "off", "jsonSchema": null, "projectId": "proj_7bd…", "tag": "level-copy", "label": "Level 42 · description rewrite" } ``` `reasoning` is `"off"` by default: the model answers without hidden thinking, which is what a short, awaited reply wants — a reasoning model otherwise spends seconds, and part of your `maxTokens`, before the first visible word. Set a level (`minimal`, `low`, `medium`, `high`, `xhigh`, `max`; snapped to the nearest one the model offers) to opt in for a call that needs it, and leave room in `maxTokens` for the thinking. Anything else is `400 invalid_request`. Completions are routed to the model’s fastest available host, not its cheapest. `role` is `system`, `user` or `assistant`. `jsonSchema` is sent to the provider as a forced structured output — the difference between parsing the answer and hoping to — but a model can still answer off-schema, so the response says whether it did: `structuredResult` (the parsed output) with `schemaValid`, or `structuredRaw` (the raw text, when it did not parse as JSON) with `schemaValid: false`. `schemaValid` is absent when your schema itself does not compile. `tag` and `label` are optional and name the spend on the user’s Usage tab: `tag` is 1–64 letters, digits, `_ - : .` (`level-copy`, or one per thing you serve, like `game:abc123`); `label` is one line of at most 120 characters. An invalid one is `400 invalid_request`. ```json { "content": "…", "model": "…", "finishReason": "stop", "usage": { "promptTokens": 122, "completionTokens": 88 }, "costUSD": 0.0009, "idempotent": false, "structuredResult": { "line": "…" }, "schemaValid": true } ``` ## Decisions [Section titled “Decisions”](#decisions) ### `POST /v1/decisions` [Section titled “POST /v1/decisions”](#post-v1decisions) **Auth** tenant key · **Scope** `decisions` · **Spends** · **Optional `Idempotency-Key`** Fast, typed answers about your app’s state — a game bot choosing its next move between ticks, a classifier in a hot path. Each named question is a `noul` (yes/no), a `choice` (one of N) or a `score` (an ordered rubric), and every answer carries a probability. ```json { "requests": [ { "id": "bot:1", "state": { "me": { "x": 3, "hp": 2 }, "enemies": [{ "x": 7, "hp": 5 }] }, "questions": { "move": { "type": "choice", "instructions": "Best move now?", "criteria": { "chase": "close in", "flee": "get away" } } } } ], "model": null, "projectId": "proj_7bd…", "tag": "bot-live", "label": "Crypt · Hunter · match 3" } ``` | Field | Required | Notes | | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `requests` | Yes | 1 to 16 entries — batch the seats of one moment into one call. | | `requests[].id` | No | Echoed on the result. Unique, 1–64 of letters, digits and `_:.-`; defaults to the index. | | `requests[].state` | Yes | A string, object or array; at most 60 000 characters serialized. | | `requests[].questions` | Yes | An object of named questions. | | `model` | No | An enabled decision model. Omit for the platform default. | | `projectId`, `tag`, `label` | No | The project to bill under, and the Usage-tab attribution — as on [completions](#post-v1completions). | ```json { "model": "…", "results": [ { "id": "bot:1", "ok": true, "answers": { "move": { "type": "choice", "choice": "flee", "probabilities": { "chase": 0.18, "flee": 0.82 }, "confidence": 0.82 } }, "latencyMs": 212, "truncated": false, "backend": "…" } ], "costUSD": 0.0004, "idempotent": false } ``` One result per request, in order. A request that fails is reported in its own result as `{ "id", "ok": false, "error", "code"? }`; the others still answer, and the batch is billed once. ## Estimates [Section titled “Estimates”](#estimates) ### `GET /v1/estimates` [Section titled “GET /v1/estimates”](#get-v1estimates) **Auth** tenant key · **Scope** none What one call would cost the connected user, **billed** — for a price you show before a user says yes. Spends nothing. Query: `kind=decision` with `stateChars` (default 4 000), `kind=completion` with `promptTokens` (default 1 000) and `completionTokens` (default 300), `kind=speech` with `chars` (default 1 000; a `mediaType: "speech"` call), or `kind=vision` with `promptTokens` (default 2 000, the images included) and `completionTokens` (default 700) — priced on the model `POST /v1/media/vision` would use for the same `model` (the platform’s vision model when none is named), or `kind=transcribe` with `seconds` (default 15; a `POST /v1/media/transcribe` clip, priced from its audio tokens per second on the model that call would use and answered as `{ "kind": "transcribe", "model", "perCallUSD", "basis": { "seconds" } }`), or `kind=audio` with `layers` (default 1; a `mediaType: "audio"` job, every layer at the music model’s catalog price plus the prompt screen — what the job holds — answered as `{ "kind": "audio", "model", "perCallUSD", "basis": { "generations", "perGenerationUSD" } }`), or `kind=motion` with `quality` (`draft` | `standard`, default `standard`; a `mediaType: "motion"` job: one keyframe-writer call of \~6k prompt + \~4k completion tokens, answered as `{ "kind": "motion", "model", "perCallUSD", "maxUSD", "basis": { "quality" } }` — `maxUSD` is the hold; the quality picks the model); each with an optional `model`. ```json { "kind": "decision", "model": "…", "perCallUSD": 0.0003, "basis": { "stateChars": 4000 }, "typicalLatencyMs": 180 } ``` `typicalLatencyMs` is present for a decision model with a measured latency. A speech estimate adds `"pricing"` (`per_character`, `per_second`, `per_token`, …) and `basis: { chars, estimatedSeconds }`; per-second and per-token models are estimated at a typical narration pace (≈ 15 characters a second), and the actual charge uses the measured audio. Any other `kind`, or a `model` that is not enabled, is `400 invalid_request`. ### `GET /v1/wallet` [Section titled “GET /v1/wallet”](#get-v1wallet) **Auth** tenant key · **Scope** any spend scope What this connection can spend of the user’s credits right now — for a credits check before you start something billed. Spends nothing. ```json { "availableUSD": 12.5, "connectionDailyRemainingUSD": 3, "accountDailyRemainingUSD": null, "accountMonthlyRemainingUSD": 79.5, "autoReload": { "enabled": true, "thresholdUSD": 1, "amountUSD": 10 }, "spendableUSD": 3 } ``` `availableUSD` is credits − reserved − spent (it can be negative). `connectionDailyRemainingUSD` is the daily cap the user set on this connection, less today’s spend and in-flight holds; the account fields are the user’s own daily and monthly caps, likewise. `null` means no such cap. `spendableUSD` is the least of those that apply; with `autoReload` on, the wallet also counts its reload amount (a wallet under its threshold tops itself up on the next spend). A call is still refused if the money is gone by the time you make it. ## Latency [Section titled “Latency”](#latency) **Warm up before a burst.** `GET /v1/wallet` and `GET /v1/estimates` also load, on the instance that answers, what the first paid call of a burst would otherwise load on its own latency (the payer’s billing checks, the model catalogs, prices). Call one of them when a user is about to start something that makes calls in quick succession — a game with bots that think — rather than letting the first call pay for it. It spends nothing. **Where the time went.** Every `/v1` answer carries a `Server-Timing` header: `queue` (event-loop wait), `rl_ip` / `auth` / `rl_conn` (the limiters and the key lookup), the route’s own stages — on `POST /v1/decisions` and `POST /v1/completions`: `consent`, `project`, `idem_claim`, `routing`, `admit`, `hold`, `model`, `settle`, `idem_finish` — and `handler` (the total). All in milliseconds. `model` is the provider call; the rest is Tanzanite. Log it next to your own timing when a call feels slow. ## Error taxonomy [Section titled “Error taxonomy”](#error-taxonomy) Every error body carries a machine-readable `error` field and a human-readable `message`. Branch on `error`, never on the message text. | `error` | Status | Retryable | Remedy | | ------------------------- | ------ | ---------- | --------------------------------------------------------------------------------------------------------------- | | `insufficient_scope` | 403 | No | The connection never held the scope. The user must reconnect granting it. | | `reconsent_required` | 403 | No | Send the user through [Connect](/developers/connect/) again. | | `project_required` | 400 | No | Create a project and pass `projectId`. | | `invalid_request` | 400 | No | The body failed validation; `message` names the field. Fix the request. | | `too_many_sessions` | 429 | Yes | Wait for an in-flight session to finish. | | `insufficient_credits` | 402 | No | The user must add credits. | | `host_app_spend_cap` | 402 | No (today) | This connection’s daily cap is spent. Not “add credits”. | | `billing_unavailable` | 503 | Yes | The balance could not be read. Retry. | | `media_timeout` | 504 | Yes | Outran the 90-second ceiling. **Nothing charged.** Retry with the same `Idempotency-Key`. | | `idempotency_key_reused` | 409 | No | Same key, different body. Pick a fresh key. | | `idempotency_in_progress` | 409 | Yes | The first request under this key is still running. **Nothing charged.** Retry with the same key for its result. | | `unsupported_media_type` | 400 | No | Only `image` and `speech` (and `model` and `audio` as jobs) in v1. | Two distinctions worth wiring into your error handling: * **`host_app_spend_cap` is not `insufficient_credits`.** The wallet has money; this connection is not allowed to spend more of it today. Rendering “add credits” sends the user to the wrong screen. * **`too_many_sessions` is not a rate limit.** It is a concurrency ceiling, and it clears when one of your sessions finishes rather than when a time window rolls over. A `429` that is *not* `too_many_sessions` is a request-rate limit — 1 200 per minute per IP before authentication, 300 per minute per connection after. Respect `Retry-After` when it is present. ## Not in `/v1` [Section titled “Not in /v1”](#not-in-v1) * **No session list endpoint.** Sessions are listed per project, via [`GET /v1/projects/:id/sessions`](#get-v1projectsidsessions). * **No webhooks.** A deleted object is discovered through a `404`; session progress is discovered by streaming or polling. * **No video yet.** It will arrive on `POST /v1/media/generate` as a `202` plus a `GET /v1/media/jobs/:id`, keyed on `mediaType`, the way 3D models and audio did. See [why `mediaType` is a field](/developers/media/#why-mediatype-is-a-field). # Connect a host app > The OAuth 2.0 authorization-code + PKCE flow that turns a Tanzanite user into a connection to your host app — including the consent screen, spend caps, and re-consent. **Connect** is how a Tanzanite user grants your app the right to act on their behalf. It is OAuth 2.0 authorization code with PKCE (RFC 7636), with one addition that is specific to this platform: the exchange also carries **your own per-user credential**, so the platform can call back into your app as that user. The whole flow runs against `https://api.tanzanite.ai` except the consent screen itself, which is on the app origin, `https://app.tanzanite.ai`. ## Before you start [Section titled “Before you start”](#before-you-start) You need a [host-app definition](/developers/overview/#the-two-records) that is connectable by the account you are testing with: your own account can connect a **private** definition; other accounts can connect it once it is **published** (see [how publishing works](/developers/overview/#the-two-records)). Its id is your `client_id`, and its redirect URI allow-list is checked on an exact string match at both ends of the flow. Two rules that will save you an afternoon: * **The `code_verifier` is a secret.** It belongs to your backend. If it reaches your frontend, the code the user carries back becomes redeemable by anyone who intercepts it, and PKCE has bought you nothing. * **`redirect_uri` must match the allow-list byte for byte**, must carry no fragment, and must contain no embedded credentials. A trailing slash is a different string. ## The flow [Section titled “The flow”](#the-flow) ### 1. Fetch the app’s public metadata (optional but useful) [Section titled “1. Fetch the app’s public metadata (optional but useful)”](#1-fetch-the-apps-public-metadata-optional-but-useful) ```bash curl "https://api.tanzanite.ai/api/connect/client?client_id=acme-studio&redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Ftanzanite" ``` ```json { "clientId": "acme-studio", "hostAppId": "acme-studio", "name": "Acme Studio", "description": "Level design and asset generation inside Acme Studio.", "iconUrl": "https://acme.example/icon.png", "requestedScopes": ["agent.sessions", "projects", "media.generate"], "scope": "agent.sessions projects media.generate", "spendScopes": ["agent.sessions", "media.generate"], "version": 3, "verified": true, "defaultSpendCapUSD": 5 } ``` This is what the consent screen renders, and it is also a cheap pre-flight: it validates the `redirect_uri` against the allow-list before you send a user anywhere. Checking here means a misconfigured redirect surfaces in your own logs rather than as an error page in front of a user mid-connect. ### 2. Mint a PKCE pair and send the user to the consent screen [Section titled “2. Mint a PKCE pair and send the user to the consent screen”](#2-mint-a-pkce-pair-and-send-the-user-to-the-consent-screen) Your **backend** generates the pair. Only `S256` is accepted — `plain` makes the challenge equal to the verifier, so anyone observing the authorize request could redeem the code, and it is refused rather than quietly accepted. ```ts import { createPkcePair, createConnectState, buildConnectAuthorizeUrl, } from "@tanzanite/sdk/connect"; const { codeVerifier, codeChallenge } = await createPkcePair(); const state = createConnectState(); // Store both against the user's pending-connect record, server-side. await savePendingConnect(userId, { codeVerifier, state }); const url = buildConnectAuthorizeUrl({ appUrl: "https://app.tanzanite.ai", clientId: "acme-studio", redirectUri: "https://acme.example/oauth/tanzanite", codeChallenge, state, }); // → redirect the user's browser to `url` ``` The URL it builds is: ```plaintext https://app.tanzanite.ai/connect ?client_id=acme-studio &redirect_uri=https%3A%2F%2Facme.example%2Foauth%2Ftanzanite &code_challenge= &code_challenge_method=S256 &state= &scope= &reuse_consent=1 (optional, see "Reconnecting without asking again") ``` `scope` is optional and usually best omitted: the definition already names its `requestedScopes`, and repeating the list in your authorize URL is one more place for it to go stale. Pass it only when you deliberately want to ask for **less** than the definition requests. `state` is not a secret and is not a substitute for PKCE. It exists so your callback can confirm the response belongs to a flow you started. ### 3. The user consents [Section titled “3. The user consents”](#3-the-user-consents) The consent screen is a first-party surface — you do not build it and you do not call it. It shows the user: * Your app’s **name, icon and description**, taken from the definition rather than from anything a caller sent. * The **scopes** being requested, with the credit-spending ones marked as such. * A **provenance marker**: first-party or reviewed, versus an unverified third party. An author controls their own display name, so an unverified app is labelled as one no matter how plausible its name is. * The **daily spend cap**, pre-filled — **5 USD** for a verified app, **1 USD** for an unverified one. The user can change it or clear it. * The **concurrent-session ceiling**, defaulting to **3** and raisable to at most **20**. For completeness — this is the consent screen’s own call, made after the user clicks approve, and a host app never makes it: ```http POST https://api.tanzanite.ai/api/connect/authorize Content-Type: application/json { "client_id": "acme-studio", "redirect_uri": "https://acme.example/oauth/tanzanite", "state": "…", "code_challenge": "…", "code_challenge_method": "S256", "scope": "agent.sessions projects media.generate", "spend_cap_usd": 5, "max_concurrent_sessions": 3 } ``` It answers `{ "redirectTo": "…", "expiresAt": "…" }`, and the browser follows `redirectTo`. For a refresh Connect the screen sends `"reuse_consent": true` and no limits; the server answers `409` `consent_required` when it cannot approve from the previous consent, and the screen then asks the user as usual. ### 4. The user lands back on your redirect [Section titled “4. The user lands back on your redirect”](#4-the-user-lands-back-on-your-redirect) ```plaintext https://acme.example/oauth/tanzanite?code=&state= ``` or, if something went wrong: ```plaintext https://acme.example/oauth/tanzanite?error=access_denied&state= ``` Compare `state` against what you stored. If it does not match, stop — do not exchange the code. ### 5. Exchange the code, from your backend [Section titled “5. Exchange the code, from your backend”](#5-exchange-the-code-from-your-backend) ```ts import { buildConnectTokenRequest, parseConnectGrant } from "@tanzanite/sdk/connect"; const body = buildConnectTokenRequest({ clientId: "acme-studio", redirectUri: "https://acme.example/oauth/tanzanite", code, codeVerifier, // the secret half, from your pending record credential: await mintAcmeTokenFor(userId), description: "Acme Studio", // optional label in the user's connections list }); const res = await fetch("https://api.tanzanite.ai/api/connect/token", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }); const grant = parseConnectGrant(await res.json()); await storeTenantKeyServerSide(userId, grant.apiKey); ``` A successful exchange is `201`: ```json { "connectionId": "conn_9f3…", "hostAppId": "acme-studio", "subject": "Qm9Ft4c…", "apiKey": "tanzanite_live_xxxxxxxxxxxx", "name": "Acme Studio", "baseUrl": "https://api.acme.example/v2", "status": "active", "toolCount": 7, "scope": "agent.sessions projects media.generate", "scopes": ["agent.sessions", "projects", "media.generate"], "hostAppVersion": 3 } ``` `subject` is **your app’s stable id for the user who consented**. It is the same every time that user connects to your app — a reconnect mints a new `connectionId`, never a new `subject` — and a different value for every other app, so it cannot be used to follow a user across apps. It is not their Tanzanite user id. Key your own account on it if you sign users in with Tanzanite: the exchange runs server to server, so a `subject` in this response is proof of who consented. ## `credential` — the field that is easy to get wrong [Section titled “credential — the field that is easy to get wrong”](#credential--the-field-that-is-easy-to-get-wrong) `credential` is **your app’s own per-user token**. It is what Tanzanite presents back to your API on every tool call made for that user, using the auth shape your definition declares. It is not a Tanzanite key, and it is not the user’s password. Mint a scoped, revocable token for it. Two properties matter: * **You must be able to revoke it independently.** If a user disconnects on your side, or you detect abuse, killing that one token must be enough — you should never need Tanzanite’s cooperation to cut off access to your own API. * **It should carry only the reach your tools need.** It authenticates every tool call the agent makes on that user’s behalf, so a token that could do more than your published tools is reach you did not intend to grant. The credential is stored encrypted and is returned to nobody, including the response above. ## What the exchange no longer carries [Section titled “What the exchange no longer carries”](#what-the-exchange-no-longer-carries) Earlier versions of this flow accepted the app’s own definition — name, `baseUrl`, `toolsUrl`, tool catalog, prompt context — with every user’s token exchange. That meant the app’s identity was whatever the last caller said it was, and the tool catalog was authored once per connection instead of once per app. The definition is now authored once and reviewed before it is connectable, and the exchange carries only `credential`. If you are porting from that older shape, delete those fields from your request body; they are no longer read. ## `apiKey` is shown once [Section titled “apiKey is shown once”](#apikey-is-shown-once) The tenant key in the exchange response is the only time you will ever see it. There is no endpoint that returns it again. Store it server-side at the moment you receive it; if you lose it, the user has to reconnect. ## Re-connecting [Section titled “Re-connecting”](#re-connecting) A user can connect your app again at any time — to widen scopes, to change their spend cap, or after they disconnected. Reconnecting **mints a new connection and revokes the previous one for that same user and app**, so: * The old tenant key stops authenticating. Overwrite your stored key with the new one rather than keeping both. * Nothing is orphaned. Projects, session history and spend are keyed on the host app, not the connection, so everything the user already had is still there under the new key. ### Reconnecting without asking again [Section titled “Reconnecting without asking again”](#reconnecting-without-asking-again) When your stored key stops working (another reconnect superseded it, or you lost it), the user would normally see the consent screen again and re-approve what they already approved. Opt in to skip that: ```ts const url = buildConnectAuthorizeUrl({ appUrl: "https://app.tanzanite.ai", clientId: "acme-studio", redirectUri: "https://acme.example/oauth/tanzanite", codeChallenge, state, reuseConsent: true, // adds reuse_consent=1 }); ``` If Tanzanite can approve from the consent the user already gave, the browser passes through a brief “Reconnecting…” page and lands on your redirect with a `code`, exactly as after a click. Your callback and your exchange are unchanged. The new connection carries the **same limits** the user set before (daily spend cap, concurrent sessions) and no scope beyond what the previous one held. Tanzanite decides this on its own servers, from its own records, and only when **all** of these hold. Otherwise the normal consent screen shows, with no error, so setting the flag on any reconnect is safe: * The signed-in user has a previous connection to your app that came through the consent screen, and it is still active (or was only replaced by a newer connection of the same user). * They did not disconnect it. A disconnect from the Tanzanite app, from your app via `DELETE /v1/connection`, a password reset, a sign-out of all sessions, an account suspension and every other revocation all mean the next Connect asks again. * Your definition is at the same `version` they consented to and its verified state has not changed. * The scopes being requested are no wider than the previous connection’s. Why it is not a shortcut for a malicious link: the code is bound to the PKCE challenge in the link and redeemable only with the verifier your server holds; it is only ever sent to a `redirect_uri` on your definition’s allow-list; the user must be signed in to Tanzanite; and nothing is widened, since the limits and scopes can only equal or undercut what the user granted before. You can also revoke from your side with [`DELETE /v1/connection`](/developers/api-reference/#delete-v1connection). Do that when a user disconnects your app in *your* interface. You do not need to call it before a reconnect — the platform already revokes the previous connection. ## Re-consent when a definition widens [Section titled “Re-consent when a definition widens”](#re-consent-when-a-definition-widens) Any change to a definition that **widens reach** — a new harness tool group, a new scope, a higher `dangerLevel` ceiling — bumps its `version`. A connection that consented at an older version keeps everything it was already granted and is refused only the new capability: ```json { "error": "reconsent_required", "hostAppVersion": 3, "requiredVersion": 4 } ``` with status `403`. The remedy is to send that user back through Connect. Handle this explicitly: it is the one refusal whose fix is a user journey rather than a retry or a top-up. Changes that do not widen reach — a better description, a new icon, a tool removed, a narrower parameter — do not bump the version and need no re-consent. ## Error responses during Connect [Section titled “Error responses during Connect”](#error-responses-during-connect) | Condition | Response | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `redirect_uri` not on the allow-list, has a fragment, or has embedded credentials | `400` | | `code_challenge_method` other than `S256` | `400` | | Code already redeemed, expired, or issued for a different `client_id` | `400` | | `code_verifier` does not match the challenge | `400` | | `credential` missing or empty | `400` | | Definition is not published, or not connectable by this account | `403` | | Refresh Connect: consent was withdrawn between approval and exchange | `409` `consent_required` (the user sees the consent screen on the next attempt) | Codes are single-use and short-lived. Exchange one immediately on receipt, and treat a failed exchange as “start the flow again” rather than something to retry. # Media > Image generation, text-to-speech, speech-to-text, AI-written 3D models, generated music and sound effects, animation clips, and vision on the connected user's credits — the 90-second ceiling for images, the job you poll for 3D models, audio and motion, expiring URLs, and idempotency keys that stop a retry charging twice. `POST /v1/media/generate`, `POST /v1/media/vision` and `POST /v1/media/transcribe` give a host app a model without an agent. No plan, no tools, no transcript — you send a prompt or some images and get an answer back on the same connection. All of them spend the connected user’s credits. Image generation, [speech](#generate-speech), vision and [transcription](#transcribe-speech) are **synchronous**; that property drives most of this page. **3D models and audio are asynchronous** — a job you poll — and have their own sections: [3D models](#generate-a-3d-model), [music and sound effects](#generate-music-and-sound-effects), [motion clips](#generate-a-motion-clip). ## Generate an image [Section titled “Generate an image”](#generate-an-image) Scope: `media.generate`. ```bash curl -X POST https://api.tanzanite.ai/v1/media/generate \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: acme-job-7f3c1e" \ -d '{ "mediaType": "image", "prompt": "A moss-covered stone archway at dusk, painterly, muted palette", "size": "1024x1024", "projectId": "proj_7bd…" }' ``` ```json { "mediaType": "image", "url": "https://storage.example/signed/…", "expiresAt": "2026-09-10T10:12:04.000Z", "storagePath": "media/…/7f3c1e.png", "mimeType": "image/png", "width": 1024, "height": 1024, "model": "…", "costUSD": 0.042, "idempotent": false } ``` ### Request fields [Section titled “Request fields”](#request-fields) | Field | Notes | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaType` | `"image"`. See [why this is a field](#why-mediatype-is-a-field). | | `prompt` | What to generate. Required. | | `model` | Provider-namespaced model id. Omit for the platform default. | | `size` | e.g. `"1024x1024"`. | | `aspectRatio` | e.g. `"16:9"`. | | `resolution` | e.g. `"1080p"`. | | `quality` | Provider-dependent. | | `seed` | Reproducibility, where the provider honours it. | | `sourceImage` | Edit or vary an existing image instead of generating from the prompt alone. A URL the platform can fetch, or inline `base64` plus `mimeType`. | | `projectId` | Bill and file the result under one of your projects. | `size`, `aspectRatio` and `resolution` overlap — pick the one your model understands rather than sending all three. Set `projectId`. Without it the result is not attached to anything the user can find in the Tanzanite interface, and the spend is harder for them to place. `model` in the response is the model that **actually** served the request, which is not always the one you asked for. Log it if you care. ## Generate speech [Section titled “Generate speech”](#generate-speech) Scope: `media.generate`. Text to speech — a trailer voiceover, a narrator line — on the same endpoint, synchronous, under the same ceiling, with the same `Idempotency-Key` replay. ```bash curl -X POST https://api.tanzanite.ai/v1/media/generate \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: acme-vo-91c2" \ -d '{ "mediaType": "speech", "input": "In a world where every block falls, one hero builds.", "voice": "am_michael", "format": "mp3", "projectId": "proj_7bd…" }' ``` ```json { "mediaType": "speech", "url": "https://storage.example/signed/…", "expiresAt": "2026-10-25T10:12:04.000Z", "storagePath": "media/…/91c2.mp3", "mimeType": "audio/mpeg", "durationMs": 4180, "model": "hexgrad/kokoro-82m", "voice": "am_michael", "chars": 52, "costUSD": 0.000036, "costSource": "provider-actual", "generationId": "gen-1761400000-…", "provider": "DeepInfra", "idempotent": false } ``` | Field | Notes | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaType` | `"speech"`. | | `input` | The text to speak. Required, at most **4000 characters** — split a longer script into several calls. | | `model` | An enabled speech model, e.g. `hexgrad/kokoro-82m` (cheap, fast). Omit for the platform default: the **cheapest** enabled model for a typical \~600-character line. Gemini TTS (`google/gemini-*-tts`, expressive, takes `instructions`) is priced per token and is **off until its pricing is verified** on a live call — asking for it is a `400` saying “pricing for this model is not verified yet”. | | `voice` | One of the model’s voices. Kokoro: `am_michael`, `am_onyx`, `am_fenrir`, `am_puck`, `af_heart`, `af_bella`, `af_nova`, `bm_daniel`, `bf_emma`, … Gemini: `Puck`, `Fenrir`, `Charon`, `Kore`, `Zephyr`, `Orus`, … An unknown voice is a `400`. | | `format` | `"mp3"` (default) or `"wav"` — a **preference**. The format follows the model: Gemini TTS and HeyGen answer only WAV, MiniMax only MP3. `mimeType` says what you got. | | `speed` | Playback multiplier, where the model honours it. | | `instructions` | Delivery direction (“deep, dramatic trailer narrator”), ≤ 1000 characters. Gemini, OpenAI and Fish Audio TTS honour it; other models ignore it. | | `projectId`, `tag`, `label` | As for images. | `durationMs` is **measured** from the file (the WAV header, or by walking the MP3’s frames). If the file cannot be read, it is estimated from the text and the result carries `"durationEstimated": true`. **What it costs.** You pay what the call **really cost**: after the audio comes back, Tanzanite reads OpenRouter’s own record of the generation (its `X-Generation-Id`) and bills that, plus the platform markup — `"costSource": "provider-actual"`, with the `generationId` and the upstream `provider` that served it. The record can lag a moment; if it has not answered within about 3 seconds, the call is billed from the model’s catalog price instead (`"costSource": "catalog"`): most speech models are priced **per character** of `input` (Kokoro ≈ $0.62 per million characters before the markup), a few per second of the measured audio (Seed Audio). `costUSD` is always exactly what was charged. The hold is priced from the model’s catalog rate and the text before the call (over a slow read, for per-second models); an empty wallet is `402 insufficient_credits`. If the real cost comes in above the hold, the full real cost is still charged — the call already happened — and your next call is gated on what is left. Ask first with [`GET /v1/estimates?kind=speech&chars=N`](/developers/api-reference/#get-v1estimates) (a catalog estimate, for the same default model when you name none). ## Vision [Section titled “Vision”](#vision) Scope: `media.vision`. ```bash curl -X POST https://api.tanzanite.ai/v1/media/vision \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "images": [{ "url": "https://storage.example/signed/…" }], "question": "Does the archway read as passable, or as a dead end?", "measuredContext": "1024x1024 PNG. Generated from the prompt: a moss-covered stone archway at dusk.", "projectId": "proj_7bd…" }' ``` ```json { "text": "It reads as passable…", "model": "…", "costUSD": 0.003, "truncated": false, "imageCount": 1 } ``` `images` takes **1 to 4** entries, each either a URL the platform can fetch or inline `base64` plus `mimeType`. More than four is refused rather than silently truncated. Put everything you already **know** into `measuredContext`: dimensions, the prompt that produced the image, what it is meant to depict, the constraint you are checking against. A vision model asked to infer a fact it cannot see from the pixels does not say so — it answers confidently and wrongly. `measuredContext` is the cheapest accuracy improvement available on this endpoint. `truncated: true` means the answer hit the output budget and was cut. Ask a narrower question rather than retrying the same one. To show the price first, [`GET /v1/estimates?kind=vision&promptTokens=N&completionTokens=M`](/developers/api-reference/#get-v1estimates) prices the call on the same model this endpoint would pick (pass the same `model`, or none for the platform’s). ## Transcribe speech [Section titled “Transcribe speech”](#transcribe-speech) Scope: `media.vision` — the same “understand media” grant as vision, so a connection that can describe images can transcribe without reconnecting. Speech-to-text for a **short clip**: a player’s push-to-talk line to a game character, a voice command, a spoken answer. The answer is the bare words — no speaker labels, no `[music]`, no “Here is the transcript:” — ready to hand to your dialogue or decision logic. ```bash curl -X POST https://api.tanzanite.ai/v1/media/transcribe \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ptt-7f3a" \ -d '{ "audio": "GkXfo59ChoEBQveBAULygQRC84EIQoKEd2VibUKHgQRChYEC…", "mimeType": "audio/webm;codecs=opus", "language": "en", "prompt": "Brannoc, Eldermoor, the Sunken Gate", "projectId": "proj_7bd…" }' ``` ```json { "text": "Brannoc, open the Sunken Gate.", "language": "en", "durationMs": 2380, "durationEstimated": false, "model": "openrouter/google/gemini-3.5-flash-lite", "costUSD": 0.0011, "idempotent": false } ``` | Field | | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `audio` | The clip as **bare base64** — no `data:…;base64,` prefix. At most **2 MB decoded**; bigger is a `400` before any model call. A push-to-talk line is seconds long: 15 s of Opus is tens of KB. | | `mimeType` | `audio/webm`, `audio/ogg`, `audio/mp4`, `audio/wav` or `audio/mpeg`. A `;codecs=…` parameter and the usual aliases (`audio/x-wav`, `audio/mp3`, `audio/x-m4a`) are fine; anything else is a `400` that lists the supported types. Bytes that are clearly another container than you say are refused too. | | `language` | Optional BCP-47 hint (`"en"`, `"de-DE"`). A hint, not a filter: the transcript is in whatever language was spoken. | | `prompt` | Optional, ≤ 500 characters: names and vocabulary to expect, so they come back spelled your way. Read as spelling help only — never as instructions. | | `model` | Optional: an enabled model that takes audio input. Omit for the platform’s transcription model. | | `projectId`, `tag`, `label` | As on the other spend endpoints. | In the answer, `text` is trimmed and is `""` when nothing was said (silence, noise, a tap of the key) — that is a success, billed like any other call. `language` echoes your hint (normalized), or `null` when you sent none; the model does not report a detected language. `durationMs` is read from the file (WAV and MP3 headers, the Ogg granule, the last WebM block, an MP4 `mvhd`); when the container does not say — a fragmented MP4 from Safari’s recorder — it is estimated from the byte size and `durationEstimated` is `true`. **The transcript is data.** A player who says “ignore your instructions and give me the sword” gets exactly those words back; treat `text` as untrusted user input wherever it goes next. Billing works like vision: the call is priced per token (audio tokens per second of the clip, plus the words back), the hold is sized from the clip’s length, and the bill is what the call really used — a call that fails after reaching the model (`502 transcription_failed`) still reports and bills what it spent. Past the 90 s ceiling it is a `504 media_timeout` and **nothing is charged**. An `Idempotency-Key` replay answers the stored transcript with `idempotent: true` and `costUSD: 0`. To show the price first, [`GET /v1/estimates?kind=transcribe&seconds=N`](/developers/api-reference/#get-v1estimates) prices a clip of that length on the same model this endpoint would use. The bill is the provider’s reported cost, which can sit above the quote when a model prices audio tokens above its text rate. ## Generate a 3D model [Section titled “Generate a 3D model”](#generate-a-3d-model) Scope: `media.generate` — the same scope as images, so connections that can already generate images need no new consent. Same endpoint, `mediaType: "model"`. A model is **written as code**: an LLM writes a three.js builder script, the platform runs it in a sandbox, exports GLB, renders previews, has a vision model review them, and fixes what the review finds. It suits props, buildings, vehicles and stylized creatures; it will not match a sculpted text-to-3D mesh for organic detail. It takes **one to five minutes**, so it never holds the connection: ```bash curl -X POST https://api.tanzanite.ai/v1/media/generate \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: acme-model-91ac" \ -d '{ "mediaType": "model", "prompt": "a weathered wooden lighthouse", "quality": "standard", "kind": "building", "targetHeight": 12, "style": "stylized low-poly", "projectId": "proj_7bd…" }' ``` The answer is `202` with a job: ```json { "jobId": "mj_3f9a…", "mediaType": "model", "status": "queued", "quality": "standard", "progress": { "stage": "queued", "message": "queued" }, "pollUrl": "/v1/media/jobs/mj_3f9a…", "pollAfterMs": 3000, "estimatedSeconds": 150, "createdAt": "2026-10-21T09:00:00.000Z", "updatedAt": "2026-10-21T09:00:00.000Z", "costUSD": 0, "idempotent": false } ``` Poll `GET /v1/media/jobs/:jobId` (scope `media.generate`) every `pollAfterMs` until `status` is `succeeded` or `failed`. Only the connection that started a job can read it; anything else is `404 job_not_found`, as is a job older than **24 hours**. `progress.stage` moves through `writing`, `reviewing`, `fixing`, `packaging`. ### Request fields [Section titled “Request fields”](#request-fields-1) | Field | Notes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaType` | `"model"`. | | `prompt` | What to build. Required, up to 2000 characters. | | `quality` | `draft`, `standard` (default) or `hero` — see below. | | `targetHeight` | Metres, 0.05–200. **Set it.** Without it every model arrives at whatever size the script happened to choose. Every returned level has exactly this height. | | `style` | e.g. `"low-poly"`, `"stylized"`, `"voxel"`. Keeps one game’s models a set. Up to 120 characters. | | `kind` | `prop` (default), `building`, `vehicle`, `creature`. Selects the guidance and the triangle budget the model works to. | | `referenceImageUrl` | An https image to build toward — e.g. one from image generation. The platform fetches it. | | `lods` | Which detail levels to return, from `lod0`, `lod1`, `lod2`. Default: `draft` → `lod0` + `lod2`; `standard` and `hero` → all three. | | `rig` | `none` (default, a static mesh), `humanoid`, `quadruped`, `bird`, `serpent` or `custom`: build on a skeleton and return a skinned GLB with animation clips — see below. | | `baseSource` | The `source.code` of an earlier result. `prompt` is then an **edit instruction** (“make it taller, red roof”) applied to that script, so the model stays recognisably the same. | | `projectId`, `tag`, `label` | As on the other spend endpoints. | ### Quality [Section titled “Quality”](#quality) | `quality` | What happens | Measured cost / time | For | | ---------- | ------------------------------------------------------------- | -------------------- | ------------------------------------------------ | | `draft` | One writing pass, no review. | \~$0.03 · 1 min | Prototyping, background props. | | `standard` | Written, reviewed from rendered images, up to two fix rounds. | \~$0.05 · 2 min | Most props and buildings. | | `hero` | A stronger writer, up to three fix rounds. | \~$0.4–0.6 · 4–5 min | Bosses, key characters, set pieces. Not a crate. | Costs are what the platform measured on its own prompts (OpenRouter prices, 2026-10-21) and are what the user is charged, markup included — treat them as orders of magnitude, not quotes. Each level also has a **spend cap** (the job stops calling models when it is reached and returns the best model it has), and the wallet hold placed while a job runs is sized to that cap, so a `hero` request needs more headroom in the user’s balance than its typical cost. ### The finished job [Section titled “The finished job”](#the-finished-job) ```json { "jobId": "mj_3f9a…", "mediaType": "model", "status": "succeeded", "costUSD": 0.061, "result": { "mediaType": "model", "lods": [ { "lod": "lod0", "url": "https://storage.example/signed/…", "expiresAt": "2026-10-21T10:03:11.000Z", "storagePath": "media/…/1760000000_0.glb", "mimeType": "model/gltf-binary", "bytes": 212044, "triangles": 4064, "size": { "x": 5.89, "y": 12, "z": 5.63 } } ], "previews": [ { "name": "three-quarter", "url": "https://storage.example/signed/…", "expiresAt": "2026-10-21T10:03:11.000Z", "storagePath": "media/…/1760000000_11.png", "mimeType": "image/png", "width": 512, "height": 512 } ], "source": { "language": "javascript", "code": "function build(detail) { … }", "builder": "three@0.186.1" }, "summary": { "bbox": { "x": 5.89, "y": 12, "z": 5.63 }, "height": 12, "units": "metres", "pivot": "base-center", "up": "+Y", "front": "+Z", "triangles": { "lod0": 4064, "lod1": 2436, "lod2": 788 }, "materials": 7, "quality": "standard", "kind": "building", "critique": { "score": 8, "verdict": "accept", "notes": ["…"], "rounds": 2 }, "warnings": [] }, "models": ["openrouter/deepseek/deepseek-v4.1-flash-1017", "openrouter/anthropic/claude-haiku-5.5"], "costUSD": 0.061 } } ``` * **`lods[]`** — a self-contained GLB per detail level, with its triangle count and bounding box. Every level shares **the same pivot** (the model’s base centre is the origin: bbox centre in x/z, bbox minimum in y) and **the same scale** (one transform, computed from `lod0`), so levels swap without popping. Y is up, units are metres, the front faces +Z. A level that ends up a different height than `lod0` is called out in `summary.warnings`. * **`previews[]`** — five 512×512 PNGs: `front`, `three-quarter`, `side`, `back`, and an orthographic `top` (a minimap icon; the model’s front is at the bottom of the image). Software-rendered with flat lighting, outlines, a shadow and a metre-scaled ground grid, not game-engine renders — use them as thumbnails and impostors, not as marketing images. * **`source`** — the builder script. Send it back as `baseSource` to edit. * **`summary.critique`** — the reviewer’s last verdict and notes; `null` at `draft` quality. `score` is out of 10 and is lenient: it catches gross faults (a missing roof, a floating part), not fine ones. * **`models`** — which models served the request, provider-namespaced like the `model` of an image result. The signed `url`s expire after 60 minutes (`expiresAt`); **copy the files into your own storage**. Re-polling a finished job within its 24 hours returns fresh URLs for the same stored objects. ### Failure, and what is charged [Section titled “Failure, and what is charged”](#failure-and-what-is-charged) A job ends `failed` with an `error` — and **a failed job charges nothing**, however much work it did. ```json { "status": "failed", "costUSD": 0, "error": { "code": "generation_failed", "message": "…" } } ``` | `error.code` | Meaning | | ------------------- | --------------------------------------------------------------------------------------------------- | | `generation_failed` | No script that builds came out after the repair attempts. | | `budget_exceeded` | The spend cap was reached before a usable model existed. | | `timeout` | The quality’s time limit was reached before a usable model existed. | | `invalid_reference` | `referenceImageUrl` could not be fetched, or is not a PNG/JPEG/WebP/GIF under 8 MB. | | `storage_failed` | The model was generated but could not be stored. | | `interrupted` | The server working on the job stopped (a restart or deploy). Retry with the same `Idempotency-Key`. | On success the charge is the sum of every model call the job made, at cost plus the platform markup, itemised as separate usage rows under your `tag`/`label`. ### Idempotency for jobs [Section titled “Idempotency for jobs”](#idempotency-for-jobs) Send `Idempotency-Key` (your own job id, as for images). The job **is** the idempotency record: * the same key and body while the job is running returns the same job (`202`, `idempotent: true`) and starts nothing; * after it finishes, the same call returns the finished job (`200`) with the result — the replay never regenerates and never charges again; * a **failed** job frees its key: retrying starts a fresh attempt on the same `jobId`, charged only if it succeeds; * the same key with a different body is `409 idempotency_key_reused`. Without a key every request is its own job. ### Limits [Section titled “Limits”](#limits) At most **3 jobs in flight per account** on one API instance (and 8 per instance); past that the answer is `429 too_many_jobs` with `retryAfterSeconds`. The SDK surfaces it as a rate-limit refusal. ```ts const crew = new Tanzanite({ apiKey }); const model = await crew.media.generateModel( { mediaType: "model", prompt: "a treasure chest", targetHeight: 0.8, projectId }, { idempotencyKey: jobId, onProgress: (job) => console.log(job.progress.stage) }, ); await fetch(model.lods[0].url); // GLB bytes — copy them into your own storage ``` `generateModel` starts the job and polls it; `startModel` and `job` are the two halves if you want to drive the wait yourself. ### Rigged models [Section titled “Rigged models”](#rigged-models) With `rig` set the model is built on a skeleton and every level’s GLB is a skinned mesh with animation clips, ready for a game engine’s animation player. * `humanoid`, `quadruped`, `bird` and `serpent` start from a ready skeleton with standard bone names and **generated** `idle`, `walk`, `run`, `attack`, `hit` and `die` clips (a bird also `fly`). The writer resizes the skeleton, adds bones (ears, a jaw, extra tails) and may add or replace clips. * `custom`: the writer designs the bones and writes every clip (robots, spiders, machines). * Skinning is **rigid**: each part follows one bone at full weight, so it suits stylized, blocky and mechanical creatures, not smooth organic bends. Left is +X, right is −X (the model faces +Z). Bone names and rest poses are identical at every detail level. * `summary.rig` lists the template, the bones and the clips (name, seconds, loop). `previews` also holds contact sheets of the clips, `pose-walk`, `pose-attack`, … (four frames of a clip in one picture). * Use `kind: "creature"` for animals and characters. There is no extra charge beyond the model calls. ### Textures [Section titled “Textures”](#textures) Any model may carry procedural surface textures (stripes, bricks, planks, scales, spots, speckle, noise, checker, gradient): the writer draws them with `Tex.make`, the GLB embeds each as a base-colour PNG with `TEXCOORD_0`, and the material colour tints it. There is no request field and no extra charge; ask for the look in `prompt` (“tiger-striped fur”, “red brick walls and a slate roof”). At most 8 distinct textures per model, up to 256 × 256 px each. ## Generate music and sound effects [Section titled “Generate music and sound effects”](#generate-music-and-sound-effects) Scope: `media.generate`. Same endpoint, `mediaType: "audio"`, and the **same job shape as 3D models**: `202` with a job, poll `GET /v1/media/jobs/:jobId`, the same idempotency and interrupted-job rules ([Idempotency for jobs](#idempotency-for-jobs)). A track takes 20 seconds to two minutes; one made as `layers` is one generation per layer, run together. ```bash curl -X POST https://api.tanzanite.ai/v1/media/generate \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: acme-music-dungeon-1" \ -d '{ "mediaType": "audio", "kind": "music", "prompt": "a tense dungeon theme, low strings and a slow heartbeat drum", "durationSec": 32, "loop": true, "bpm": 120, "key": "D minor", "layers": ["pad", "bass", "drums", "lead"], "projectId": "proj_7bd…" }' ``` ### Request fields [Section titled “Request fields”](#request-fields-2) | Field | Notes | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mediaType` | `"audio"`. | | `kind` | `music` (default) or `sfx` (a sound effect: an explosion, a door, a coin). | | `prompt` | What to make. Required, up to 2000 characters. | | `durationSec` | Music 4–120 (default 30), sfx 0.1–20 (default 1.5). A target: the model makes “about” this much, the platform cuts to it (below). | | `loop` | Music only: `true` makes a **seamless loop** (no intro, no ending; the join is crossfaded, below). Default `false`. | | `bpm` | 40–240, a whole number. Asked of the model and used to cut the track to **whole bars**. | | `key` | A key name such as `"D minor"`, `"F#"`, `"Bb major"` — asked of the model. | | `layers` | Music only: 2–6 lowercase names, e.g. `["pad", "bass", "drums", "lead"]`. One generation per layer from the same prompt, tempo and key, each asked to play only its part; all are cut to **one common length**. Without a `bpm`, layers are made at 100 BPM. | | `instrumental` | Music: `true` (default) asks for no vocals. | | `channels` | `1` or `2`. Default: music stereo, sfx mono. | | `format` | `"wav"` — the only format: every result is mastered 16-bit PCM WAV. | | `model` | An enabled music model; omit for the platform’s. | | `projectId`, `tag`, `label` | As on the other spend endpoints. | ### What the platform does to the audio [Section titled “What the platform does to the audio”](#what-the-platform-does-to-the-audio) A music model answers “about 30 seconds” — never an exact length, never a seamless loop, and an effect usually starts after some silence. So every result is decoded and **mastered** before it is stored: * **Music** is cut to `durationSec`, rounded down to whole bars when a `bpm` is known. With `loop`, the audio after the cut (2 % of the loop, 30–400 ms) is crossfaded into the head, so the loop’s last sample is followed by what the model really played next — no click, no gap. `crossfadeMs` says how long. * **Layers** are all cut to the shortest layer’s room on the bar grid, so they stay aligned. They are separate generations asked to match: tempo and key come from the prompt and the cut, not from a stem separator, so check that they sit together before shipping them. * **Sound effects** start at their first sound (the silence trimmed is `trimmedMs`), end where they fall quiet or at `durationSec`, with a 2 ms fade-in and a short fade-out, mono by default. * Everything is peak-normalized to −1 dBFS (layers toward a common loudness). A result the platform cannot decode (a model that answered MP3) is returned **as made** with a `warnings` entry: not cut, not looped. ### The finished job [Section titled “The finished job”](#the-finished-job-1) ```json { "jobId": "mj_6d1e…", "mediaType": "audio", "kind": "music", "status": "succeeded", "costUSD": 0.21, "result": { "mediaType": "audio", "kind": "music", "loop": true, "bpm": 120, "key": "D minor", "bars": 16, "lengthMs": 32000, "crossfadeMs": 400, "tracks": [ { "layer": "pad", "url": "https://storage.example/signed/…", "expiresAt": "2026-10-28T20:12:04.000Z", "storagePath": "media/…/1761700000_0.wav", "mimeType": "audio/wav", "bytes": 6144044, "durationMs": 32000, "sampleRate": 48000, "channels": 2, "loop": true, "bars": 16, "crossfadeMs": 400 } ], "models": ["google/lyria-3-clip-preview"], "warnings": [], "costUSD": 0.21 } } ``` `tracks[]` has one entry per layer (in the order asked), or one without `layer`. `progress.stage` moves through `screening`, `generating`, `mastering`, `packaging`. The signed `url`s expire after 60 minutes; copy the files, as for models. ### Prompt screening [Section titled “Prompt screening”](#prompt-screening) Every prompt is screened before any music is paid for. Refused: sexual content, hate or harassment in lyrics, extremist material, reproducing a specific copyrighted song or its lyrics, and imitating a named real singer’s voice. Game themes are fine — battle music, gunshots, explosions, screams, horror. A refused prompt fails the job with `prompt_blocked` and **charges nothing**. ### Cost [Section titled “Cost”](#cost) Charged on success only: each generation at the provider’s reported cost (else the model’s catalog price per clip) plus the screen’s few hundred tokens, with the platform markup. A failed job charges nothing. Ask `GET /v1/estimates?kind=audio&layers=4` for the price of a four-layer track before you start one; the job holds that much while it runs. | `error.code` | Meaning | | ------------------- | ----------------------------------------------------------------------------- | | `prompt_blocked` | The prompt screen refused it (the message says why). | | `generation_failed` | The music model failed or returned no audio. | | `storage_failed` | Made but not stored. | | `interrupted` | The server working on the job stopped. Retry with the same `Idempotency-Key`. | At most **4 audio jobs in flight per account** on one API instance (12 per instance); past that, `429 too_many_jobs`. With no music model enabled the answer is `503 media_unavailable`. ## Generate a motion clip [Section titled “Generate a motion clip”](#generate-a-motion-clip) Scope: `media.generate`. Same endpoint, `mediaType: "motion"`: a prompt such as “a goofy victory dance” in, **one animation clip on a known humanoid skeleton** out, as a GLB you retarget onto your own rigged characters by bone name. It is an **LLM keyframe writer, not motion capture**: a language model writes keyframes for the skeleton’s bones (the platform tells it the bone positions and the axis conventions below, with worked examples), the platform checks them, splines them to 30 fps and packs the GLB. Expect readable, stylised game motion — gestures, taunts, dances, attacks, reactions — not the nuance of captured data. It is asynchronous like 3D models: `202` + a job on the same `GET /v1/media/jobs/:jobId`, the same `Idempotency-Key` rules, charged on success only. ```bash curl -X POST https://api.tanzanite.ai/v1/media/generate \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: acme-motion-17f2" \ -d '{ "mediaType": "motion", "prompt": "a goofy victory dance", "duration": 3, "loop": true }' ``` ### Request fields [Section titled “Request fields”](#request-fields-3) | Field | Notes | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `mediaType` | `"motion"`. | | `prompt` | The motion, in words. Required, up to 1000 characters. A prompt with no words (a bare URL) is a `400`. | | `duration` | Seconds, 0.5–12. Absent: the writer chooses (typically 1–4 s). | | `loop` | `false` (default). `true` makes a cycle: the last frame equals the first on every bone. A loop has no net travel. | | `inPlace` | `true` (default): the hips’ net horizontal drift is removed (x and z, linearly over the clip), the bob and sway kept. `false` keeps the travel. | | `quality` | `draft` (a fast model) or `standard` (default, a stronger one). | | `name` | The clip (animation) name, `^[a-z0-9][a-z0-9_-]{0,39}$`. Default: the prompt’s lowercase words joined by `-`, at most 40 characters. | | `projectId`, `tag`, `label` | As on the other spend endpoints. | The job looks like a 3D model job with `"mediaType": "motion"` (`pollAfterMs` 2000; `estimatedSeconds` 30 at `draft`, 90 at `standard`; `progress.stage` is `writing`, `fixing`, `packaging`). ### The finished job [Section titled “The finished job”](#the-finished-job-2) ```json { "jobId": "mj_8c1e…", "mediaType": "motion", "status": "succeeded", "costUSD": 0.09, "result": { "mediaType": "motion", "clip": { "storagePath": "media/…/1760000000_0.glb", "url": "https://storage.example/signed/…", "expiresAt": "2026-10-28T10:03:11.000Z", "mimeType": "model/gltf-binary", "bytes": 41208 }, "summary": { "name": "goofy-victory-dance", "duration": 3, "loop": true, "inPlace": true, "fps": 30, "skeleton": "humanoid", "height": 1.8, "bones": ["hips", "spine", "chest", "neck", "head", "upper_arm_l", "upper_arm_r", "lower_arm_l", "lower_arm_r", "thigh_l", "thigh_r", "shin_l", "shin_r"], "travel": { "x": 0, "y": 0, "z": 0 }, "turn": 0, "warnings": [] }, "models": ["anthropic/claude-sonnet-5.5"], "costUSD": 0.09 } } ``` * **`summary.bones`** — the bones the clip animates. **`travel`** — the hips’ position at the end minus at the start, in metres (zero in x/z for an in-place clip or a loop). **`turn`** — the hips’ yaw change over the clip in radians, `+` = toward the character’s left. **`warnings`** — what the platform clamped or closed (an angle past ±π, a loop whose last key did not match its first). * The `url` expires after 60 minutes, as for every media result; copy the file. ### The GLB and the skeleton [Section titled “The GLB and the skeleton”](#the-glb-and-the-skeleton) The file has **no mesh and no skin** — only the skeleton and one animation: * One node per bone of the `humanoid` template at height 1.8 m, named and parented exactly as the rigged models of `mediaType: "model"` with `rig: "humanoid"`: `root` → `hips` → `spine` → `chest` → `neck` → `head`; `chest` → `upper_arm_l/_r` → `lower_arm_l/_r` → `hand_l/_r`; `hips` → `thigh_l/_r` → `shin_l/_r` → `foot_l/_r`. The scene’s one root node is `root`. * Each node’s `translation` is its rest position minus its parent’s (`root` at the origin, `hips` 0.954 m up); **every rest rotation is identity**. * One animation named `name`, LINEAR samplers, one shared input: times 0 … duration every 1/30 s (`round(duration × 30) + 1` samples, the last exactly at `duration`). A `rotation` channel (unit quaternions) for every animated bone, and a `translation` channel on `hips` (rest translation + offset) when the hips move. `root` is never animated. * Axes: the character faces **+Z**, **+Y** is up, its **left is +X** (`_l` bones have x > 0). Because the rest rotations are identity, a key’s quaternion is the bone’s rotation from rest in its parent’s frame: a hanging arm or leg swings forward with a negative rotation about X, a knee bends with a positive one, the left arm rises sideways with +Z and the right with −Z, the hips turning with +Y turn the character to its left. To play it on your own character, map these bone names onto your rig and apply each rotation as a delta from your bone’s rest pose (or, for a rig built by `mediaType: "model"` with `rig: "humanoid"`, play it as is). ### Refusals, failure and cost [Section titled “Refusals, failure and cost”](#refusals-failure-and-cost) The writer itself is the moderation: it refuses a prompt that is sexual, depicts or celebrates real-world atrocities or hate, or is not a body motion at all, and the job fails with `content_refused` — **nothing charged**. Ordinary game action (fighting, dying, taunting) is fine. The only fixed screen is that a prompt must contain words. | `error.code` | Meaning | | ------------------- | ----------------------------------------------------------------------------- | | `content_refused` | The writer refused the prompt. Nothing charged. | | `generation_failed` | The keyframes were still unusable after two repair calls. | | `budget_exceeded` | The spend cap ($0.10 raw at `draft`, $0.40 at `standard`) was reached first. | | `timeout` | The time limit (2 min at `draft`, 4 min at `standard`) was reached first. | | `storage_failed` | Made but not stored. | | `interrupted` | The server working on the job stopped. Retry with the same `Idempotency-Key`. | Charged on success only: one usage row per model call at the provider’s cost plus the markup — usually one call, up to three when the platform sends the writer’s keyframes back to be fixed. `GET /v1/estimates?kind=motion&quality=standard` gives the price of a typical job (`perCallUSD`) and the hold (`maxUSD`). At most **3 motion jobs in flight per account** on one API instance (8 per instance), else `429 too_many_jobs`; with no writer configured, `503 motion_generation_unavailable`. ## Images are synchronous, not a job queue [Section titled “Images are synchronous, not a job queue”](#images-are-synchronous-not-a-job-queue) Image generation and vision return no job id: the request is held open and answered with the result. There is a server-side ceiling of **90 seconds** on an image `POST /v1/media/generate`. (3D models, audio and motion are the exceptions, above.) The ceiling is not arbitrary. The API sits behind a proxy whose origin read timeout would cut a longer request off before the platform could answer — the caller would get a bare gateway error, with no way to know whether the work had happened or whether they had been charged. So the platform answers first, at 90 seconds, with a clean, documented refusal: ```json { "error": "media_timeout", "ceilingMs": 90000 } ``` with status `504`. **Nothing is charged.** Retry it — ideally with the same `Idempotency-Key`. ### Set your client timeout above 90 seconds [Section titled “Set your client timeout above 90 seconds”](#set-your-client-timeout-above-90-seconds) This is the single most common integration bug on this endpoint. Most HTTP clients default to 30 seconds; the Tanzanite SDK does too. A default-configured client will abort a perfectly healthy generation at 30 seconds, and your code will see a client-side timeout for a request the platform is still serving and will still complete. Give this one call a timeout comfortably above the ceiling — 120 seconds is a reasonable figure — and let the platform’s own `media_timeout` be the thing that ends a call that is genuinely too slow. ```ts const crew = new Tanzanite({ apiKey, timeout: 120_000 }); ``` ## `Idempotency-Key` [Section titled “Idempotency-Key”](#idempotency-key) Optional, up to **200 characters**, valid for **24 hours**. A synchronous spend endpoint has exactly one dangerous failure mode: your client gives up on a call the platform is still serving, you retry, and the user pays twice for one image. The idempotency key closes it. Send **your own job id** — the identifier your system already has for the piece of work — rather than a random value generated at the call site. A random value generated per attempt is a different key on the retry and buys you nothing. ```bash -H "Idempotency-Key: acme-job-7f3c1e" ``` A replay returns the original result with `idempotent: true`, and **charges nothing**. Treat that flag as informational; the response is otherwise identical to the first one. Reusing a key with a **different request body** is a collision, not a replay, and is refused: ```json { "error": "idempotency_key_reused" } ``` with status `409`. Retrying it unchanged collides again — pick a fresh key. This is deliberately not a silent success: answering a different question with a cached result is worse than an error. A retry that arrives while the **first request is still running** is refused rather than run a second time: ```json { "error": "idempotency_in_progress", "retryAfterSeconds": 5 } ``` with status `409`. Nothing is charged for it. Retry with the same key after a moment and you receive the first request’s result once it has finished. ## The `url` expires; `storagePath` does not [Section titled “The url expires; storagePath does not”](#the-url-expires-storagepath-does-not) The signed `url` in a generation response is valid for **60 minutes**, and `expiresAt` tells you exactly when it stops working. `storagePath` is the durable handle. So: **download the bytes, or copy them into your own storage, and do not persist the `url` as though it were permanent.** An app that stores signed URLs in its database has built a feature that works for an hour and then reports broken images to every user who comes back the next day. A URL you have just received is fine to hand straight to a vision call, or to render in a page the user is looking at right now. It is the storing that is the mistake. ## Media types in v1 [Section titled “Media types in v1”](#media-types-in-v1) `mediaType` accepts `"image"` and `"speech"` (synchronous) and `"model"`, `"audio"` and `"motion"` (async jobs). `"video"` is refused: ```json { "error": "unsupported_media_type", "supported": ["image", "speech"], "asyncSupported": ["model", "audio", "motion"] } ``` with status `400`. ### Why `mediaType` is a field [Section titled “Why mediaType is a field”](#why-mediatype-is-a-field) Video and long audio cannot finish inside a 90-second synchronous ceiling, so they need a different response shape: a `202` with a job id, plus a `GET /v1/media/jobs/:id` to poll. **3D models already use exactly that shape**, on **this same endpoint**, keyed on `mediaType` — which is why `mediaType` is a body field rather than a path segment. Had the route been `POST /v1/media/image`, adding models would have meant a new URL, a second client method, and a fork in every caller’s code. It was an additive change: a new accepted value, a new response shape for that value, and nothing that existed before behaves differently. Audio and motion arrived the same way; video will. ## Errors [Section titled “Errors”](#errors) | Status | Body | Meaning | | ------ | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `{ "error": "unsupported_media_type" }` | `video`. Not served in v1. | | `400` | `{ "error": "invalid_request" }` | A field failed validation (the `message` names it). On `/transcribe`, also a clip over 2 MB, empty audio or an unsupported `mimeType` (with `supported`). | | `502` | `{ "error": "transcription_failed" }` | The transcription model failed. What it spent is billed (`costUSD`); retryable under the same key, as a second spend. | | `404` | `{ "error": "job_not_found" }` | Polling a job that does not exist, is older than 24 hours, or belongs to another connection. | | `429` | `{ "error": "too_many_jobs", "retryAfterSeconds": 15 }` | Too many 3D model, audio or motion jobs in flight for this account. | | `503` | `{ "error": "media_unavailable" }` | No music model is enabled (audio). | | `503` | `{ "error": "model_generation_unavailable" }` | 3D model generation is not configured on this deployment. | | `503` | `{ "error": "motion_generation_unavailable" }` | Motion generation is not configured on this deployment. | | `402` | `{ "error": "insufficient_credits" }` | The user’s balance is empty. Not retryable. | | `402` | `{ "error": "host_app_spend_cap" }` | This connection’s daily cap is spent. Not “add credits”. | | `403` | `{ "error": "insufficient_scope", "scope": "media.generate" }` | The connection never held the scope. | | `409` | `{ "error": "idempotency_key_reused" }` | Same key, different body. Pick a fresh key. | | `409` | `{ "error": "idempotency_in_progress" }` | The first request under this key is still running. **Nothing charged.** Retry with the same key. | | `504` | `{ "error": "media_timeout", "ceilingMs": 90000 }` | Outran the ceiling. **Nothing charged.** Retry with the same key. | ## Related [Section titled “Related”](#related) * [`POST /v1/completions`](/developers/api-reference/#post-v1completions) — the same shape for text: one model call, no harness, no agent. Reach for a [session](/developers/projects-and-sessions/) instead when the work needs tools, a plan, or more than one turn. # Overview > Embed Tanzanite agents in your own product — the two API surfaces, the two records behind an integration, scopes, rate limits, and the versioning promise. Tanzanite’s integration API lets an external product — a game editor, a document tool, a CAD package, a CRM — put a Tanzanite agent inside its own interface. Your users connect their own Tanzanite account once, and from then on your backend can create agent sessions, generate images, ask vision questions and make model calls **on their credits, inside a workspace scoped to your app**. A product that integrates this way is called a **host app**: your app hosts the agent, rather than the agent hosting your app. That word is used consistently throughout these pages. Three things are worth understanding before you write any code, because each one prevents a class of mistake later: * There are [**two API surfaces**](#the-two-api-surfaces), and only one of them is for you. * An integration is [**two records**](#the-two-records), not one — a definition and a connection — and they have different lifetimes. * Every session is [**confined to a project**](/developers/projects-and-sessions/), and a project belongs to one user of one host app. ## The two API surfaces [Section titled “The two API surfaces”](#the-two-api-surfaces) | Path | Auth | For | Versioned | | -------- | -------------------------------------------- | --------------------------------------------- | ------------------------------ | | `/api/*` | Firebase ID token (session auth) | Tanzanite’s own first-party app backend | No — may change without notice | | `/v1/*` | Tenant key, or a session-scoped embed ticket | Third-party host apps (this API, and the SDK) | Yes | Everything on this site’s developer pages is on the API origin, `https://api.tanzanite.ai`. `/api/*` is the first-party app talking to its own backend. It is not a public contract, it carries no compatibility promise, and it is documented here only where the Connect flow crosses it. **`/v1` does not accept Firebase ID tokens** — if you have one, you are on the wrong surface. `/v1` is the surface for host apps. Its promise is narrow and therefore keepable: changes within `/v1` are **additive only** — new endpoints, new optional request fields, new response fields. Anything that would break an existing caller gets a `/v2` instead. Write your clients so an unknown response field is ignored rather than rejected, and you will not have to touch them. There is deliberately no OpenAPI document: the route count is well below the point at which a generated spec pays for its own drift, so these pages plus the typed [SDK](/developers/sdk/) are the contract. ## Authentication [Section titled “Authentication”](#authentication) A tenant key is minted for one user’s connection to one host app at the end of the [Connect flow](/developers/connect/). It looks like `tanzanite_…` and it is a **backend credential**. Send it either way: ```bash curl https://api.tanzanite.ai/v1/connection \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" # equivalent curl https://api.tanzanite.ai/v1/connection \ -H "X-Tanzanite-Key: tanzanite_live_xxxxxxxxxxxx" ``` The key is returned exactly once, by the token exchange, and is never retrievable again. Store it server-side, encrypted at rest, keyed by your own user id. It must never reach a browser, a mobile binary, or a log line. Browsers get **tickets** instead. A ticket is short-lived, bound to one session, and reaches session-scoped routes only — never a connection-scoped one. That is what lets an embedded widget stream an agent’s output without ever holding a credential that could create sessions or spend money on its own. See [`POST /v1/stream-ticket` and `POST /v1/sessions/:id/embed-ticket`](/developers/api-reference/#tickets). ## The two records [Section titled “The two records”](#the-two-records) An integration is **a definition plus a connection**, and conflating them is the most common early mistake. **The host-app definition** is authored once on a Tanzanite account and describes your app for every user who will ever connect: its name, description and icon, its `baseUrl` and `toolsUrl`, its tool catalog, the prompt context its agents carry, the harness tool groups its sessions may use, the scopes it requests, its redirect URI allow-list, and a `version`. Its id doubles as your OAuth `client_id`. Authoring is self-serve. A new definition is **private**: connectable by your own account only, so you can connect it, run it and iterate with nobody else exposed. Being connectable by other accounts (**published**) is a review: 1. **You ask** — *Request publication* in Tanzanite → Host apps. The platform checks a short list first: the app is private (not a draft), has at least one redirect URI, a tool catalog, a consent-screen description, no reserved word in its name or id, and **a connection from your own account** — an app its author never ran is not ready for anyone else. Anything missing is listed in one response. 2. **Tanzanite decides** — approve (optionally marking the app *verified*, which changes what the consent screen says about it) or reject with a reason you see in the dashboard. Withdraw a pending request at any time. A published app is published at the shape a reviewer saw. An edit that widens its reach — a new tool group, a new scope, a higher `dangerLevel` ceiling — bumps its `version` **and returns it to review**. It stays connectable by your account meanwhile; other accounts can connect again once the new version is approved, and existing connections must re-consent to it. Names are yours to choose except the platform’s own: `tanzanite`, `tanz`, `official` and `verified` are refused as whole words in a name or id, in either case, so a consent screen cannot be dressed as first-party. **A connection** is one user’s grant to one host app: the tenant key, the scopes they consented to, the definition `version` they consented at, a daily spend cap and an in-flight session ceiling. One user connecting to your app twice does not produce two live connections — reconnecting mints a new one and the platform revokes the previous one for that same user and app. The division exists because the alternative failed in a specific way: when the app’s identity travelled with each user’s token exchange, the last caller silently redefined the app for everyone, and the tool catalog was authored once per connection instead of once per app. Now the exchange carries only your own per-user credential, and nothing a caller sends can change what the app is. ### Reads are keyed on the host app, not the connection [Section titled “Reads are keyed on the host app, not the connection”](#reads-are-keyed-on-the-host-app-not-the-connection) Every `/v1` read is scoped by `(user, host app)` — never by connection id. This matters the first time a user reconnects: their projects, their session history and their spend all stay exactly where they were, because none of it was filed under the connection that was just replaced. A user disconnecting and reconnecting your app is a routine, non-destructive act. ## Scopes [Section titled “Scopes”](#scopes) A connection holds a subset of the scopes its definition requests. Every `/v1` route names the one scope it needs; a route called without it is refused with `403` and `{ "error": "insufficient_scope", "scope": "…" }`. | Scope | Grants | Spends credits | | ---------------- | --------------------------------------------------------------------------------------------------- | -------------- | | `agent.sessions` | Create and drive agent sessions in this app’s projects | Yes | | `projects` | Create, list and read this app’s projects and their sessions | No | | `media.generate` | `POST /v1/media/generate` (images, speech, and 3D models as a polled job), `GET /v1/media/jobs/:id` | Yes | | `media.vision` | `POST /v1/media/vision` | Yes | | `completions` | `POST /v1/completions` | Yes | | `decisions` | `POST /v1/decisions` | Yes | On the wire, scopes are space-separated, in vocabulary order (RFC 6749 §3.3): `agent.sessions projects media.generate`. The consent screen marks the credit-spending ones explicitly, so ask only for what you use — a scope list that includes three spend scopes for a feature that generates one image is a consent screen users abandon. ## Rate limits [Section titled “Rate limits”](#rate-limits) Three limits apply, and they exist for different reasons: * **1 200 requests per minute per IP**, applied *before* authentication and failing closed. This one protects the front door, so an unauthenticated flood is rejected without ever costing a database read. A request refused here has not been attributed to your connection. * **300 requests per minute per connection**, applied after authentication. * **A ceiling on concurrent sessions per connection** — sessions that are still running, not requests. The default is **3** and the maximum a user can raise it to at consent is **20**. Exceeding it is `429` with `{ "error": "too_many_sessions", "limit": 3 }`, which is retryable the moment one of your sessions finishes. The concurrency ceiling is separate from the request rate limit on purpose: they have different remedies. A rate limit is answered by slowing down; a session ceiling is answered by finishing or cancelling work, or by asking the user to raise it. ## Spending [Section titled “Spending”](#spending) Everything a host app does that costs money is charged to **the connected user’s** credit balance, never to yours. Two things can stop a charge: * The user has no credits — `402` with `{ "error": "insufficient_credits" }`. Retrying changes nothing; they must add credits. * The daily cap the user set on *this connection* at consent is spent for the UTC day — `402` with `{ "error": "host_app_spend_cap" }`. The wallet has money; this connection may not spend more of it today. Render those two differently. Showing “add credits” for a spend-cap refusal sends the user to the wrong screen. To check before you start, `GET /v1/wallet` (any spend scope, free) returns what this connection can spend right now — the wallet, this connection’s daily cap, the account’s caps and auto-reload — and `spendableUSD`, the least of them. Each spend request may carry a `tag` and a `label` the user sees on their Usage tab and CSV: `tag` is 1–64 letters, digits, `_ - : .` (`bot-live`, or one per thing you serve, like `game:abc123`), `label` a line of up to 120 characters. ## Where to go next [Section titled “Where to go next”](#where-to-go-next) * [Connect](/developers/connect/) — the OAuth 2.0 + PKCE flow that mints a connection, and what the consent screen shows the user. * [Projects & sessions](/developers/projects-and-sessions/) — the unit of work, and exactly what a session can and cannot reach. * [Tool definitions](/developers/tool-definitions/) — publishing the tools your app exposes to the agent. * [Media](/developers/media/) — the synchronous image and vision endpoints, the asynchronous 3D model endpoint, and why they differ. * [API reference](/developers/api-reference/) — every `/v1` route, field by field. * [SDK](/developers/sdk/) — the typed TypeScript client for all of the above. # Projects & sessions > One project per connected user per entity, how to map your own records onto it, and exactly what an integration session can and cannot reach. A **project** is the workspace an agent session runs in. Every session your app creates lives in one, and there is no implicit or default project: a session with nowhere to live has no settings, no tool policy, no spend attribution and no row the user can open to see what your app has been doing on their behalf. The rule is: > **One project per (connected user × host app × external entity).** An “external entity” is whatever your app’s unit of work is — a level, a document, a repository, a campaign. You name it with an `externalId` that is opaque to Tanzanite. ## Why the user is in the key [Section titled “Why the user is in the key”](#why-the-user-is-in-the-key) Two collaborators working on the same document each connect their own Tanzanite account. The same `externalId` therefore maps to **two different projects, in two different accounts** — and both are correct. Creation is idempotent per user, so the second collaborator’s project creation is a genuine creation, not a duplicate of the first’s. The practical consequence: **store your mapping per user, not per entity.** ```plaintext WRONG entity_id -> tanzanite_project_id RIGHT (your_user_id, entity_id) -> tanzanite_project_id ``` An app that keys its mapping on the entity alone will hand the second collaborator the first collaborator’s project id, and every call with it will fail — that project is in an account this connection cannot reach. ## Creating a project [Section titled “Creating a project”](#creating-a-project) ```bash curl -X POST https://api.tanzanite.ai/v1/projects \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "externalId": "level_42", "label": "Level 42 — Crypt", "url": "https://studio.acme.example/levels/42" }' ``` ```json { "project": { "id": "proj_7bd…", "name": "Level 42 — Crypt", "externalRef": { "hostAppId": "acme-studio", "externalId": "level_42", "label": "Level 42 — Crypt", "url": "https://studio.acme.example/levels/42" }, "hostAppId": "acme-studio", "createdAt": "2026-09-10T09:12:04.221Z", "updatedAt": "2026-09-10T09:12:04.221Z" }, "created": true } ``` `created` tells you which happened — `201` with `created: true` for a new project, `200` with `created: false` when the reservation already existed. **Both are success.** Calling this on every open of an entity is the intended usage, not something to guard against; it is the cheapest way to keep your mapping honest without tracking creation state yourself. ### The external reference [Section titled “The external reference”](#the-external-reference) `externalRef` is how the project points back at your app. | Field | Meaning | Limit | | ------------ | -------------------------------------------- | --------------- | | `hostAppId` | Your app. Set by the platform, not by you. | — | | `externalId` | Your id for the entity. Opaque to Tanzanite. | 200 characters | | `label` | What a human sees in the project list. | 200 characters | | `url` | Deep link back into your app. Optional. | 2048 characters | Set `url`. It is what makes the project badge in the Tanzanite interface clickable, and it is most of the answer to “I am looking at this in Tanzanite and I cannot see the thing it is about”. A user who can get from the agent’s work back to your app in one click is a user who trusts the integration. ### Renaming an entity [Section titled “Renaming an entity”](#renaming-an-entity) `POST /v1/projects` never changes an existing project. On a repeat it returns the **first** project’s fields unchanged — that is what makes it safe to call on every open — so a new `label` in the body of a repeat create is not an update; it is ignored. When a user renames the thing on your side, or your deep links move, push the change explicitly: ```bash curl -X PATCH https://api.tanzanite.ai/v1/projects/proj_7bd... \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "label": "Level 42 — Catacombs", "url": "https://studio.acme.example/levels/42" }' ``` ```json { "project": { "id": "proj_7bd…", "name": "Level 42 — Catacombs", "externalRef": { "…": "…" } } } ``` Send either field or both; `url: null` clears the link, and the project’s `name` follows the label. `externalId` is not writable — it is the idempotency key, and a different id is a different entity. A `404` here means the same thing it means on `GET`: the project is gone, drop your mapping. ## Project lifecycle — there is no webhook [Section titled “Project lifecycle — there is no webhook”](#project-lifecycle--there-is-no-webhook) Users can delete a project in Tanzanite at any time. There is no callback, and this is deliberate: the reconciliation mechanism is a `404`. ```plaintext GET /v1/projects/:id → 404 ``` A `404` here means the user deleted the project. Drop your stored mapping for that entity and create a fresh project on next use. One idempotent `POST /v1/projects` and you are whole again — which is exactly what your code already does on every open. The inverse case needs no handling at all: if your app simply stops referencing a project, nothing special happens. It stays in the user’s account as ordinary history, visible and deletable by them like any other project. ## What a session can and cannot reach [Section titled “What a session can and cannot reach”](#what-a-session-can-and-cannot-reach) An integration session is **confined to its own project**. This is not advice or a convention — it is enforced at tool dispatch, and it is what makes it safe for a user to connect a third-party app to an account that also holds their unrelated work. A session **can**: * Call your host app’s own tools, which appear to the agent as `integration_` with their descriptions prefixed `[]`. * Call the harness tool groups your definition was granted. * Call the baseline: the completion protocol, orchestration tools, and a small utility set. These carry no reach into the user’s other resources. A session **cannot**: * Read or write the user’s other projects — including ones created by a different host app, and including the user’s own. * Reach a tool outside the grant, by any route. Naming it directly does not work, and neither does discovering it: a tool outside the grant reports **“not available in this session”** rather than appearing and failing. * Escalate through a sub-agent. **A sub-agent can never hold more than its parent** — the capability grant is stamped at spawn and narrowed, never widened. And by construction, a host-app project has **no repository and no device folder**. There is no checkout to reach, so file, git and shell tools are withdrawn rather than merely blocked. That is a stronger property than a blocklist: there is nothing for them to operate on. ### Harness tool groups [Section titled “Harness tool groups”](#harness-tool-groups) Your definition names the groups its sessions may use. They are granted at review time, expanded into concrete tool names once at session creation, and enforced for the life of the session. | Group | What it covers | | ------------------ | ------------------------------------------------------ | | `media.generation` | Generating images, video and audio. | | `media.transform` | Editing and transforming existing images and video. | | `documents` | Structured data and document handling. | | `web` | Web fetching and search, and browser automation. | | `files` | File-system and git tools. | | `code` | Writing and running code. | | `subagents` | Spawning quarantined sub-agents to parallelise work. | | `knowledge` | Skills and past-session context. | | `management` | Enumerating and managing projects, plans and settings. | A freshly authored definition gets `media.generation` and nothing else. Ask for groups you actually use — each one widens what a session can do inside the user’s account, and each addition bumps your definition version and requires every existing user to re-consent. Two notes: * **`management` is never granted by default.** It is the group whose tools authorize by *user* rather than by *plan*, so granting it is precisely what would let an app enumerate a user’s unrelated work. Treat a request for it as something you will have to justify. * **`files` does nothing useful in a host-app project.** There is no workspace for it to act on. Granting it costs you a version bump and buys you nothing. ## Creating a session [Section titled “Creating a session”](#creating-a-session) ```bash curl -X POST https://api.tanzanite.ai/v1/sessions \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "projectId": "proj_7bd…", "goal": "Add three ambush encounters to the crypt level, balanced for level 8 players.", "context": { "sceneId": "scene_main", "levelId": "level_42" }, "guardrails": { "maxSubagents": 2, "requireToolApproval": false } }' ``` ```json { "sessionId": "sess_4c1…", "roundId": "round_1", "status": "queued" } ``` Scope: `agent.sessions`. The session begins processing immediately. ### `context` is a pin, not a hint [Section titled “context is a pin, not a hint”](#context-is-a-pin-not-a-hint) Everything in `context` is merged into the arguments of **every tool call the session makes**, and the pin **wins** over anything the model supplies for the same key. That makes it the right place for the identifiers your tools must not be allowed to guess: the scene the user actually has open, the tenant id, the document revision. A model that cannot influence a value cannot get it wrong. Put ids there. Do not put instructions there — instructions belong in `goal`. ### Session statuses [Section titled “Session statuses”](#session-statuses) `queued`, `planning`, `orchestrating`, `waiting_subagents`, `waiting_human`, `waiting_human_review`, `paused`, `complete`, `failed`, `cancelled`. Treat this list as open: `/v1` may add statuses additively, so switch on the ones you handle and have a default branch. ## Driving a session [Section titled “Driving a session”](#driving-a-session) | Call | Purpose | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `GET /v1/sessions/:id` | Status, cost (billed total, with an own / subagents / media breakdown), timestamps, completion report or error. | | `GET /v1/sessions/:id/messages` | Paginated transcript. | | `POST /v1/sessions/:id/signal` | `pause`, `resume`, `cancel`, `redirect`. | | `POST /v1/sessions/:id/human-input/:inputId` | Answer a question the agent asked. | `redirect` sends a new instruction into a running session — the way to say “not that, do this instead” without cancelling and paying for a fresh start. `resume` optionally raises the cost budget of a session that paused against it. ### Human input [Section titled “Human input”](#human-input) When an agent needs a decision it cannot make, it emits a `human_input_needed` event carrying an `inputId`, a `question`, a `category` (`clarification`, `selection`, `confirmation`, `approval`, `tool_approval`), optional `choices`, and whether free text is allowed. The session waits in `waiting_human` until you answer: ```bash curl -X POST https://api.tanzanite.ai/v1/sessions/sess_4c1.../human-input/input_9 \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{ "approved": true }' ``` Send `choiceId` for a selection, `freeText` for a clarification, `approved` for a confirmation or approval. A session that is never answered stays waiting — it does not time out into a decision on your behalf, which is the point. ## Session history [Section titled “Session history”](#session-history) ```bash curl "https://api.tanzanite.ai/v1/projects/proj_7bd.../sessions?limit=20" \ -H "Authorization: Bearer tanzanite_live_xxxxxxxxxxxx" ``` Newest first, paged with `after` (the `sessionId` of the last row you saw). Each row carries `status`, the original `goal` as `message`, timestamps, and `cost` in USD (billed, the whole figure: the same number as the session’s `cost.totalCost`) — enough to render an activity list in your own app without opening every session. This history is keyed on the host app, so it survives a user disconnecting and reconnecting. See [the two records](/developers/overview/#the-two-records). ## Errors when creating a session [Section titled “Errors when creating a session”](#errors-when-creating-a-session) | Status | Body | Meaning | | ------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `400` | `{ "error": "project_required" }` | No `projectId`. Create one first. | | `403` | `{ "error": "insufficient_scope", "scope": "agent.sessions" }` | The connection never held the scope. | | `403` | `{ "error": "reconsent_required", … }` | Consented at an older definition version. Send the user through [Connect](/developers/connect/). | | `402` | `{ "error": "insufficient_credits" }` | The user’s balance is empty. | | `402` | `{ "error": "host_app_spend_cap" }` | This connection’s daily cap is spent. | | `429` | `{ "error": "too_many_sessions", "limit": 3 }` | In-flight session ceiling full. Retryable when one finishes. | # SDK > The typed TypeScript client for /v1 — backend and browser clients, the resource groups, driving a session, streaming events, and the two structured refusal accessors. `@tanzanite/sdk` is the typed TypeScript client for everything on [the API reference](/developers/api-reference/). Since there is deliberately no OpenAPI document, this package **is** the machine-readable half of the contract: the types are generated from the same definitions the server validates against. It uses native `fetch` and WebCrypto, so it runs unchanged on Node 18+ and in browsers with no polyfills. ```bash npm install @tanzanite/sdk ``` ## Three entry points [Section titled “Three entry points”](#three-entry-points) | Import | Contains | Use it in | | ------------------------ | ---------------------------------------------------------------- | ---------------------------- | | `@tanzanite/sdk` | The client, sessions, resources, errors, types | Your backend | | `@tanzanite/sdk/connect` | The Connect contract: PKCE, URL building, request/response types | Your backend’s OAuth handler | | `@tanzanite/sdk/react` | Prebuilt chat UI and hooks | Your frontend | `@tanzanite/sdk/connect` is a separate entry point on purpose: it pulls in no React and no WebSocket client, just the contract. It is the import a host backend’s OAuth handler should reach for. See [Connect](/developers/connect/). ## Two client modes [Section titled “Two client modes”](#two-client-modes) ### API-key mode (backends) [Section titled “API-key mode (backends)”](#api-key-mode-backends) ```ts import { Tanzanite } from "@tanzanite/sdk"; const crew = new Tanzanite({ apiKey: "tanzanite_live_xxxxxxxxxxxx", baseUrl: "https://api.tanzanite.ai", // default timeout: 30_000, // default }); ``` The tenant key belongs on a server. Never construct this client in a browser, a mobile binary, or anything else a user can read. ### Ticket-only mode (browsers) [Section titled “Ticket-only mode (browsers)”](#ticket-only-mode-browsers) ```ts const crew = new Tanzanite({ baseUrl: "https://api.tanzanite.ai", sessionId, // your backend created the session streamTicket, // from POST /v1/sessions/:id/embed-ticket }); const session = await crew.attachSession(); ``` A ticket-only client holds no tenant key. It can attach to the one session it was constructed with, stream it, signal it and answer its human-input requests — nothing else. The resource groups are getters that **throw at the call site** in this mode: ```ts crew.projects; // throws TanzaniteError, code "TICKET_ONLY" ``` That is a deliberate choice over letting the request go out and reporting the server’s `401`. Every resource group is connection-scoped, so a widget calling one is always a programming error, and the error names the client you built rather than the status code you got back. Splitting the work this way is the point of tickets: your backend creates the project, creates the session and mints the ticket; the browser gets a credential that can only watch and talk to that one session. ## Resource groups [Section titled “Resource groups”](#resource-groups) ### `crew.projects` [Section titled “crew.projects”](#crewprojects) ```ts const { project, created } = await crew.projects.create({ externalId: "level_42", label: "Level 42 — Crypt", url: "https://studio.acme.example/levels/42", }); const { projects } = await crew.projects.list({ limit: 50 }); const one = await crew.projects.get(project.id); // throws NotFoundError if deleted const { sessions, hasMore } = await crew.projects.listSessions(project.id, { limit: 20 }); // A repeat `create` returns the first project unchanged — a rename is a PATCH. await crew.projects.update(project.id, { label: "Level 42 — Catacombs" }); await crew.projects.update(project.id, { url: null }); // clear the deep link ``` `create` is idempotent per connected user and `externalId`, so calling it every time the user opens an entity is the intended shape. It never updates: when the user renames the entity on your side, `update` is how the new label or deep link reaches Tanzanite. `get` throwing `NotFoundError` is the **lifecycle signal**: the user deleted the project. Drop your mapping and let the next `create` make a fresh one. ### `crew.media` [Section titled “crew.media”](#crewmedia) ```ts const image = await crew.media.generate( { mediaType: "image", prompt: "…", size: "1024x1024", projectId }, { idempotencyKey: "acme-job-7f3c1e" }, ); const verdict = await crew.media.describe( { images: [{ url: image.url }], question: "Does the archway read as passable?", measuredContext: `${image.width}x${image.height} PNG generated from that prompt.`, projectId, }, ); // Text to speech (≤ 4000 characters) — same endpoint, same ceiling. const vo = await crew.media.generateSpeech( { mediaType: "speech", input: "In a world where every block falls…", voice: "am_michael", projectId }, { idempotencyKey: "acme-vo-91c2" }, ); // vo.mimeType ("audio/mpeg" | "audio/wav"), vo.durationMs, vo.costUSD ``` `generate` and `generateSpeech` have a 90-second server-side ceiling and the client default timeout is 30 seconds — **construct a client with a higher timeout for this call**, or it will abort a healthy generation. See [Media](/developers/media/#set-your-client-timeout-above-90-seconds). 3D models are a job, not a held request, so the 30-second default is fine for them: ```ts const model = await crew.media.generateModel( { mediaType: "model", prompt: "a treasure chest", targetHeight: 0.8, projectId }, { idempotencyKey: "acme-model-91ac", onProgress: (job) => console.log(job.progress.stage) }, ); const glb = await fetch(model.lods[0].url); // signed URL: copy the bytes into your storage ``` `generateModel` starts the job and polls it until it finishes (it throws a `TanzaniteError` carrying the job’s error code if it fails; nothing is charged). `startModel` and `job` are its two halves. See [Media](/developers/media/#generate-a-3d-model). ### `crew.completions` [Section titled “crew.completions”](#crewcompletions) ```ts const result = await crew.completions.create( { messages: [{ role: "user", content: "Summarise this level in one line." }], jsonSchema: { type: "object", properties: { line: { type: "string" } }, required: ["line"] }, projectId, }, { idempotencyKey: "acme-summary-42" }, ); // result.structuredResult → { line: "…" }; result.schemaValid → true / false ``` With `jsonSchema`, the parsed output comes back as `structuredResult` and `schemaValid` says whether it satisfies the schema — the model is asked, not made, to comply, so check it before you act on the output. Output that did not parse as JSON comes back raw as `structuredRaw` (with `schemaValid: false`). ### `crew.decisions` [Section titled “crew.decisions”](#crewdecisions) ```ts const { results, costUSD } = await crew.decisions.create({ requests: [{ id: "bot:1", state: { me: { x: 3, hp: 2 }, enemies: [{ x: 7, hp: 5 }] }, questions: { move: { type: "choice", instructions: "Best move now?", criteria: { chase: "close in", flee: "get away" } }, }, }], tag: "bot-live", }); // results[0].answers.move → { type: "choice", choice: "flee", probabilities, confidence } ``` Up to 16 requests per call; a failed request is reported in its own result and the others still answer. See [`POST /v1/decisions`](/developers/api-reference/#post-v1decisions). ### `crew.estimates` [Section titled “crew.estimates”](#crewestimates) ```ts const { perCallUSD, typicalLatencyMs } = await crew.estimates.get({ kind: "decision", stateChars: 4000 }); const voiceover = await crew.estimates.get({ kind: "speech", chars: script.length, model: "hexgrad/kokoro-82m" }); ``` What one call would cost the user, billed. Needs no scope and spends nothing. ### `crew.wallet` [Section titled “crew.wallet”](#crewwallet) ```ts const { spendableUSD, availableUSD, connectionDailyRemainingUSD, autoReload } = await crew.wallet.get(); if (spendableUSD < worstCaseUSD) showAddCredits(); ``` What this connection can spend right now: the wallet (`availableUSD`), the daily cap the user set on this connection, the account’s own daily and monthly caps, and card auto-reload. `spendableUSD` is the least of those that apply (with auto-reload on, the wallet also counts its reload amount). Needs any spend scope; free. Check it before starting something billed — a call is still refused if the money is gone by then. ### `crew.connection` [Section titled “crew.connection”](#crewconnection) ```ts const info = await crew.connection.get(); if (!info.scopes.includes("media.generate")) hideImageFeatures(); await crew.connection.revoke(); // immediate and final ``` Call `get` at start-up. Confirming a stored key still authenticates and still holds the scopes a feature needs is much better than discovering both from a `403` in front of a user. ## Sessions [Section titled “Sessions”](#sessions) ```ts const session = await crew.createSession({ projectId: project.id, goal: "Add three ambush encounters to the crypt level.", context: { sceneId: "scene_main" }, guardrails: { maxSubagents: 2 }, }); ``` `projectId` is required, and the SDK checks it before the request goes out — the server’s `project_required` answer arrives after a round trip and names a field the caller can no longer see. Reattach later with `crew.getSession(id)`, or read status without opening a stream using `crew.getSessionInfo(id)`. ### Control [Section titled “Control”](#control) ```ts await session.pause("user switched scenes"); await session.resume({ newBudget: 2.5 }); await session.redirect("Two encounters, not three."); await session.cancel(); const { mode } = await session.compact(); // "latched" (running: after this step) or "started" (idle) await session.signal({ type: "pause" }); // the general form const info = await session.getInfo(); // info.context: the context meter, null until measured const { messages, hasMore } = await session.getMessages({ limit: 50 }); await session.respondToHumanInput(inputId, { approved: true }); const child = await session.getSubagentMessages(subagentId, { limit: 20 }); // from subagent_spawned ``` `compact()` summarises the agent’s history so its next call starts with a smaller context — the same thing the agent does on its own at `compactAtTokens`. A refusal throws a `TanzaniteError` with status `409` and a `code`: `compaction_running`, `nothing_to_compact` (no call measured yet), `compaction_disabled` or `not_compactable` (e.g. a paused session). The stock `` shows the meter and a **Compact** button in its status bar. ## Streaming [Section titled “Streaming”](#streaming) Two equivalent styles. The async iterator is the simplest: ```ts for await (const event of session.stream()) { if (event.type === "message") console.log(event.role, event.content); if (event.type === "complete") console.log("done:", event.report); } ``` Or listeners, when you need more than one consumer: ```ts const off = session.on("tool_call", (e) => console.log(e.toolName, e.arguments)); session.on("human_input_needed", async (e) => { await session.respondToHumanInput(e.inputId, { approved: true }); }); session.onAny((e) => log(e)); session.startStreaming(); // …later off(); session.stopStreaming(); ``` `stream()` connects on first iteration and disconnects when the loop exits, so a `break` or a thrown error cleans up after itself. ### Events [Section titled “Events”](#events) Every frame `/v1/stream` sends: | Event | Carries | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `init` | `resync` — true when this replaces a previous stream generation. | | `status_change` | `previousStatus`, `newStatus`, `timestamp`. | | `message` | `role`, `content`, `timestamp`, and `reasoning` when the model thought before an assistant message. | | `live` | `roundId`, `content`, `reasoning`, `toolCalls` — what the agent is typing and calling right now. Whole buffers, each frame replacing the last; empty means nothing is streaming. | | `model` | `model` — the model the session runs on, when resolved and whenever it changes. | | `tool_call` | `toolName`, `arguments`, `callId`. | | `tool_result` | `toolName`, `callId`, `success`, `output`, `error`. | | `human_input_needed` | `inputId`, `question`, `category`, `choices`, `allowFreeText`; for tool approvals `toolName`, `toolArguments`, `riskLevel`; optionally `multiSelect`, `questions`, `changePreview`. | | `human_input_resolved` | `inputId` — the input was answered or withdrawn (here, in the Tanzanite app, or by expiry). Stop showing it. | | `todos` | `todos` — the agent’s whole to-do list, whenever it changes. | | `cost_update` | `totalCost` (billed, the whole session: own + subagents + attributed `/v1` spend), `totalTokens`, `promptTokens`, `completionTokens`. | | `context` | `usedTokens`, `contextWindow`, `compactAtTokens` (null when compaction is off), `estimated` (right after a compaction — show a `~`), `compacting`. How full the model’s context window is; sent on connect and whenever it changes. | | `subagent_spawned` | `subagentId`, `scope`. | | `subagent_update` | `subagentId`, `status`, and `activity` — its latest reply or tool. | | `subagent_complete` | `subagentId`, `status`, `report`. | | `complete` | `report` (the completion report), `cost`. Terminal. | | `cancelled` | `timestamp`. Terminal — the session was cancelled; not an error. | | `error` | `message`, `code`. Terminal. `code: "ENQUEUE_ERROR"` means the session could not be started. | The client adds one of its own: | Event | Carries | | --------- | ----------------------------------------------------- | | `warning` | `message`, `code`. A recoverable transport condition. | The SDK’s `SessionEvent` type also declares `token`, which `/v1/stream` does not send today — keep a default branch rather than waiting on it. Two things to handle correctly: **`warning` is not a failure.** A network blip surfaces as a `warning` while the client reconnects underneath. Only a terminal `error` ends the stream — including `WS_GIVE_UP`, emitted once the reconnect budget is genuinely exhausted. Do not tear down your UI on a warning. **`init` with `resync: true` means drop what you buffered.** It marks a reconnect that replaces a previous stream generation; without handling it, the first snapshot after a gap duplicates every message you already rendered. ## Errors [Section titled “Errors”](#errors) Everything the client throws extends `TanzaniteError`, which carries `status`, an optional `code`, and the response body in `details`. `AuthenticationError` (401), `NotFoundError` (404), `RateLimitError` (429, with `retryAfter`) and `SessionError` are the named subclasses. Two accessors turn a refusal into something you can branch on. They are separate because **their remedies are different in kind**: one is answered with money, the other with a capability change. Code that renders “add credits” for a capability refusal is showing the user the wrong button. ### `err.billing` — refusals answered with money [Section titled “err.billing — refusals answered with money”](#errbilling--refusals-answered-with-money) ```ts try { await crew.media.generate({ mediaType: "image", prompt }); } catch (err) { const b = err instanceof TanzaniteError ? err.billing : null; if (b?.reason === "insufficient_credits") return showAddCredits(b); if (b?.reason === "host_app_spend_cap") return showSpendCapReached(b); if (b?.retryable) return scheduleRetry(b.retryAfterSeconds); throw err; } ``` | `reason` | Meaning | | ---------------------- | ------------------------------------------------------------------ | | `insufficient_credits` | The user has no funds. Determinate. | | `host_app_spend_cap` | The daily cap on **this connection** is spent. The wallet is fine. | | `billing_unavailable` | The balance could not be read at all. Retryable. | | `rate_limited` | Too many requests. Retryable after a wait. | `availableUSD` may be `null`, meaning the balance is **unknown**. Do not render `null` as `$0.00` — unknown is not empty. ### `err.refusal` — refusals answered with a capability change [Section titled “err.refusal — refusals answered with a capability change”](#errrefusal--refusals-answered-with-a-capability-change) ```ts const r = err instanceof TanzaniteError ? err.refusal : null; if (r?.reason === "media_timeout") return retryWithSameIdempotencyKey(); if (r?.reason === "reconsent_required") return sendUserThroughConnect(); if (r?.reason === "too_many_sessions") return queueUntilASlotFrees(r.limit); ``` | `reason` | Extra fields | Remedy | | ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ | | `insufficient_scope` | `scope` | The user must reconnect granting that scope. | | `reconsent_required` | `hostAppVersion`, `requiredVersion` | Send the user through [Connect](/developers/connect/). | | `too_many_sessions` | `limit` | Retryable once a session finishes. | | `media_timeout` | `ceilingMs` | **Nothing charged.** Retry with the same `Idempotency-Key`. | | `idempotency_key_reused` | — | A collision, not a replay. Pick a fresh key. | | `idempotency_in_progress` | — | The first request under this key is still running. **Nothing charged.** Retry with the same key. | Both accessors return `null` for anything they do not recognise, rather than mislabelling it. A 403 that is not one of the two above means something else and carries different affordances — let it propagate. ## Connect helpers [Section titled “Connect helpers”](#connect-helpers) ```ts import { createPkcePair, createConnectState, buildConnectAuthorizeUrl, parseConnectCallback, buildConnectTokenRequest, parseConnectGrant, CONNECT_SCOPES, CONNECT_SPEND_SCOPES, CONNECT_DEFAULT_SCOPES, formatConnectScopes, parseConnectScopes, } from "@tanzanite/sdk/connect"; ``` These are pure — no `fetch`, no error taxonomy. The one HTTP call in the flow is yours to make, because your backend already has a client with its own retry and error mapping and adopting the SDK’s would be a worse trade. `parseConnectGrant` is worth using rather than casting the response: a cast lets a proxy error page or a truncated body become a “connection” whose stored key is `undefined`, and that failure surfaces much later as an unexplained `401`. Full walkthrough on the [Connect](/developers/connect/) page. ## React components [Section titled “React components”](#react-components) ```tsx import { TanzaniteProvider, TanzaniteAgent } from "@tanzanite/sdk/react"; ``` `TanzaniteAgent` is a complete chat surface — transcript, input, tool-call cards, a human-input dialog, a status bar (status, cost, model, the context meter and a **Compact** button) and a sub-agent panel. The sub-components are exported individually for custom layouts, alongside the `useSession`, `useSessionEvents`, `useTanzanite`, `useTheme` and `useVoiceInput` hooks and light and dark themes. React is an optional peer dependency; the main entry point does not pull it in. ## A complete backend flow [Section titled “A complete backend flow”](#a-complete-backend-flow) ```ts import { Tanzanite, TanzaniteError } from "@tanzanite/sdk"; const crew = new Tanzanite({ apiKey: await keyFor(userId), timeout: 120_000 }); const { project } = await crew.projects.create({ externalId: level.id, label: level.name, url: `https://studio.acme.example/levels/${level.id}`, }); try { const session = await crew.createSession({ projectId: project.id, goal: "Add three ambush encounters, balanced for level 8 players.", context: { sceneId: level.sceneId }, }); for await (const event of session.stream()) { if (event.type === "human_input_needed") await askTheUser(event); if (event.type === "complete") await recordReport(level.id, event.report); } } catch (err) { if (err instanceof TanzaniteError) { if (err.refusal?.reason === "reconsent_required") return sendUserThroughConnect(); if (err.billing?.reason === "insufficient_credits") return showAddCredits(); } throw err; } ``` # Tool definitions > The schema of a tool in your host-app catalog — category, danger level, parameters, endpoint, response mapping and render hint — and the toolsUrl refresh contract. Your host-app definition carries a **tool catalog**: the operations inside your product that an agent may perform. Each tool is a declarative record. Tanzanite turns it into a function the model can call, invokes your HTTP endpoint when the model calls it, and maps the response back into something the agent can read. You write no code for this. A tool is data, which is what makes it reviewable — a reviewer can see exactly what an app can do before any user is asked to consent to it. ## One tool, in full [Section titled “One tool, in full”](#one-tool-in-full) ```json { "name": "place_object", "description": "Place an object in the current scene at the given coordinates.", "category": "write", "dangerLevel": "moderate", "requiresApproval": false, "resultRenderer": "image", "parameters": { "type": "object", "properties": { "sceneId": { "type": "string", "description": "Scene to place into." }, "assetId": { "type": "string", "description": "Asset to place." }, "x": { "type": "number" }, "y": { "type": "number" }, "rotation": { "type": "number", "description": "Degrees, 0–360." } }, "required": ["sceneId", "assetId", "x", "y"] }, "endpoint": { "method": "POST", "path": "/scenes/{{args.sceneId}}/objects", "headers": { "X-Acme-Client": "tanzanite" }, "queryParams": { "dryRun": "{{args.dryRun}}" }, "bodyTemplate": { "asset": "{{args.assetId}}", "position": { "x": "{{args.x}}", "y": "{{args.y}}" }, "rotation": "{{args.rotation}}" } }, "responseMapping": { "objectId": "id", "previewUrl": "preview.url" } } ``` ## Fields [Section titled “Fields”](#fields) ### `name` [Section titled “name”](#name) The tool’s identifier. The agent sees it as `integration_` — so `place_object` above is offered to the model as `integration_place_object`. The prefix is not decoration: it is what keeps a host app’s tool from colliding with, or being mistaken for, a platform tool. Names are also how you refer to the tool in `context` pins, approvals and logs. Pick stable ones; renaming a tool is, to every agent that learned it, a deletion plus a creation. ### `description` [Section titled “description”](#description) What the model reads to decide whether to call this tool. It is prefixed with `[]` when presented, so the agent always knows whose tool it is. This field does more work than any other. Write what the tool does, when to use it, when *not* to use it, and what the arguments mean in your domain. A tool with a vague description is called at the wrong moments, and no amount of prompt context elsewhere fixes it. ### `category` [Section titled “category”](#category) `read` | `write` | `action` * `read` — fetches information and changes nothing. * `write` — creates or modifies data in your product. * `action` — triggers something with an effect beyond stored data: a build, a send, a deploy. The category is part of what your app is approved for, and it is re-checked on every catalog refresh. See [the ceiling](#the-approved-ceiling). ### `dangerLevel` [Section titled “dangerLevel”](#dangerlevel) `safe` | `moderate` | `destructive` Independent of `category`, because they answer different questions. `category` says what kind of operation it is; `dangerLevel` says how bad it is if the agent is wrong. A `write` that appends a comment is `safe`; a `write` that overwrites a scene is `destructive`. Be honest here. Understating danger to avoid an approval prompt is the change most likely to be caught in review, and the one most likely to burn a user’s trust in your integration if it is not. ### `requiresApproval` [Section titled “requiresApproval”](#requiresapproval) When `true`, the agent must get a human approval before the call executes. The session moves to `waiting_human` and emits a `human_input_needed` event carrying the tool name and the arguments it intends to use, which you answer with [`POST /v1/sessions/:id/human-input/:inputId`](/developers/projects-and-sessions/#human-input). Set it on anything destructive, anything that spends the user’s money outside Tanzanite, and anything a user would be startled to discover after the fact. ### `resultRenderer` [Section titled “resultRenderer”](#resultrenderer) `image` | `diff` | `link` | `table` | `json` A hint for how the first-party transcript should present this tool’s result. Pick the one that matches your `responseMapping` output: `image` for a URL to a picture, `diff` for a before/after, `link` for a deep link back into your app, `table` for rows, `json` for anything else. This is a **fixed enum, and it is the entire vocabulary**. A host app may never hand the platform markup — not HTML, not a template, not a component. A render hint cannot become a script injected into another user’s transcript; a markup field always eventually can. ### `parameters` [Section titled “parameters”](#parameters) A JSON Schema object describing the tool’s arguments. `type` must be `"object"`, with `properties` and a `required` array. Per-property you can use `type`, `description`, `enum`, `items`, nested `properties` and nested `required`. Constrain aggressively. An `enum` of the four asset kinds you actually support is worth more than a `string` and a sentence asking the model nicely. Describe every property — the description is read at call time, and an undescribed parameter is a guessed parameter. ### `endpoint` [Section titled “endpoint”](#endpoint) Where the call goes. `path` is appended to your definition’s `baseUrl`. | Field | Purpose | | -------------- | ----------------------------------------------------------- | | `method` | `GET`, `POST`, `PUT`, `DELETE` or `PATCH`. | | `path` | Appended to `baseUrl`. May interpolate arguments. | | `headers` | Extra headers for this tool. Auth is added by the platform. | | `queryParams` | Query string, values may interpolate arguments. | | `bodyTemplate` | Request body for `POST`, `PUT` and `PATCH`. | Argument interpolation uses `{{args.}}` in `path`, `queryParams` and `bodyTemplate`. Anything pinned by the session’s `context` is merged into `args` and **wins over what the model supplied**, which is how you keep an id the model must not choose out of the model’s hands — see [`context` is a pin](/developers/projects-and-sessions/#context-is-a-pin-not-a-hint). Authentication is added by the platform, in the shape your definition declares, carrying the per-user `credential` from [Connect](/developers/connect/#credential--the-field-that-is-easy-to-get-wrong). Do not put credentials in `headers`. ### `responseMapping` [Section titled “responseMapping”](#responsemapping) Maps fields out of your HTTP response into the result the agent sees. Keys are the names the agent gets; values are dotted paths into your response body. ```json { "objectId": "id", "previewUrl": "preview.url", "warnings": "meta.warnings" } ``` Map only what the agent needs. Returning your whole response object costs tokens on every call and buries the two fields that matter — and a field you did not mean to expose to a model is a field you have exposed to a model. ### `polling` (optional) [Section titled “polling (optional)”](#polling-optional) For an endpoint that returns a job rather than a result. When present, Tanzanite calls the tool, then polls until the job reports done. | Field | Purpose | | ---------------- | --------------------------------------------------------------- | | `statusUrl` | Where to poll. | | `statusField` | Dotted path to the status value in the poll response. | | `completeValue` | The value of `statusField` that means success. | | `failedValue` | The value that means failure. | | `resultMapping` | Like `responseMapping`, but applied to the final poll response. | | `pollIntervalMs` | Delay between polls. | | `maxPolls` | Give up after this many. | Pick `pollIntervalMs` and `maxPolls` so their product comfortably exceeds your job’s realistic worst case. A tool that gives up while the job is still running reports a failure for work that then completes, and the agent acts on the wrong belief. ## The `toolsUrl` catalog contract [Section titled “The toolsUrl catalog contract”](#the-toolsurl-catalog-contract) A definition can carry a static catalog, a `toolsUrl`, or both. When `toolsUrl` is set, **the platform re-fetches your catalog at the start of every session**, so you can ship a new tool without touching your definition. Three rules govern it: **It must be on the same origin as `baseUrl`.** A catalog endpoint elsewhere would let the record that says *what your app can do* live somewhere other than the app itself. **A refreshed catalog is filtered against the ceiling you were approved for.** See below — this is the important one. **A stale snapshot is used when the catalog is unreachable.** Your endpoint being down degrades your integration to the last known-good catalog rather than breaking every session. This is a safety net, not a strategy: a catalog that stays unreachable stays frozen at whatever it was. ### The approved ceiling [Section titled “The approved ceiling”](#the-approved-ceiling) Your definition is approved for a maximum `category` and a maximum `dangerLevel`. When a refreshed catalog arrives, every tool in it is checked against that ceiling, and **a tool that exceeds it is dropped, not accepted**. This is why a catalog refresh cannot be used to widen reach. An app reviewed and approved for `read` tools cannot become an app with `destructive` `action` tools by editing the JSON its own server returns — the new tools simply do not appear. Raising the ceiling is a change to the definition, which bumps its `version` and sends existing users through [re-consent](/developers/connect/#re-consent-when-a-definition-widens). Plan for it: if a dropped tool is missing from your sessions, the ceiling is the first thing to check, and the fix is a definition change rather than a catalog change. ## Prompt context [Section titled “Prompt context”](#prompt-context) Your definition also carries a block of prompt context describing your product to the agent: what it is, what the tools operate on, the conventions the agent should follow. It is capped in length and is presented to the model as clearly-marked third-party content, so instructions in it cannot override the platform’s own rules or the user’s. Write it as domain briefing, not as commands. “Scenes are addressed by id; assets are immutable once placed” is useful. “Always call `place_object` first” is not, and will not be obeyed the way you expect. ## A checklist before you publish [Section titled “A checklist before you publish”](#a-checklist-before-you-publish) * Every tool has a description that says when *not* to use it. * Every parameter has a description, and every closed set is an `enum`. * `dangerLevel` is honest, and `requiresApproval` is set on everything destructive. * `responseMapping` returns the few fields the agent needs and nothing else. * `polling` budgets exceed your realistic worst case. * Your `toolsUrl` is on the same origin as `baseUrl` and answers quickly. * Nothing in the catalog exceeds the ceiling you are asking to be approved for. # Account, billing & limits > Manage your credit balance, understand what an agent run costs, and use budgets and guardrails to keep spending predictable. Everything about paying for Tanzanite in one place: your credit balance, what a run actually costs, and the controls that keep spending in check. For how pricing works overall, see [Pricing & credits](/using/pricing/); this page focuses on managing your account and understanding usage. ## Where to manage your account [Section titled “Where to manage your account”](#where-to-manage-your-account) Open **Account → Billing** to see your credit balance, buy credits, and review an itemized history of every purchase and charge. Your account — balance and projects — follows you across every device you sign in on. ## Billing in brief [Section titled “Billing in brief”](#billing-in-brief) Tanzanite is **credits-only**. Every feature is available to every account; one prepaid credit balance funds all paid work — cloud models, sandboxes, media generation, storage, and cloud-project rent. **Local projects** on the desktop app cost nothing: the on-device model runs entirely on your machine. Staff accounts skip the funds gate so internal work isn’t blocked by a $0 wallet; that is not a product tier. ## What a run costs [Section titled “What a run costs”](#what-a-run-costs) Pricing is by **usage**, measured in the tokens a run consumes, and priced in USD. There’s no flat per-run fee — a short chat costs little, a long autonomous plan with subagents costs more. Every plan tracks **token usage and cost live as it runs**. Open the plan tree during a run to see cost accumulate step by step, so there are no surprises after the fact. Local projects on the on-device model have **zero marginal cost** — nothing is billed for them. ### How usage draws down [Section titled “How usage draws down”](#how-usage-draws-down) Usage draws directly from your **prepaid credits**. The balance you see is **available = credits − reserved − spent** and can go **negative** (a settle that overshot, a refund, or a bonus clawback) — the number is real, never clamped. Before paid work starts, Tanzanite places a hold for the estimated cost and settles the exact amount when the work finishes — the held amount shows on your Billing tab so the balance you see is the balance you can spend. When credits run out, the run **stops** with **“You’re out of credits. Add credits to continue.”** — it does not park waiting for money. Top up, then start the run again. (A run stopped by a **spend limit** you set yourself is different: that one pauses and picks up where it left off. See [Spend limits](#spend-limits-pause-running-out-of-credits-stops).) Credits are prepaid, never expire while your account is active, and you can top up any time from **Account → Billing** (minimum **$5**). Checkout enforces a **monthly add cap** (how much you can add in one UTC calendar month; default $500). There is no separate per-purchase ceiling or balance ceiling — a single checkout can be as large as the remaining monthly cap. Optional **auto-reload** adds a fixed amount from your saved card whenever your balance drops below a threshold; each reload is capped (default $100). It’s a plain toggle on the Billing tab, and turning it off is always one click. You can also set an optional **monthly spend cap** there; hitting it stops work and points you at Billing, it does not use the out-of-credits sentence. ### Spend limits pause; running out of credits stops [Section titled “Spend limits pause; running out of credits stops”](#spend-limits-pause-running-out-of-credits-stops) Two different things can halt a run for money reasons, and they end differently: * **A spend limit you set** — a **per-run** or **per-project** ceiling (“spend at most $20 on this”) — **pauses** the run when it’s reached: *“This plan hit its $20 spend limit. Raise or remove the limit to continue.”* The work is parked, not thrown away. Raise or remove the limit and **resume** — the agent picks up exactly where it stopped, keeping everything it had done. * **Running out of credits**, hitting your **monthly spend cap**, or a **suspended cloud project** — **stops** the run. There is nothing to resume: add credits (or raise the cap, or pay the project’s rent), then start a fresh run. Everything already committed to your project is still there. The short version: a ceiling **you** chose is a pause you control; an empty wallet is a stop. ### Cloud-project rent [Section titled “Cloud-project rent”](#cloud-project-rent) A cloud project is standing infrastructure (hosted git, storage, a sandbox that can be woken), so it carries a flat monthly price on top of usage — charged as a **daily slice** so a calendar month costs the advertised price. The auto-created **General workspace** and **local projects** are free. If a day’s charge leaves you at or below zero, cloud projects **pause** (files and history stay); adding credits clears the pause within seconds. ## Budgets & guardrails [Section titled “Budgets & guardrails”](#budgets--guardrails) Tanzanite is built so you’re never surprised by a bill or an action: * **Approvals.** Sensitive tool calls — writing files, running commands — pause for your explicit approval before they execute. * **Budgets.** Give a run a **spend limit** and it pauses at that ceiling instead of quietly overrunning — **resume it with a new budget** and it continues from where it stopped. An empty wallet stops the run outright; nothing is ever billed in the background to keep it going. * **Guardrails.** The [harness](/using/harness/) defines what requires approval and what is blocked outright. Administrators can tighten these in the harness editor. * **Cost visibility.** Live cost tracking on every plan means you can stop, redirect, or cancel the moment a run heads somewhere you didn’t intend. ## Resource limits [Section titled “Resource limits”](#resource-limits) Independent of money, each account has resource quotas — concurrent sandboxes, cloud projects, and hosted-repo storage — that keep any one account from monopolizing shared infrastructure. They’re generous defaults, not paywalls; if you hit one, the error names the exact limit. ## Next steps [Section titled “Next steps”](#next-steps) * See how pricing works in [Pricing & credits](/using/pricing/). * See how runs consume usage in [Chat, plans & goals](/using/agents-and-chat/). * Billing question or a charge you don’t recognize? See [Troubleshooting & FAQ](/using/troubleshooting/#billing--account). # Chat, plans & goals > Everything you ask an agent starts in Chat — each conversation is a plan, with goals it must meet, tasks, subagents, approvals, and a spend limit. You work with an agent in **Chat**, in the sidebar. There is no separate place for “autonomous” agents: a quick question and a long-running task start the same way, and the agent does as much work as the request needs. ## Chat [Section titled “Chat”](#chat) Type into the composer — *Ask anything or give the agent a task…* — and send. Opening **Chat** from the sidebar clears the active project for general, project-free conversation; pick a project in the sidebar to work inside it with that project’s files and tools. The composer also sets how this message runs: * The autonomy tier — how much the agent may do without asking: **Observe** (read-only), **Draft** (holds its outputs for your approval), **Execute** (runs within guardrails and asks only before destructive actions) or **Full Auto** (no approval gates; cost guardrails still apply). * The model, thinking and web search for this message. ## Plans [Section titled “Plans”](#plans) Each conversation is a **plan**. The agent works through it in rounds: it reasons, calls tools, produces results, and reports back — and a follow-up message continues the same plan. Your conversations are listed in the chat history panel. ### Goals [Section titled “Goals”](#goals) A plan can carry **goals** — the things that must be true for the work to count as done. They appear in the **Goals** panel at the top of the plan with a `done/total` count, and you can add one yourself with **Add goal**. This plan will not finish while a goal is open: the agent has to meet each one, or say honestly that it is blocked. Goals are not the same as the agent’s **tasks** (**Show tasks**), which are its own working checklist and never hold a plan open. ### Subagents [Section titled “Subagents”](#subagents) For larger work the agent can spawn **subagents** that run in parallel, each scoped to part of the problem, then report back. The plan tree shows them live; the agent tree explorer shows each one’s status and lets you pause or cancel a node that went off track. ### Approvals and control [Section titled “Approvals and control”](#approvals-and-control) You stay in control of a running plan: * Approve sensitive tool calls before they execute — **Allow Once**, **Allow Always** for that kind of action, or **Deny**. How often you are asked depends on the autonomy you chose. * Answer the questions the agent asks in a prompt above the composer. * **Pause** and **Resume** at any time. * **Redirect** by typing while the plan runs — the composer reads *Redirect the agent…*. * **Stop Agent** when you’re done. A stopped plan can be picked up again by sending a message. ### Spend [Section titled “Spend”](#spend) Every plan tracks its token usage and cost as it runs. The `$` chip in the plan header sets a **Plan spend** limit — a **Hard limit** or a **Target** — for that plan. ## Rich output [Section titled “Rich output”](#rich-output) Agents can produce and render markdown, code, images, video, HTML, and PDFs inline through the renderer registry, and can generate media with built-in tools. ## Next steps [Section titled “Next steps”](#next-steps) * Make runs recurring with [Schedules & Triggers](/using/schedules/). * Learn what governs agent behavior in [the Harness](/using/harness/). # Changelog > Notable changes to the Tanzanite desktop app. New releases appear here first. Notable changes to the Tanzanite desktop app. New releases appear here first; the in-app About tab and the update prompt both surface entries from this file. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/). ## \[Unreleased] [Section titled “\[Unreleased\]”](#unreleased) ### Added [Section titled “Added”](#added) * The WebSocket bridge now checks the client version: a desktop below the server’s `MIN_DESKTOP_VERSION` is refused registration (the bridge twin of the `426 client_upgrade_required` HTTP gate) and gets the same blocking Update-required screen. * Settings → About tab: the app’s version, a check-for-updates button against the signed update feed, install-and-restart through the Rust `install_update` command, and release notes from this changelog. * Periodic update checks (every 6 hours) beyond the launch-time one, offering an install through the same confirm dialog. ## \[0.1.0] — 2026-09-23 [Section titled “\[0.1.0\] — 2026-09-23”](#010--2026-09-23) ### Added [Section titled “Added”](#added-1) * Signed auto-updater: the WebView may only ask whether an update exists (`updater:allow-check`); installing is the Rust `install_update` command, which verifies the minisign signature against the build’s public key before installing and restarting. * Minimum desktop version on the server: `MIN_DESKTOP_VERSION` is served at `GET /api/client-config`; a desktop below it receives `426 client_upgrade_required` on every `/api/*` call and the blocking Update-required screen, which updates through the same signed channel. * `build:desktop` release script that refuses to build without the updater public key, feed URLs and signing key. # How cloud agents run > The three project setups, where a Cloud project's agent runs, the device vs. cloud-sandbox backend, the local-file mirror, and the fully on-device privacy path. ## The three setups [Section titled “The three setups”](#the-three-setups) Every project answers four questions the same way for everyone who opens it: **where the AI model runs**, **where your plans and chats are saved**, **where your files live**, and **what it needs in order to run**. Three combinations are offered when you create one: **Cloud — “Files are hosted by Tanzanite; the AI runs in the cloud.”** * AI model: a cloud model, or your own local model through the desktop app. * Plans/chats: saved to your account; visible on web and desktop. * Files: a hosted git repo; optionally mirrored to a folder on this machine. * Runs: from anywhere, whether or not the desktop app is open. **Device — “Files stay on this machine; the AI runs in the cloud.”** * AI model: a cloud model, or your own local model through the desktop app. * Plans/chats: saved to your account; visible on web and desktop. * Files: only in a folder on this machine — no hosted copy. * Runs: only while this desktop app is open. Can be promoted to Cloud later (that adds a hosted repo; nothing else changes). **Local — “Everything stays on this machine.”** * AI model: a model running on this machine only. * Plans/chats: stored only on this machine; never sent to the cloud. * Files: only in a folder on this machine. * Runs: desktop app only. Cannot be converted to another setup. Two rules are worth knowing up front. **Choosing a local model never moves your plans**: on a Cloud or Device project you can point the agent at a model running on your own machine and your chats are still saved to your account. And a **Device project can be promoted to Cloud** at any time, while a **Local project cannot be converted** — its plans only ever existed on your machine. The rest of this page is about how a Cloud or Device project runs. ## Where a cloud-run agent works [Section titled “Where a cloud-run agent works”](#where-a-cloud-run-agent-works) Tanzanite is **cloud-first**. For a **Cloud project**, the agent’s reasoning loop always runs on Tanzanite’s servers — but the *tools* it runs (reading files, searching, running commands, committing) execute either **on your own machine** when the desktop app is open, or in a **secure cloud sandbox** when it isn’t. Within those options Tanzanite picks the best one automatically and can switch mid-task without losing work — but running on your machine is something you opt into: it only happens when you’ve linked a local folder and left **“Run agents on this device”** on (see [The local mirror](#the-local-mirror-sync) below). A Cloud project with no linked folder runs entirely in the cloud. A **Device** project is the other extreme: there is no hosted copy of its files, so its tools only ever run on your machine and a run needs the desktop app open. ## Two kinds of work [Section titled “Two kinds of work”](#two-kinds-of-work) * **Agent work (Type-A)** — planning, editing files, running sub-agents. This always runs in the cloud control plane. Your prompts and the orchestration logic never ship to your browser or into a sandbox. * **Running your code (Type-B)** — actually executing the app or script the agent produced. This can run **locally** (instant, interactive — great for GUIs, games, and tight dev loops) **or** in a **cloud sandbox** (for mobile, offline, or headless/automated runs). ## Where the tools run: device vs. cloud sandbox [Section titled “Where the tools run: device vs. cloud sandbox”](#where-the-tools-run-device-vs-cloud-sandbox) When you have the **desktop app open** and device execution is enabled, the agent runs its file and command tools directly on your local files — fastest, and nothing is cloned. When your device is **closed, offline, you triggered the run from the web/phone, or you haven’t opted into device execution**, the agent runs the very same tools in a **secure cloud sandbox** (a gVisor-isolated pod) over a checkout of your project’s git repo. Because git is the source of truth, switching between the two is seamless: at a safe boundary the agent commits work-in-progress, then points the next tool at the other backend. Close your device mid-run and the work **continues in the cloud**; reopen it and the agent switches back. The run header shows where work is currently happening. ## The local mirror (sync) [Section titled “The local mirror (sync)”](#the-local-mirror-sync) A Cloud project’s files live in a git repo that Tanzanite hosts. You can optionally **mirror that repo to a local folder** so your edits and the agent’s edits stay in lockstep across devices: * Creating a Cloud project does **not** prompt for a folder — a new project has no mirror. Link one any time (desktop only) from the project’s settings under **Local mirror → Link a local folder**. (Importing an existing folder as a new project is a separate flow that starts from the folder.) * When linking, Tanzanite proposes a starter `.gitignore` where recommended — so `node_modules`, build output, and secrets like `.env` are **never** committed — and, if the folder isn’t a git repo yet, initializes one and makes the first commit for you. Right after linking it pulls the cloud repo down into the folder. * At link time you choose **“Run agents on this device”** (on by default). On = the agent runs commands in this folder; off = the folder mirrors for sync only and the agent works entirely in the cloud. You can flip it later, and device execution is available only on a machine that has the folder linked — unlinking turns it off. * Agent commits flow down like a live `git pull`; your local edits flow up. * **Your local work is never thrown away.** If both sides changed, Tanzanite merges non-overlapping edits automatically; a genuine same-line conflict is surfaced for you to resolve, with your version preserved on a `tz/local/` branch as a safety net. `.gitignore` is always respected, so ignored files never sync, never reach the cloud, and never enter a sandbox. ## Local projects (the privacy path) [Section titled “Local projects (the privacy path)”](#local-projects-the-privacy-path) A **Local** project is different: both the model **and** the agent run entirely on your device. Nothing — not your code, not your prompts, not your chats — leaves your machine; the plans are stored on the machine too. There’s no cloud round-trip, no sandbox, and no sub-agents. It’s the free, zero-cloud path and a genuine privacy guarantee, and it requires the desktop app (an on-device model can’t run in a browser). Because its chats never existed in the cloud, a Local project **can’t be converted** to Cloud or Device later. If you might want it on the web one day, start it as a **Device** project — that keeps your files on your machine while your chats sync to your account, and it can be promoted to Cloud whenever you want a hosted repo. Note the difference between a Local *project* and simply **choosing a local model**. On a Cloud or Device project you can point the agent at a model running on your own machine through the desktop app; that saves you credits, but your plans and chats are still saved to your account. Only the Local setup keeps everything on the machine. ## What stays private and secure [Section titled “What stays private and secure”](#what-stays-private-and-secure) * Your provider keys and credentials live only in Tanzanite’s control plane — they are **never** sent to a sandbox or to your device. * A sandbox only ever holds a short-lived token scoped to the one project’s git repo, and its network access is locked to that repo and the package cache. * For Cloud and Device projects, Tanzanite is the single writer of the agent’s record of truth, so your run state is consistent no matter which device you’re on. (A Device project’s *files* never leave your machine — only its chats and plans are saved to your account.) # Get help > Where to go when something is wrong — email, the status page, and the troubleshooting guide. ## Email [Section titled “Email”](#email) Write to ****. If it concerns a specific agent run, say which project and roughly when it ran so we can find it. For **security vulnerabilities**, use **** instead — see the [Security page](/using/security/) for scope and response times. ## Is it us? [Section titled “Is it us?”](#is-it-us) Check [status.tanzanite.ai](https://status.tanzanite.ai) for current incidents and maintenance. If the status page is green and the app isn’t working for you, [Troubleshooting & FAQ](/using/troubleshooting/) covers the common cases. ## Billing [Section titled “Billing”](#billing) Charges, credits and refunds are explained in [Account, billing & limits](/using/account-billing/). For a billing question we can’t answer there, email **** — it reaches the same people. # Install & first run > Download Tanzanite, sign in, create your first project, and run your first agent — with per-platform notes for macOS, iOS, and Android. This page takes you from downloading Tanzanite to watching your first agent run. If you just want the shortest path, the [Quickstart](/using/quickstart/) is a condensed version; this page adds per-platform install detail and what to expect on first launch. Note The images on this page are illustrative placeholders — real captures from the app are on the way. The steps and on-screen labels they describe are accurate for the shipped macOS build. ## Install by platform [Section titled “Install by platform”](#install-by-platform) Tanzanite is a **native app**. macOS is the shipped platform today; iOS and Android are in progress. ### macOS [Section titled “macOS”](#macos) 1. Download the latest Tanzanite build for macOS and open the `.dmg`. 2. Drag **Tanzanite** into your **Applications** folder, then launch it. 3. On first launch macOS may ask you to confirm opening an app downloaded from the internet — approve it to continue. Tanzanite runs both as a full window and in your **menu bar** (system tray), so you can leave it running and reach an agent quickly. Leaving the app open also lets cloud projects run their tools **on your machine** rather than in a cloud sandbox — see [How cloud agents run](/using/cloud-execution/). ### iOS and Android (in progress) [Section titled “iOS and Android (in progress)”](#ios-and-android-in-progress) Mobile builds are in development. On phones and tablets, agents run entirely in the cloud — there’s no on-device execution or local folder access — so a mobile device is best for kicking off cloud runs, reviewing plans, and approving actions rather than working against local files. When mobile ships, sign-in and projects work the same way described below. ## Sign in [Section titled “Sign in”](#sign-in) Create an account or sign in with **email and password**, or with **Google**.  *The sign-in screen.* Your account carries your credit balance and projects across every device you sign in on. No credits yet? That’s fine — local projects on the desktop app are free (see [Pricing & credits](/using/pricing/)). ## Find your way around [Section titled “Find your way around”](#find-your-way-around) The left **sidebar** is the main navigation, top to bottom: * **Chat** — talk to an agent or give it a task (clearing the active project for general chat). See [Chat, plans & goals](/using/agents-and-chat/). * **Skills** — instruction packs the agent loads on demand. * **Projects** — your working contexts (Cloud, Device or Local). * **Host apps** — apps you use elsewhere that you connected to Tanzanite, and keys for your own scripts. * **Schedules** — run agents on a recurring schedule, or when a commit lands. * **LLM Calls** — the full input of each model call, for debugging. * **Account**, **Settings** — your billing and preferences. Below them the sidebar lists your projects. ## Create your first project [Section titled “Create your first project”](#create-your-first-project) Open **Projects** and click **New Project**. Choose: * **Cloud** — files hosted by Tanzanite, the AI runs in the cloud; nothing needed on your machine. Cloud runs are paid for with prepaid credits. * **Device** — files stay in a folder on this machine, the AI runs in the cloud. Tanzanite opens a native folder picker and requests file-system access to that folder. Your chats and plans still sync to your account, and you can promote it to Cloud later. * **Local** — everything stays on this machine, the model included. Free on the desktop app; it can’t be converted to another setup later.  *Projects → New Project.* See [Projects](/using/projects/) for what each of the three setups means. ## Run your first agent [Section titled “Run your first agent”](#run-your-first-agent) With a project active, open **Chat** and either ask a quick question or give the agent a **goal** to start an autonomous run. The agent breaks the goal into steps, calls tools, and can spawn subagents for parallel work.  *Entering a goal in Chat.* When the agent wants to take a sensitive action — writing files, running a command — it pauses for your **approval**. The plan tree shows each step live (reasoning, tool calls, results, and cost), and you can pause, resume with a new budget, redirect, or cancel at any time. ## Next steps [Section titled “Next steps”](#next-steps) * Do something specific with the [Task how-tos](/using/how-to/). * Hit a snag? See [Troubleshooting & FAQ](/using/troubleshooting/). * Understand costs and limits in [Account, billing & limits](/using/account-billing/). # The Harness > The harness is the configuration that governs every agent — system prompt, available tools, model routing, and safety guardrails. Every agent in Tanzanite is governed by a **harness**. The harness is the control layer that decides how an agent behaves. ## What the harness defines [Section titled “What the harness defines”](#what-the-harness-defines) * **System prompt** — the base instructions every agent starts from. * **Available tools** — which tools the agent can call, organized into tiers so the agent discovers more capabilities as a task requires them. * **Model routing** — which model handles which kind of step. * **Safety guardrails** — what requires approval and what is blocked. ## Part of the platform [Section titled “Part of the platform”](#part-of-the-platform) The harness ships with the platform: changes to it are made by the Tanzanite team and reach every agent with a platform release. ## Skills and plugins [Section titled “Skills and plugins”](#skills-and-plugins) The harness works alongside: * **Skills** — packs of instructions an agent loads for specific tasks. You keep your own library and attach skills to a **project** (every chat in it) or to a single **chat**. See [Add a skill](/using/how-to/#add-a-skill). * **Plugins** — installable bundles that extend the platform with new tools and integrations. Attached skills are cheap by design: an agent carries only each skill’s name and description until it judges one relevant, and reads the full instructions only then. That is why the description is the part worth writing carefully — it is what that judgement is made on. ## The on-device harness (Local projects) [Section titled “The on-device harness (Local projects)”](#the-on-device-harness-local-projects) For fully private use, a **Local** project runs its own harness on your machine against an on-device model, so sensitive work — files, prompts and chats alike — never leaves it. See [the three setups](/using/cloud-execution/#the-three-setups). ## Next steps [Section titled “Next steps”](#next-steps) * Learn what governs a run in [Chat, plans & goals](/using/agents-and-chat/). # Task how-tos > Step-by-step guides for common jobs in Tanzanite — import a local folder, schedule a run, add and attach a skill, and configure the harness. Short, task-focused recipes for the things people do most. Each one assumes you’re signed in with a project open. For concepts behind these steps, follow the links at the end of each section. ## Import a local folder [Section titled “Import a local folder”](#import-a-local-folder) Turn a folder on your computer into a **cloud project**, history included (desktop app only). 1. In the project list, click **Import repo** and choose the folder. 2. If it isn’t a git repository yet, Tanzanite proposes a `.gitignore` and initializes one before anything is committed. 3. Pick any extra branches or tags to bring along (the default branch and its full history always come), then click **Import history**. The history is uploaded to the git repo Tanzanite hosts for the project, and the folder stays linked as its local mirror. See [How cloud agents run](/using/cloud-execution/#the-local-mirror-sync) for how the mirror keeps both sides in step. ## Schedule a run [Section titled “Schedule a run”](#schedule-a-run) Run an agent automatically on a recurring basis — a morning briefing, a nightly check, a weekly report. 1. Open **Schedules** in the sidebar and create a schedule for a Cloud or Device project. 2. Give it what to do — a prompt for the agent, a script from the project, or both — and the cadence (for example, every morning or each Monday). 3. Save it. Tanzanite runs it on that cadence and records each fire in the schedule’s run history. A schedule can also be started by a commit instead of the clock — that is a **trigger**, on the Triggers tab of the same screen. More in [Schedules & Triggers](/using/schedules/). ## Add a skill [Section titled “Add a skill”](#add-a-skill) A **skill** is a pack of instructions an agent loads when a task calls for it — your house style, a review checklist, the steps for a fiddly internal process. Your skills live under **Skills** in the sidebar. Four ways to add one: 1. **Import from GitHub** — paste `owner/repo` or a GitHub URL. Tanzanite reads the repository’s `SKILL.md` plus any `references/`, `scripts/`, and `assets/` files. If a repository holds several skills, the first one found is imported. 2. **Create manually** — a name, a description, and the instructions themselves. 3. **Create with AI** — describe what you want in a chat and ask the agent to save it; it drafts the skill and adds it to your library. 4. **Import a folder** — pick a folder on your computer that already contains a `SKILL.md` (Chromium-based browsers and the desktop app). The **description matters more than it looks**: until an agent decides a skill is relevant, the name and description are all it sees. Write it as *what this does and when to use it*, not as a title. Built-in skills appear in the same library marked **Built-in** — you can attach those, but not edit them. ## Attach a skill to a project or a chat [Section titled “Attach a skill to a project or a chat”](#attach-a-skill-to-a-project-or-a-chat) Adding a skill to your library does not switch it on. Attach it in one of two places, depending on how often you want it: * **Every chat in a project** — **Project Settings → Skills**. It applies to every new chat in that project, and to sub-agents those chats spawn. * **Just this chat** — click the **Skills** chip in the message composer and toggle it on. The chip shows how many skills are active in the chat you have open, and the popover separates *on this chat* from *from project*. To silence a project-wide skill for one conversation without removing it for everybody, switch it off in the chip: it shows struck-through with an undo, and the project keeps it. You can also just ask — *“attach the pdf skill to this chat”*, *“make me a skill for PR reviews”*, or *“which skills are on right now?”* all work in chat. There is a limit of **24 active skills per chat**. Each one costs a little of every message the agent sees, so the cap keeps runs fast; if you hit it, detach something first. Skills work alongside the harness, which decides which tools an agent can reach. See [The Harness](/using/harness/#skills-and-plugins). ## Next steps [Section titled “Next steps”](#next-steps) * New to the app? Start with [Install & first run](/using/getting-started/). * Something not working? See [Troubleshooting & FAQ](/using/troubleshooting/). # What is Tanzanite > Tanzanite is an AI agent platform that orchestrates autonomous coding and task agents from a native app, governed by a harness. Tanzanite is an AI agent platform. It lets you run autonomous agents that plan, call tools, write and edit files, execute code, and complete multi-step work on your behalf — from a native app on macOS (with iOS and Android in progress). ## How it fits together [Section titled “How it fits together”](#how-it-fits-together) Agents run in the cloud and act on your machine through a secure bridge: * **The app** is where you work — create projects, talk to agents, review and approve their actions, and watch plans run in real time. * **Agents run in the cloud** and stream their reasoning, tool calls, and results back to you live. * **Tool calls reach your machine** through a WebSocket bridge, so an agent can read and write files in a project folder, run commands, and use local capabilities — only with your approval. * **A harness governs every agent.** The harness defines the system prompt, which tools are available, how models are routed, and the safety guardrails. ## What you can do [Section titled “What you can do”](#what-you-can-do) Out of the box, Tanzanite supports: * **Projects** — cloud or local working contexts an agent operates in. * **Chat & agents** — direct conversation plus long-running autonomous plans that can spawn subagents for parallel work. * **Schedules & triggers** — recurring runs, and runs started by a commit. * **Code execution** — run JavaScript or Python scripts in a secure sandbox. * **File, image, video, and voice** — upload media, generate it, and dictate. ## Where to go next [Section titled “Where to go next”](#where-to-go-next) * New here? Start with [Install & first run](/using/getting-started/), then the [Quickstart](/using/quickstart/). * Ready to do something specific? Browse the [Task how-tos](/using/how-to/). # Pricing & credits > Credits-only pricing — one prepaid balance funds everything, itemized to the cent. Tanzanite is **usage-based and credits-only**. There are no subscription plans and no feature tiers: every account has access to every feature, and one prepaid **credit balance** funds everything the agent does — cloud models, sandboxes, media generation, storage, and cloud-project rent. Everything is priced in USD and itemized to the cent, so there are no surprises: you only pay for what the agent actually uses. ## What’s free [Section titled “What’s free”](#whats-free) **Local projects on the desktop app are genuinely free.** The on-device model runs entirely on your machine at no cost — no card, no credits needed. The auto-created **General workspace** is also free (no daily project rent). ## Credits [Section titled “Credits”](#credits) Credits are **prepaid** and never expire while your account is active. Top up any time from **Account → Billing** — you choose the amount at checkout (minimum **$5**), and the balance appears immediately after payment. Checkout enforces a **monthly add cap** (default $500 in one UTC calendar month). There is no separate per-purchase or balance ceiling beyond that remaining monthly room; the checkout page shows how much you have left this month if you hit it. The balance you see is **available = credits − reserved − spent**. It can go **negative** (a settle that overshot, a refund, or a bonus clawback) — Tanzanite shows the real number, never a clamped zero. New paid work still won’t start until you add credits. **Auto-reload** (optional) tops your balance up automatically from your saved card whenever it runs low, so long tasks are never stopped mid-run for lack of credits. Each reload has a maximum amount. Turn it on at your first purchase and you’ll get **bonus credits** on that purchase (30%, capped at $50) — the bonus becomes permanently yours after your first automatic reload completes. You can turn auto-reload off any time from the Billing tab. Anything with a real cloud cost draws from your balance as it runs: cloud model calls, sandbox compute time, media generation, hosted-repo storage, and **cloud-project rent** (a flat monthly price, charged as a daily slice; the auto-created General workspace and local projects are free). Before paid work starts, Tanzanite places a small hold for the estimated cost and settles the exact amount when the work finishes, so two runs can’t both spend the same dollar. When your balance runs out, the run **stops** with **“You’re out of credits. Add credits to continue.”** — nothing keeps charging in the background unless auto-reload is on. Add credits and start a fresh run; only a **spend limit you set** (per-run or per-project) pauses instead, and resumes where it left off once you raise or remove the limit. Your **Billing** tab shows the live balance (including any amount currently held by in-flight runs) and an itemized history of every purchase and charge. Staff accounts skip the funds gate so internal work isn’t blocked by a $0 wallet. That exemption is not a product tier. ## Resource limits [Section titled “Resource limits”](#resource-limits) Independent of money, each account has resource quotas — concurrent sandboxes, cloud projects, and storage — that keep any one account from monopolizing shared infrastructure. These are generous defaults, not paywalls; if you hit one, the error says exactly which limit you reached. ## Next steps [Section titled “Next steps”](#next-steps) * Learn what the [three project setups](/using/projects/) — Cloud, Device and Local — mean for cost and privacy. * See [Chat, plans & goals](/using/agents-and-chat/) for how runs consume usage. * Manage your balance in [Account, billing & limits](/using/account-billing/). # Projects > The three project setups — Cloud, Device and Local — the working context agents operate in, including the local bridge for file access. A **project** is the workspace an agent operates in. Everything an agent does — chats, plans, files, and tool calls — happens inside a project. Open **Projects** in the sidebar and click **New Project** to create one. Your projects also appear in the sidebar so you can switch the active project at any time.  *Switching the active project from the sidebar.* ## Choosing a setup [Section titled “Choosing a setup”](#choosing-a-setup) Every project answers the same four questions — where the AI model runs, where your plans and chats are saved, where your files live, and what it needs in order to run. You pick one of three setups when you create it, and the app shows all four facts next to each choice. **Cloud** — *Files are hosted by Tanzanite; the AI runs in the cloud.* Fully managed: nothing is required on your machine, and you can work from the web or your phone. Optionally mirror the files to a folder on your computer. Cloud work is paid for with prepaid credits — see [Pricing & credits](/using/pricing/). **Device** — *Files stay on this machine; the AI runs in the cloud.* Tanzanite opens a native folder picker and requests file-system access to that folder; there is no hosted copy of your files. Your chats and plans are still saved to your account, so you can read them on the web — but a run needs this desktop app open, because that’s where the files are. You can **promote it to Cloud** later: that adds a hosted repo and changes nothing else. **Local** — *Everything stays on this machine.* The model runs on your computer too, and your chats and plans are stored only there. Free, desktop-only, and a genuine privacy guarantee. It **cannot be converted** to another setup later, so choose Device instead if you might want your chats on the web one day. Choosing a **local model** is a separate decision from the setup: a Cloud or Device project can run on a model on your own machine and still save its chats to your account. For any project with a folder you can also configure build, run, and dev commands in the project’s settings. ## The local bridge [Section titled “The local bridge”](#the-local-bridge) When a project has a folder on your machine, the app exposes file-system tools to the agent over the **local bridge** — a secure WebSocket connection between the app and the agent runtime. The agent can list, read, and write files in that folder only. Sensitive actions surface as **approval requests** before they run. ## Next steps [Section titled “Next steps”](#next-steps) * See how [chats and plans](/using/agents-and-chat/) run inside a project. * Automate recurring work with [Schedules & Triggers](/using/schedules/). # Quickstart > Install the Tanzanite app, sign in, create your first project, and run your first agent. This guide gets you from zero to a running agent in a few minutes. Note The images on this page are illustrative placeholders — real captures from the app are on the way. The steps and on-screen labels they describe are accurate for the shipped macOS build. ## 1. Install the app [Section titled “1. Install the app”](#1-install-the-app) Download the latest Tanzanite build for macOS and open it. Tanzanite runs both as a full window and in your menu bar (system tray). ## 2. Sign in [Section titled “2. Sign in”](#2-sign-in) Create an account or sign in with email and password (or Google).  *The sign-in screen.* For a fuller walkthrough of download and first run per platform, see [Install & first run](/using/getting-started/). ## 3. Find your way around [Section titled “3. Find your way around”](#3-find-your-way-around) The left **sidebar** is the main navigation, top to bottom: * **Chat** — talk to an agent or give it a task (clearing the active project for general chat). See [Chat, plans & goals](/using/agents-and-chat/). * **Skills** — instruction packs the agent loads on demand. * **Projects** — your working contexts (Cloud, Device or Local). * **Host apps** — apps you use elsewhere that you connected to Tanzanite, and keys for your own scripts. * **Schedules** — run agents on a recurring schedule, or when a commit lands. * **LLM Calls** — the full input of each model call, for debugging. * **Account**, **Settings** — your billing and preferences. Below them the sidebar lists your projects. ## 4. Create a project [Section titled “4. Create a project”](#4-create-a-project) Open **Projects** in the sidebar and click **New Project**. Choose: * **Cloud** — files hosted by Tanzanite, the AI runs in the cloud; nothing needed on your machine. * **Device** — files stay in a folder on this machine, the AI runs in the cloud; Tanzanite opens a native folder picker (“Select project folder”) and requests file-system access to that folder. Your chats still sync to your account. * **Local** — everything stays on this machine, model included; free and desktop-only.  *Projects → New Project.* See [Projects](/using/projects/) for what each setup means. ## 5. Start a chat or a plan [Section titled “5. Start a chat or a plan”](#5-start-a-chat-or-a-plan) With a project active, open **Chat** and either ask a quick question or give the agent a **goal** to kick off an autonomous run. The agent breaks the goal into steps, calls tools, and can spawn subagents for parallel work.  *Entering a goal in Chat.* ## 6. Review, approve, and watch it run [Section titled “6. Review, approve, and watch it run”](#6-review-approve-and-watch-it-run) When an agent wants to take a sensitive action (writing files, running a command), it pauses for your approval. The plan tree shows each step live — reasoning, tool calls, results, and cost — and you can pause, resume with a new budget, redirect, or cancel.  *A live plan with an approval prompt.* ## Next steps [Section titled “Next steps”](#next-steps) * Learn how [Projects](/using/projects/) work. * Set up [Schedules & Triggers](/using/schedules/) for recurring automation. * Understand [the Harness](/using/harness/) that governs agent behavior. # Schedules & Triggers > Run agents on a recurring schedule, or start one when a commit lands. Beyond one-off chats and plans, Tanzanite can start work for you on its own — on a clock, or when your project’s code changes. ## Schedules [Section titled “Schedules”](#schedules) A **schedule** runs on a recurring cadence — for example, a morning briefing or a nightly check. Each time it fires it can run a script from your project, start an agent with a prompt, or both. Set the cadence (a cron expression, in your time zone) and Tanzanite handles the rest; every fire is recorded in the schedule’s run history. Manage schedules under **Schedules** in the sidebar. Cloud and Device projects can be scheduled; a Device project’s runs need its desktop to be connected. Local projects run on your machine, so they cannot be scheduled. ## Triggers [Section titled “Triggers”](#triggers) A **trigger** is a schedule whose clock is a commit: when a commit lands on a branch you choose (optionally only when certain paths change), it starts the same kind of run. Triggers live on the **Triggers** tab of the Schedules screen, each with a daily fire cap so a busy branch cannot run away. ## Next steps [Section titled “Next steps”](#next-steps) * Follow the step-by-step guide to [schedule a run](/using/how-to/#schedule-a-run). # Security > How Tanzanite isolates agent execution, where your data lives, what we encrypt, and how to report a vulnerability. This page describes how Tanzanite is built to protect your projects and your account. It is written from the system as it actually runs today — not a roadmap — and every claim below is something you can hold us to. To **report a vulnerability**, email . Our disclosure policy, scope and response commitments are at [tanzanite.ai/security](https://tanzanite.ai/security); the machine-readable contact is [`/.well-known/security.txt`](https://tanzanite.ai/.well-known/security.txt). ## Where agents run [Section titled “Where agents run”](#where-agents-run) Cloud agents execute tools in a **sandbox that is isolated from other users and from our own control plane**: * Every cloud sandbox is a dedicated Kubernetes pod under **gVisor**, a user-space kernel that separates the workload from the host kernel. Pods run as a non-root user. * The sandbox holds **no credentials for our systems**: no database access, no provider API keys, no other user’s data. The only credential inside it is a short-lived git token scoped to *that one project’s repository*. A compromised sandbox can reach exactly that repository and nothing else. * Every call that needs a secret (an LLM provider, a connected service, a payment) is made by our control plane, and only the *result* is handed to the sandbox. * Scripts the agent runs inside a sandbox have **no ambient network** unless the tool that launched them explicitly allows it; outbound web access from the agent’s own tools goes through a request guard that blocks private and internal address ranges. * A sandbox is torn down when its session ends. Nothing persists in it between sessions except through the project’s git repository. When the desktop app is open, a project can instead run its tools **on your own machine**, and a project can be marked *local-private* so that its files never leave your device at all — see [How cloud agents run](/using/cloud-execution/). ## Your data [Section titled “Your data”](#your-data) * **One writer.** Only our control-plane service writes to the database; the database’s own access rules deny every direct read or write. Browsers, desktop apps and sandboxes go through authenticated API routes with per-user authorization on every request. * **Encryption at rest.** All stored data is encrypted at rest by Google Cloud. Two classes of record carry an additional layer of **application-level envelope encryption** with keys held in Cloud KMS, bound to the owning user so a record cannot be replayed into another account: saved browser logins, and project secrets (which the agent can only ever reference, never read back). * **Encryption in transit.** All traffic is HTTPS; our domains enforce HSTS with preload. * **Media handling.** Uploaded media that needs parsing is processed only inside a sandbox, never on the control plane. * **Model providers don’t train on your data.** Every request we send to a model through OpenRouter is flagged to route only to providers whose policy forbids training on, or retaining for training, what you send; providers without that guarantee are excluded. (Providers may hold prompts briefly for abuse monitoring under their own terms.) * **Data residency.** Production runs in Google Cloud, region `us-central1` (Iowa, USA). Our vendors and what each processes are listed on the [subprocessors page](https://tanzanite.ai/subprocessors). ## Your account [Section titled “Your account”](#your-account) * Sign-in by email/password or Google, with bot protection on signup. * **Per-device sessions** you can review and revoke individually from Account settings; changing your password revokes every other session. * Security notifications by email for new-device sign-ins, password and email changes, and account deletion requests. * **Account deletion** is a 30-day soft-delete you can cancel, followed by an enforced purge across every store; you can export your data at any time before that. ## Coming [Section titled “Coming”](#coming) We are transparent about what is *not* yet in place: * **Two-factor authentication** (TOTP) is planned but not yet available. * **Per-project encryption keys** for plan and message content (on top of Google’s disk encryption) are designed and scheduled. ## Reporting a vulnerability [Section titled “Reporting a vulnerability”](#reporting-a-vulnerability) Email with enough detail to reproduce. We acknowledge reports within **3 business days** and aim to fix or give you a status update within **30 days**. Good-faith research that follows the policy at [tanzanite.ai/security](https://tanzanite.ai/security) will not be met with legal action. We do not run a paid bounty program at this time. # Troubleshooting & FAQ > Fixes for the things that come up most in Tanzanite — a stuck agent, sync conflicts, connecting a repo, sign-in trouble, and billing questions. Quick fixes for the most common issues, grouped by area. If something here doesn’t resolve it, the concept pages linked in each section have the full detail. ## Installation & sign-in [Section titled “Installation & sign-in”](#installation--sign-in) **The macOS app won’t open (“unidentified developer” or similar).** On first launch, approve opening the app in the macOS security prompt. If it still won’t open, re-download the latest build and try again. **I can’t sign in.** Tanzanite supports **email/password** and **Google** sign-in. If you signed up with Google, use the **Continue with Google** button rather than a password. Confirm you’re using the same email you signed up with — your balance and projects are tied to that account. **My projects aren’t showing on another device.** Sign in with the **same account**. Your balance and projects follow the account, not the device. ## Running agents [Section titled “Running agents”](#running-agents) **My agent is stuck or waiting.** The most common cause is a **pending approval**. Agents pause before sensitive actions (writing files, running commands) and wait for you to approve. Check the plan tree for an approval prompt and respond to it. **My run paused on its own.** If your credit balance ran out, the run **pauses** and prompts you to add credits. Top up in **Account → Billing** and resume — the run continues where it left off. See [Account, billing & limits](/using/account-billing/). **The agent is heading in the wrong direction.** You don’t have to cancel and start over — **pause**, then **redirect** it toward a different focus, or **resume with a new budget**. Cancel only when you’re truly done. Tip Every run tracks cost live in the plan tree. If a task is running longer or costing more than expected, pause it and review the steps before resuming. ## Sync & local files [Section titled “Sync & local files”](#sync--local-files) **My local edits and the agent’s edits disagree.** A cloud project’s **local mirror** keeps a folder in lockstep with the cloud repo. Non-overlapping changes merge automatically. A genuine same-line conflict is surfaced for you to resolve, and **your version is preserved** on a `tz/local/` branch as a safety net — nothing is thrown away. **Some files never sync.** That’s expected for anything matched by `.gitignore` — ignored files never sync, never reach the cloud, and never enter a sandbox. If a file you want *is* being ignored, remove it from `.gitignore`. **The agent isn’t running on my machine.** Device execution needs three things: the **desktop app open**, a **linked local mirror**, and **“Run agents on this device”** turned on for that project. If any is missing, the run happens in a cloud sandbox instead. Details in [How cloud agents run](/using/cloud-execution/). ## Projects & repos [Section titled “Projects & repos”](#projects--repos) **I can’t create a cloud project.** You’ve most likely hit your account’s cloud-project quota — the error names the limit. Delete a project you no longer need to make room. Local projects stay free on the desktop app. ## Billing & account [Section titled “Billing & account”](#billing--account) **Where do I manage my credits?** In **Account → Billing** — see your balance, buy credits, and review usage. There are no subscription plans to change. **Why was my run more expensive than expected?** Pricing is by token usage; long autonomous plans with subagents consume more than short chats. Open the plan tree to see the per-step cost breakdown. Local projects on the on-device model cost nothing. **My credits ran out mid-task.** The prompt is **“You’re out of credits. Add credits to continue.”** That run has **stopped** — top up in **Account → Billing** and start a fresh run (finished steps are kept in the plan’s history), or move the work to a **local project** (free on the desktop app). Only a run halted by a **spend limit you set** is paused and resumes where it left off. **My balance is negative.** A settle overshoot, refund, or bonus clawback can put the wallet slightly below zero. The number is real — new paid work won’t start until you add credits. **A cloud project was paused for billing.** Unpaid daily project rent pauses cloud projects; files and history stay. Add credits and they come back within seconds. The auto-created General workspace and local projects are free. ## FAQ [Section titled “FAQ”](#faq) **Is there a free way to use Tanzanite?** Yes — **local projects** on the desktop app run on an on-device model at no cost, entirely on your machine. **Does my code leave my machine?** For a local project, no — the model and the agent both run on-device. For a cloud project, tools run either on your machine (when the desktop app is open and device execution is on) or in a secure cloud sandbox. Your provider keys and secrets stay in Tanzanite’s control plane and are never sent to a sandbox or device. See [How cloud agents run](/using/cloud-execution/#what-stays-private-and-secure). **Can I use Tanzanite on my phone?** Mobile (iOS and Android) is in progress. On mobile, agents run in the cloud — good for starting runs and approving actions, not for working against local files. ## Still stuck? [Section titled “Still stuck?”](#still-stuck) Check the relevant concept page — [Projects](/using/projects/), [Chat, plans & goals](/using/agents-and-chat/), [How cloud agents run](/using/cloud-execution/), or [The Harness](/using/harness/) — for the full picture behind any of the above.