API Reference
Every endpoint, request, and response. The full OpenAPI 3.1 spec is available at /api/v1/openapi.yaml.
Base URL
https://api.gistate.com/api/v1Authentication
Two auth modes depending on the endpoint:
Bearer (API key)
Used for the core API: refine, merge, chat.
Authorization: Bearer GS_xxxxxxxxxxxxxxxxxxxxxxxxSession cookie
Used for dashboard endpoints under /auth/* and /account/*. Login sets an httpOnly Secure SameSite=Lax cookie. Mutations require an X-CSRF-Token header obtained from GET /auth/me.
Refine
POST /refine
Compress raw context into a versioned gist.
Request
{
"raw_transcript": "User: build a CLI ...",
"v_target": "claude-opus-5-5",
"intent": "refine" | "ingest" | "normalize",
"save": true // optional; false returns the gist without committing or charging
}Response
{
"gist": {
"g_id": "g_id_...",
"v_target": "claude-opus-5-5",
"tokens": 487,
"snapshot": { ... },
"parent_hash": null,
"state_checksum": "sha256:...",
"stability_passed": true
},
"receipt": {
"input_tokens": 148230,
"output_tokens": 487,
"savings_pct": 99.7
},
"g_id": "g_id_...", // committed id, use it with /chat
"saved": true,
"charged_usd": 0.0231, // USD. charged_usd_micros is also returned
"normalization": { // null when structured messages were sent
"method": "boundary_markers",
"chunks": 1,
"anchors_matched": 57,
"anchors_missed": 2,
"chunk_fallbacks": 0,
"repair_retries": 0
},
"fidelity": { // the receipt: exact details of the conversation found in the state
"version": 1, "checked": 20, "kept": 18,
"missing": ["render.yaml", "TRUST_PROXY_HOPS"]
},
"warnings": []
}Instead of raw_transcript, messages takes the conversation as [{ "role": "user" | "assistant", "content": "..." }], with an optional commit_message naming the state.
Errors
402 INSUFFICIENT_CREDITS422 REFINE_FAILED
Merge
POST /merge
Atomically combine two gist states. Postgres advisory locks serialize concurrent merges on the same parent.
Request
{
"stateA": { ... gist JSON ... },
"stateB": { ... gist JSON ... },
"v_target": "claude-opus-5-5"
}Errors
402 INSUFFICIENT_CREDITS409 INTEGRITY_FAILURE / CONCURRENCY_LOCK422 GOVERNOR_PRE rejection
Chat (Router)
Continue a saved state on-platform. The server restores the whole session from the head state, answers one turn with the chosen model, bills it, and writes a checkpoint every checkpoint_every_turns turns. Each checkpoint folds the previous state together with the turns since it, so the new head is the whole session on its own. POST /chat/stream takes the same body and streams the reply as server-sent events.
POST /api/v1/chat
{
"g_id": "g_id_...", // head to continue from (omit to start fresh)
"v_target": "gpt-6-sol", // any model from GET /pricing/models
"messages": [ ...turns since the last checkpoint... ],
"message": "What port is Postgres on?",
"effort": "standard", // optional: low | standard | max output budget
"attachments": [ "sha256..." ], // optional: images, PDFs, audio or video uploaded to /attachments
"handoff_from": "claude-opus-5-5", // optional: the model the conversation was on
"checkpoint": false, // true writes a checkpoint after this turn
"commit_message": "Before the refactor", // optional label for that checkpoint
"key_source": "gistate", // optional: "own" or "gistate" for this request
"files": true, // optional: true saves the reply's named files; "read" only shows the session's
"sandbox": false, // optional: with files true, the model may run code in the session's sandbox
"instructions": false, // optional: leave the account's standing instructions out of this turn
"memory": false, // optional: leave the person's memory out of this turn (when it is on)
"assistant": false, // optional: leave out the assistant the session was started from
"connectors": ["<connector_id>"], // optional: the connectors whose tools the model may call (see Connectors)
"tool_round": { "connectors": ["<connector_id>"] } // optional: this message carries those connectors' results
}
// Response
{
"reply": "5432",
"head_g_id": "g_id_...", // new head if a checkpoint was written
"charged_usd": 0.0021, // USD for this turn
"charged_usd_micros": 2100, // the same figure in integer micros
"key_source": "gistate", // or "own": the account's own provider key
"turns_since_checkpoint": 3,
"checkpoint_every_turns": 10,
"checkpoint": null, // or { g_id, depth, charged_usd, receipt, fidelity }
"runs": [ ... ], // with sandbox: what the reply ran, its output and the files it saved
"runs_message": "...", // send as the next message, and the model goes on from the results
"tool_calls": [ ... ], // with connectors: the calls the reply made, waiting, run or invalid
"tools_message": "...", // once none waits and one ran: send it as the next message, with tool_round
"tools_from": [ "<connector_id>" ]
}With checkpoint: true and no message, the request only saves: the turns in messages are folded into a new head and no model reply is requested. To hand a conversation to another model, save it that way under the new v_target, then send the next message with handoff_from naming the model it came from; the handoff is recorded and billed at provider cost.
Errors
402 INSUFFICIENT_CREDITSor402 PROVIDER_BUDGET_EXCEEDED: the balance that pays for this model cannot cover the turn403 MODEL_NOT_ENTITLED: the model is not currently offered (see Models)400 MODEL_NO_VISION,MODEL_NO_PDF,MODEL_NO_AUDIO,MODEL_NO_VIDEO: an attachment sent to a model that does not read its kind400 BYOK_KEY_REFUSED,400 BYOK_KEY_NO_CREDIT,429 BYOK_KEY_RATE_LIMITED: the account's own provider key could not be used; nothing was sent or charged. Send it again with"key_source": "gistate"to use GiState's keys400 BYOK_NO_KEY: the request asked for the account's own key, or the account uses only its own keys, and there is none for this model's provider
Your instructions
What every model should know or do, sent with every message on the account after the saved state, and with every Work task. Up to 4,000 characters; an empty string clears them. They are part of each message's input and billed with it.
GET /api/v1/account/instructions
PUT /api/v1/account/instructions { "instructions": "Answer in British English." }Assistants
A model, instructions, files and suggested tools set up once. A session started from one carries its instructions in every message and Work task, before the account's own instructions and memory, which win where they differ; its files are copied into the session. Private to its maker, or shared from an organization seat with a team or the whole organization; only its maker changes it. Whoever starts a session from one pays for that session. model is a model id, or null to leave the model to whoever uses it; tools are suggestions, never switched on.
GET /api/v1/assistants { assistants, share: { org, teams }, limits }
POST /api/v1/assistants { "name", "description", "instructions", "model", "starters": [..4],
"tools": { "web", "sandbox" }, "visibility": "private" | "team" | "org", "team_id" }
GET /api/v1/assistants/:id { assistant, files }
PATCH /api/v1/assistants/:id any of the fields above (its maker)
DELETE /api/v1/assistants/:id its maker, or an owner or admin of its organization
POST /api/v1/assistants/:id/files { "name": "style.md", "data": "<base64>" } read as a session upload is
DELETE /api/v1/assistants/:id/files?path=style.md
POST /api/v1/assistants/:id/sessions { "name": "optional" } a new session from it, its files copied inConnectors
The account's own services through their MCP servers (Streamable HTTP; the 2026-07-28 protocol and older servers that use initialize). A connector signs in with nothing, a token, or OAuth at the service. A turn with connectors tells the model their tools; the model calls one in a tool code block. Each call waits for POST /connector-calls/:id/run (optionally with edited arguments) or /discard, unless its tool is set to run without asking, and never runs by itself after web pages, attachments or another connector's results. Once none of a reply's calls waits, the run answer's followup.message (or the turn's tools_message) hands the results to the model as the next message. Calls are free; each round is billed like a reply.
GET /api/v1/connectors { connectors, directory, config }
POST /api/v1/connectors { "name", "url", "auth": "none" | "bearer" | "oauth", "token" }
PATCH /api/v1/connectors/:id { "name", "url", "token", "enabled", "tools": { "<tool>": { "off", "auto" } } }
DELETE /api/v1/connectors/:id
POST /api/v1/connectors/:id/refresh connect again and read its tools
POST /api/v1/connectors/:id/sign-in { authorize_url }: send the browser there
GET /api/v1/connector-calls?project_id= the session's calls
POST /api/v1/connector-calls/:id/run { "arguments": { ... } } -> { call, followup: { pending, message } }
POST /api/v1/connector-calls/:id/discardScheduled work and the daily brief
A schedule runs by itself at the times it names, in its own time zone, each run costing at most cap_usd: a question about a session (ask), whose answer is kept in the session's files under scheduled/, or a Work job (work), planned and then run with what the cap leaves. Three runs in a row that fail or are skipped pause it, saying why. The daily brief is off until turned on; it is made without a model call.
GET /api/v1/schedules { schedules, limits, enabled }
POST /api/v1/schedules { "name", "kind": "ask" | "work", "prompt", "project_id", "model", "mode",
"cap_usd", "every": "hours" | "day" | "weekdays" | "week" | "month",
"at": "08:30", "tz": "America/New_York", "interval_hours", "days": [1, 3],
"day_of_month", "email" }
PATCH /api/v1/schedules/:id any of the fields above, and "enabled"
DELETE /api/v1/schedules/:id
POST /api/v1/schedules/:id/run run it now, once -> 202 { run }
GET /api/v1/schedules/:id/runs { runs: [{ status, charge_usd, output, path, job_id, error, ... }] }
GET /api/v1/daily-brief { settings, briefs }
PUT /api/v1/daily-brief/settings { "enabled", "email", "hour": 0-23, "tz" }
POST /api/v1/daily-brief/now today's brief now, in the app onlyImporting history
One conversation from a ChatGPT or Claude export becomes a new session with a saved state. An account's first few are free; past them the request answers 409 IMPORT_NOT_FREE (with reason: used_up, too_long, own_keys, off or no_model) and changes nothing, and the conversation can be saved through /refine with its messages, billed like any save.
GET /api/v1/import/allowance
// { "free_total": 3, "free_used": 1, "free_left": 2, "free_max_chars": 60000, "model": "claude-haiku-5-5" }
POST /api/v1/import/free
{ "title": "Render deploy", "source": "chatgpt", "messages": [ { "role": "user", "content": "..." }, ... ] }
// 201 { "project": { "project_id", "name" }, "g_id", "fidelity", "free_left", "model" }Your own provider keys
An account can add its own Anthropic, OpenAI or Google key. Calls to that provider then run on it: the provider bills you directly, and GiState charges its fee (a share of the provider's list price, byok.fee_rate in GET /pricing/models, plus the per-operation fee). Keys are checked with the provider before they are saved, stored encrypted, and never returned. Changing them needs an admin-scoped key or the console.
GET /api/v1/account/provider-keys // keys (last four only) and settings
PUT /api/v1/account/provider-keys/anthropic { "key": "sk-ant-..." }
PATCH /api/v1/account/provider-keys/anthropic { "preferred": "own" } // or "gistate"
POST /api/v1/account/provider-keys/anthropic/test // ask the provider again
DELETE /api/v1/account/provider-keys/anthropic
PATCH /api/v1/account/provider-keys { "own_keys_only": true }Models and prices
GET /pricing/models. Public, no authentication.
Every model you can name as v_target, with what GiState charges for it. The list follows the providers: a new model appears once the provider serves it, is priced, and answers a test request; prices follow the providers' own; a model leaves on its retirement date. Billing reads the same catalog, so a price listed here is the price charged.
{
"models": [{
"model": "claude-opus-5-5",
"display_name": "Claude Opus 5.5",
"provider": "anthropic",
"capabilities": { "vision": true, "max_output_tokens": 128000, "context_length": 1000000 },
"reasoning": { "efforts": ["max", "xhigh", "high", "medium", "low"], "default_effort": "high" },
"benchmarks": { "intelligence_index": 57.6, "coding_index": null, "agentic_index": null },
"managed_price_per_m": { "input": 10, "output": 50, "cache_read": 0.5, "cache_write": 12.5 },
"provider_cost_per_m": { "input": 4, "output": 20, "cache_read": 0.2, "cache_write": 5 },
"long_context": null, // or { above_input_tokens, managed_price_per_m, ... }
"released_at": "2026-09-21T...",
"retires_at": null
}],
"byok": { "fee_rate": 0.1 }, // GiState's fee on your own provider key
"credit_usd": 0.01
}Prices are US dollars per million tokens. benchmarks.intelligence_index is the Artificial Analysis Intelligence Index where published, otherwise null.
Rehydrate (deprecated)
GET /rehydrate/{v_target}?g_id={g_id}
Session recovery check only. Verifies you own a live, loadable saved state and returns { "status": "success", "session_id": g_id }. nothing else. It performs no model execution and returns no content: the reconstructed prompt never leaves the server, and completions are served exclusively by POST /chat and POST /chat/stream. Responses carry a Deprecation header pointing at /chat.
Webhooks
Subscribe HTTPS endpoints to receive event notifications.
Events
credits_added: a payment or an automatic top-up reached the walletauto_reload_scheduled: the balance fell below your threshold and a top-up startedpayment_failed: a subscription payment did not go throughsubscription_period_renewed: a subscription period renewed
Verification
Every delivery includes an X-GiState-Signature header of the form sha256=<hex>: an HMAC SHA-256 of the raw request body, keyed with the secret shown once when the webhook is created. Compare it in constant time.
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
const received = req.get("X-GiState-Signature") || "";
if (received.length !== expected.length ||
!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
return res.status(401).end();
}Rate limits
None on paid usage. Your balance is the limit: every metered call reserves its maximum cost before it runs, and a call your balance cannot cover returns 402. An optional 6-hour spend ceiling, set from Edit on any key, stops a runaway loop.
A 429 means the model provider is limiting, your spend ceiling was reached (SAFETY_FUSE_TRIPPED), or one address made too many sign-in, sign-up or password-reset attempts.
Versioning
The API is versioned via URL path (/api/v1/). Optional X-Gist-Version header pins the schema version of returned gists (default: HC-Omni-Hybrid_v4.4).