Quickstart
Make your first save, continue, and merge calls in under five minutes.
Prerequisites
- A GiState account (sign up at /signup)
- An API key (create one in the dashboard at /keys)
- curl, or any HTTP client
1. Refine raw context into a gist
The refine operation compresses raw conversation text into a versioned gist.
curl -X POST https://api.gistate.com/api/v1/refine \
-H "Authorization: Bearer GS_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"raw_transcript": "User: build me a CLI app. Agent: started scaffolding ...",
"v_target": "claude-opus-5-5",
"intent": "refine"
}'The response contains the new gist ID and metadata:
{
"gist": {
"g_id": "g_id_a1b2c3d4...",
"v_target": "claude-opus-5-5",
"tokens": 487,
"snapshot": { ... },
"parent_hash": null,
"state_checksum": "sha256:...",
"stability_passed": true
},
"warnings": []
}2. Continue on a different model
Take the gist from step 1 and continue the conversation on a different model. GiState replays the state server-side on managed keys, the reconstructed prompt never leaves the platform, and returns the new model's reply. This is where cross-model portability shines.
curl -X POST https://api.gistate.com/api/v1/chat \
-H "Authorization: Bearer GS_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"g_id": "g_id_a1b2c3d4...",
"v_target": "gpt-6.1-sol",
"message": "Pick up where we left off, what is the next step?"
}'The response is GPT-6.1 Sol's continuation, answered from your saved state:
{
"reply": "Next step: wire the retry queue into ...",
"turns_since_checkpoint": 3,
"checkpoint": null,
"charged_usd": 0.0142
}Keep chatting from the newest head_g_id and switch v_target any time. The agent continues where it left off. GET /api/v1/pricing/models lists every model you can name, with its price.
3. Merge two gists
Combine two gist states atomically. The truth registry arbitrates any conflicting facts. Advisory locks prevent race conditions on concurrent merges.
curl -X POST https://api.gistate.com/api/v1/merge \
-H "Authorization: Bearer GS_your_key_here" \
-H "Content-Type: application/json" \
-d '{
"stateA": { ... gist JSON ... },
"stateB": { ... gist JSON ... },
"v_target": "claude-opus-5-5"
}'Next steps
- Read about core concepts like the truth registry and lineage.
- See the full API reference.
- Subscribe a webhook to hear about payments and balance top-ups.