Citations

When you make an explainer through the API from your own files, you can have the narration cite them. Each spoken line then records which part of which file it teaches from, and you read that back as data.

Use it to show the source beside the video, to check the lesson against the file it came from, or to link a sentence of narration to the exact lines it describes.

Turning citations on

Send cite_attachments: true with the create request, along with at least one text attachment. The explainer is written with the citations in place; nothing on its page changes.

curl -s "$SCRIMBA/api/v1/explainers" \
  -H "Authorization: Bearer $SCRIMBA_KEY" \
  -F "prompt=Walk through how this handler checks the token" \
  -F "cite_attachments=true" \
  -F "[email protected]"

Only text and code files are cited, never pictures or PDFs. Without cite_attachments, the explainer is made as usual and every citation list is empty. A value that isn't true or false answers 400 invalid_cite_attachments.

Reading them back

Once the explainer is ready, GET /api/v1/explainers/:id/transcript returns the narration as a list of entries, one per spoken passage in playback order. Each entry carries its citations under references.

{
  "index": 3,
  "slide": 2,
  "title": "Checking the token",
  "text": "The handler reads the token from the header, then compares it to the stored secret.",
  "references": [
    {
      "text": "reads the token from the header",
      "text_start": 12,
      "text_end": 43,
      "attachment": 1,
      "offset": 412,
      "length": 39,
      "lines": [10, 10],
      "cited_text": "const token = req.headers.authorization"
    }
  ]
}

A citation ties words of the narration to a part of a file:

• text, text_start and text_end are the words of the entry the citation supports, and where they sit in the entry's text.
• attachment is the file, by the ref number the explainer object lists under attachments.
• offset, length, lines and cited_text are the cited part of that file: its place in characters, its first and last line counted from 1, and the text itself.

While the explainer is still generating, or after it failed, the endpoint answers 409 not_ready.

What to expect

The model decides what to cite. It cites the sentence, value or passage a point comes from, the smallest useful part, and a passage can carry several citations into one file or several. A line that teaches nothing from the files has none.

• text_start and text_end are null when the narration doesn't speak the cited words exactly as written, so match on text yourself in that case.
• A text file is read up to 30,000 characters, and offset counts within what was read.
• A citation whose quoted part isn't found in the file is left out.

For the field-by-field reference, see The Explainer API.