ConteXtube API

Every work is available to programs at https://contextube.ai/api/v1. Reading needs no key and allows 60 requests a minute per IP. The full contract is in openapi.json; a summary for language models is in llms.txt.

Endpoints

Method	Path	What it returns
GET	`/content`	Published works, newest first. Filters: flow, tag, domain, language, limit (≤100), offset.
GET	`/content/{id}`	One work with per-layer counts and its top essence. {id} is the uuid or the slug.
GET	`/content/{id}/layer/{n}`	All chunks of layer 1 to 5, in reading order.
GET	`/search?q=`	Works ranked by relevance, each with its best-matching chunks.
POST	`/assemble`	The best chunks of one work that fit a token budget.
GET	`/feed`	Essences (L1) and evidence (L2) across the library, most important first.
GET	`/flows`	Creators' collections with work counts.
GET	`/categories`	Domains and tags with counts.
POST	`/publish`	Writers only. Publish or replace a work. Needs a publish key.
DELETE	`/publish/{slug}`	Writers only. Unpublish a work; nothing is deleted.

Read a work in three calls

curl "https://contextube.ai/api/v1/search?q=partnership"
curl "https://contextube.ai/api/v1/content/peace-treaty-architecture"
curl "https://contextube.ai/api/v1/content/peace-treaty-architecture/layer/1"

Assemble context to a budget

Send a work and a token budget; ConteXtube returns its most important chunks that fit, always opening with the work's essence. With focus, chunks that match those concepts rise. maxLayer caps the depth (default 3).

curl -X POST "https://contextube.ai/api/v1/assemble" \
  -H "Content-Type: application/json" \
  -d '{"contentId": "peace-treaty-architecture", "maxTokens": 1500, "focus": ["privacy"]}'

Strategies: relevant (default) ranks by importance and focus; complete fills layer by layer from L1; custom returns the chunkIds you name. The response ends with usage: tokens used, budget and chunks left out.

Publish a work

Writers send the whole unit as JSON with Authorization: Bearer <publish key>. Sending the same slug again replaces every chunk. The server counts tokens. Validation rejects the whole unit if a layer is outside 1 to 5, an extract runs past 8 words, an L2 chunk has no source_quote, or a copyrighted work carries L5 source text. All content is published in English. Images are optional: cover for the work, flow_cover for its flow, and up to five images per chunk, each a URL or an object with url, alt, credit and source.

{
  "flow": "andrei-navrotskii",
  "slug": "echo",
  "title": "Shards: Echo",
  "language": "en",
  "rights": "own",
  "tags": ["space", "war"],
  "domains": ["literature"],
  "cover": { "url": "https://…/cover.webp", "alt": "…", "credit": "…" },
  "chunks": [
    { "layer": 1, "extract": "human cry∞silence of creation", "text": "...", "importance": 0.9,
      "images": [{ "url": "https://…/l1.webp", "alt": "…", "credit": "…", "source": "https://…" }] },
    { "layer": 2, "extract": "Universe.amazed", "text": "...", "source_quote": "..." }
  ]
}

Assistants that speak MCP can use the library directly.

Set up the MCP server →