Q&A endpoint

Books support a question-and-answer endpoint: you send a question about a book, and bkstr streams back an answer grounded in that book's content. Skills do not have this endpoint — they ship as installable file bundles, not as queryable text.

This is an advanced surface. For most uses, installing the book and letting your agent read it directly is the simpler path — see Installing.

POST /api/agent/fetch

The endpoint takes a book identifier and a natural-language query, and streams the answer back.

curl -N -X POST https://bkstr.tmrwgroup.ai/api/agent/fetch \
  -H "Authorization: Bearer $BKSTR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "book_id": "<book-id>",
    "query": "What does the manual say about test control?"
  }'

It authenticates with a bks_ Bearer key — the same key the rest of the API uses. Create one at /dashboard/api-keys.

The request body is JSON:

• book_id — the book's id. Required.
• query — your question, up to 8000 characters. Required.

The response

The answer streams back as server-sent events; curl -N keeps the stream open:

• event: chunk — one piece of the answer. Concatenate the chunks in order.
• event: done — the stream is complete; the payload carries token counts and latency.
• event: error — a failure that happened mid-stream.

An error that happens before the stream starts comes back as a normal JSON response with a 4xx or 5xx status instead.

The answer is generated by a language model that is given the book's text and instructed to answer only from it — if the book does not cover the question, the answer says so rather than inventing one. Because a model generates each answer, expect a response to take a few seconds.

Every call is recorded in your fetch logs with a timestamp, the book queried, and the answer's size.