Citations

⚠️

Preview — this feature is being built; the design below is the spec.

With citations turned on, the model points each claim in its answer back to the exact passage in your documents that supports it. Your app can show the quote, link to the page, or highlight the source, and reviewers can check the answer without rereading the whole document.

When to use it

Legal, finance, health and support answers where users need to verify.
Search and knowledge-base assistants (pass your search snippets as documents).
Any answer built from web search or web fetch; both add citations on their own.

Endpoint and auth

POST https://app.syntic.ai/v1/chat/completions or Messages, Authorization: Bearer sk_live_....

Request fields

Turn citations on per document:

Where	Field	Details
`file` content part	`file.citations`	`{"enabled": true}`
`text_document` content part	`text_document.text`, `text_document.title`, `text_document.citations`	Plain text you supply, for example a search result.
`text_document` content part	`text_document.chunks`	Optional array of strings. When given, citations refer to chunk numbers instead of character ranges.

All documents in one request must either all enable citations or all leave them off; mixing returns 400.

Response

The answer text is unchanged. Each cited span is listed in message.annotations:

{
  "message": {
    "role": "assistant",
    "content": "Either party may end the lease after year three with six months' notice.",
    "annotations": [
      {
        "type": "citation",
        "start_index": 0,
        "end_index": 72,
        "source": { "document_index": 0, "file_id": "file_01JBW9Q6RZ", "title": "Shop lease 2024" },
        "location": { "type": "page", "start_page": 7, "end_page": 7 },
        "quote": "either the Landlord or the Tenant may terminate this Lease on giving not less than six months' written notice"
      }
    ]
  }
}

Field	Description
`start_index`, `end_index`	Character range in `content` the citation supports.
`source.document_index`	Position of the document among all cited documents in the request, from 0.
`source.file_id` / `source.title` / `source.url`	Whichever applies.
`location.type`	`page` (PDF), `char` (plain text) or `chunk`.
`location.start_page`, `end_page`	1-based pages for `page`.
`location.start_char`, `end_char`	0-based characters for `char`.
`location.start_chunk`, `end_chunk`	0-based chunk numbers for `chunk`.
`quote`	The exact source text. Always copied from the document, never written by the model.

Quotes do not count as output tokens. On Messages, citations are attached to each text block instead of a separate list.

Streaming

Citations arrive as their own delta right after the text they support:

data: {"choices":[{"index":0,"delta":{"annotations":[{"type":"citation","start_index":0,"end_index":72,"...":"..."}]}}]}

Examples

curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "messages": [{
      "role": "user",
      "content": [
        { "type": "text_document", "text_document": {
            "title": "Returns policy",
            "text": "Items can be returned within 30 days. Plants must be unopened. Refunds take 5 working days.",
            "citations": { "enabled": true } } },
        { "type": "text", "text": "Can I return a plant I have repotted?" }
      ]
    }]
  }'

const data = await (await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    messages: [{
      role: 'user',
      content: [
        { type: 'file', file: { file_id: 'file_01JBW9Q6RZ', citations: { enabled: true } } },
        { type: 'text', text: 'Can the tenant leave early?' },
      ],
    }],
  }),
})).json()
 
const msg = data.choices[0].message
for (const a of msg.annotations ?? []) {
  console.log(`"${msg.content.slice(a.start_index, a.end_index)}" <- p.${a.location.start_page}: ${a.quote}`)
}

import os, requests
 
data = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json={
        "model": "Amara S1.2",
        "stream": False,
        "messages": [{
            "role": "user",
            "content": [
                {"type": "file", "file": {"file_id": "file_01JBW9Q6RZ", "citations": {"enabled": True}}},
                {"type": "text", "text": "Can the tenant leave early?"},
            ],
        }],
    },
    timeout=120,
).json()
 
msg = data["choices"][0]["message"]
for a in msg.get("annotations", []):
    print(msg["content"][a["start_index"]:a["end_index"]], "<-", a["quote"])

Errors

Unified envelope.

Status	`code`	Cause
400	`citations_mixed`	Some documents enable citations and some do not.
400	`citations_not_supported`	The model does not support citations.
400	`citations_with_json_output`	Citations cannot be combined with `response_format` `json_schema`.

Limits and cost

Up to 20 cited documents per request.
Turning citations on adds a small amount of input (document markers), usually under 2% of the document’s tokens.
Scanned PDFs without a text layer cite by page only.

Build notes for the platform team

Phase 1: text_document with chunks (caller-supplied search snippets). Phase 2: files with page and character ranges.
The quote is filled in by the server from the source span, so it can never be invented. Drop any citation whose span cannot be resolved.

Files API Search result blocks

Was this page helpful?