API reference

Developer docs

The Gist API serves pre-synthesized cultural context as JSON. One authenticated GET returns the current context block for a topic — drop it into your agent's system prompt or fetch it fresh on each call. Blocks are built ahead of time and served as-is, so reads are fast and cacheable. Need an answer to a specific question instead? Search a topic with a free-text query for an on-demand read.

Base URL

All endpoints are relative to:

https://gist-api.the-alt.co

Authentication

Every request needs a secret key in the Authorization header as a bearer token. Create and manage keys from your dashboard. Keys look like gist_sk_live_… — keep them server-side. A missing or invalid key returns 401.

Get the current context block

GET/v1/context/{topic}

Returns the current context block for a subscribed topic — one interpreted, prompt-ready read of where the topic stands right now. knowledgeCutoff tells you exactly how fresh it is, and cacheControl.nextRefresh when to fetch again.

Path parameters

Parameter	Type	Description
topic	string	required · The topic slug, e.g. fashion. Must be a topic you are subscribed to.

Query parameters

Parameter	Type	Description
segment	string	optional · A segment id or name that targets a specific segment. Omit to get the topic's default segment. The segment must be active on your plan.

Example request

curl https://gist-api.the-alt.co/v1/context/fashion \
  -H "Authorization: Bearer $GIST_KEY"

200 · application/json

{
  "topic": "fashion",
  "segment": { "segmentId": "c980ccca-…", "name": "Global" },
  "knowledgeCutoff": "2026-07-12T23:59:59.999Z",
  "asOf": {
    "week": "2026-07-13-W29",
    "windowStart": "2026-07-06",
    "windowEnd": "2026-07-12"
  },
  "summary": "Wide-leg trousers and baggy jeans are foundational, often ...",
  "read": "The dominant silhouette is relaxed and oversized from the ...",
  "cacheControl": {
    "validUntil": "2026-07-20",
    "nextRefresh": "2026-07-20"
  },
  "noSignal": false,
  "notes": "",
  "contentRead": null
}

Response fields

Field	Type	Description
topic	string	The topic slug.
segment.segmentId	string	Stable id of the segment this block is for.
segment.name	string	Human-readable segment name, e.g. "Global".
knowledgeCutoff	string	ISO 8601 · The instant the block's knowledge runs through (inclusive).
asOf.week	string	Publishing-week code for the source window.
asOf.windowStart	string	date · First day of the window the block summarizes (inclusive).
asOf.windowEnd	string	date · Last day of the window (inclusive).
summary	string	Short, prompt-ready synthesis of the topic.
read	string	Longer narrative read with more detail.
cacheControl.validUntil	string	date · The block is current until this date.
cacheControl.nextRefresh	string	date · When the next version is expected — poll on or after this.
noSignal	boolean	True when the block’s focused slice lacked cross-creator support (default segments never signal false here).
notes	string	Human note, e.g. the reason for a no-signal block. Empty string when none.
contentRead	string \| null	The content-formats read for content/campaign consumers, or null for blocks baked without it.

Search a topic

POST/v1/search/{topic}

Ask a free-text question about a topic and get an on-demand, always-fresh read — the same synthesis engine as a saved segment, but throwaway. Requires an active subscription to the topic. Each call spends 3 units from your plan's search-unit budget. A repeat of the same query is served from cache until cacheControl.nextRefresh and does not spend a unit (usage.cached: true); usage.unitsRemaining tells you what's left. The read core (asOf, summary, read, knowledgeCutoff, cacheControl) matches Get the current context block field-for-field.

Path parameters

Parameter	Type	Description
topic	string	required · The topic slug, e.g. fashion. Must be a topic you are subscribed to.

Body parameters

Parameter	Type	Description
query	string	required · Your free-text question about the topic (max 400 characters).
geo	string	optional · Narrow the read to a place, e.g. "North America" or "Western Europe". Omit for a global read.
thinking	"standard"	default standard · Model tier. One tier — standard — costing 3 units. The retired "lite" and "pro" ids are still accepted and resolve to standard at the same 3 units.
content	boolean	default false · Also return content_read — a readout of the content FORMATS running (hooks, structure, angles, sounds), separate from the subject read.

Example request

curl -X POST https://gist-api.the-alt.co/v1/search/fashion \
  -H "Authorization: Bearer $GIST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what streetwear silhouettes are gaining right now?",
    "geo": "Europe",
    "thinking": "standard",
    "content": true
  }'

200 · application/json

{
  "topic": "fashion",
  "query": "what streetwear silhouettes are gaining right now?",
  "geo": "Europe",
  "thinking": "standard",
  "knowledgeCutoff": "2026-07-12T23:59:59.999Z",
  "asOf": {
    "week": "2026-07-13-W29",
    "windowStart": "2026-07-06",
    "windowEnd": "2026-07-12"
  },
  "summary": "Relaxed, oversized streetwear with a utilitarian bent ...",
  "read": "Baggy, low-slung silhouettes are pulling ahead — parachute and ...",
  "noSignal": false,
  "notes": "",
  "contentRead": "Reels lead with a 3-second fit-check hook, then a ...",
  "cacheControl": {
    "validUntil": "2026-07-20",
    "nextRefresh": "2026-07-20"
  },
  "usage": {
    "cached": false,
    "unitsRemaining": 89
  }
}

Response fields

Field	Type	Description
topic	string	The topic you searched.
query	string	Your query, echoed back.
geo	string \| null	The geo scope applied, or null for a global read.
thinking	string	The model tier used — always "standard".
knowledgeCutoff	string	ISO 8601 · The instant the read’s knowledge runs through (inclusive). Same shape as /v1/context.
asOf.week	string	Publishing-week code for the source window.
asOf.windowStart	string	date · First day of the window the read summarizes (inclusive).
asOf.windowEnd	string	date · Last day of the window (inclusive).
summary	string	Short, prompt-ready synthesis.
read	string	The synthesized read answering your query.
noSignal	boolean	True when the topic lacks enough cross-creator signal for your query.
notes	string	Context, populated when noSignal is true.
contentRead	string \| null	Readout of the content formats running — null unless content:true was requested.
cacheControl.validUntil	string	date · The read is current until this date.
cacheControl.nextRefresh	string	date · When the read re-synthesizes — a repeat query is free (cached) until then.
usage.cached	boolean	True when served from cache — a cached response does NOT consume a unit.
usage.unitsRemaining	number	Your remaining search units after this call.

Errors

Errors use standard HTTP status codes and a consistent JSON envelope:

4xx · application/json

{
  "error": {
    "code": "not_found",
    "message": "No context published for topic 'fashion'."
  }
}

Status	Code	When
400	invalid_request	A parameter was malformed.
401	—	Missing, invalid, or revoked API key.
403	forbidden	Not subscribed to the topic, or the requested segment isn't active on your plan.
403	plan_required	The topic isn't available on your plan (e.g. a paid topic on the Free plan).
404	not_found	No context block has been published for that topic/segment yet.
429	rate_limited	Per-minute burst limit exceeded — retry shortly.
429	quota_exceeded	Search usage limit reached for your plan (POST /v1/search).