Ask a legal question (streaming)

Stream an AI-generated answer to your legal question in real-time via Server-Sent Events (SSE). Provides thinking steps, source citations, and answer tokens as they are generated.

Authentication: API key via Authorization: Bearer vq_key_...

Content-Type: Response is text/event-stream. Set Accept: text/event-stream.

Event Types

Event	Description
stream_init	Stream opened — contains streamId
thinking	Pipeline progress step (analyzing, searching, generating)
sources	Retrieved source citations (same fields as sync /ask)
thinking_complete	Thinking done, answer streaming begins
chunk	Answer text token (concatenate all chunks for full answer)
heartbeat	Keep-alive signal (every 15s)
done	Stream complete — contains meta with credits and timing
error	Error occurred — contains message and code

Usage

const response = await fetch('/api/v1/ask/stream', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer vq_key_...',
    'Content-Type': 'application/json',
    'Accept': 'text/event-stream',
  },
  body: JSON.stringify({ question: 'What is negligence?', mode: 'standard' }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // Parse SSE events from text
  for (const line of text.split('\n')) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log(event.type, event);
    }
  }
}

Same modes, credit costs, source fields, and chatHistory support as POST /ask.

Example SSE Sequence

data: {"type":"stream_init","streamId":"abc-123"}

data: {"type":"thinking","step":{"id":"step_1","message":"Analyzing your question...","status":"active"}}

data: {"type":"sources","sources":[{"sourceIndex":1,"citation":"[2005] 6 S.C.R. 1","caseName":"Jacob Mathew v. State of Punjab","relevanceScore":0.94,...}]}

data: {"type":"thinking_complete"}

data: {"type":"chunk","content":"The test for"}
data: {"type":"chunk","content":" negligence requires"}
data: {"type":"chunk","content":" three essential elements..."}

data: {"type":"done","data":{"mode":"standard","meta":{"processingTimeMs":2340.5,"creditsConsumed":0.5,"creditsRemaining":4.5}}}

For more details, see the API Reference.

POST /api/v1/ask/stream

Ask a legal question (streaming)

cURL

curl --request POST \
  --url https://api.vaquill.ai/api/v1/ask/stream \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "<string>"
}
'

200

{
  "events": [
    {
      "type": "stream_init",
      "streamId": "abc-123"
    },
    {
      "type": "thinking",
      "step": {
        "id": "step_1",
        "message": "Analyzing your question...",
        "status": "active",
        "progress": 0.1
      }
    },
    {
      "type": "thinking",
      "step": {
        "id": "step_2",
        "message": "Searching 20M+ legal cases...",
        "status": "active",
        "progress": 0.3
      }
    },
    {
      "type": "sources",
      "count": 1,
      "sources": [
        {
          "sourceIndex": 1,
          "citation": "[2005] 6 S.C.R. 1",
          "caseName": "Jacob Mathew v. State of Punjab",
          "court": "Supreme Court of India",
          "year": 2005,
          "excerpt": "The three essential components of negligence are: duty, breach, and resulting damage...",
          "relevanceScore": 0.94,
          "judges": [
            "ARIJIT PASAYAT",
            "C.K. THAKKER"
          ],
          "decisionDate": "05-08-2005",
          "courtType": "supreme_court"
        }
      ]
    },
    {
      "type": "thinking_complete"
    },
    {
      "type": "chunk",
      "content": "The test for negligence under tort law in India follows "
    },
    {
      "type": "chunk",
      "content": "the principles established in Donoghue v. Stevenson..."
    },
    {
      "type": "done",
      "data": {
        "questionInterpreted": "What is qualified immunity?",
        "mode": "standard",
        "meta": {
          "processingTimeMs": 2340.5,
          "creditsConsumed": 0.5,
          "creditsRemaining": 4.5
        }
      }
    }
  ],
  "_note": "Each object above is delivered as a separate SSE `data:` line. Concatenate all `chunk` content tokens for the full answer."
}

Authorizations

Authorization · string · header · required

API key issued from the Vaquill developer dashboard. Pass as Authorization: Bearer vq_key_...

Body

application/json

Request body for the AI-powered legal Q&A endpoint.

question · string · required

Your legal question in plain language.

Required string length: 1 - 5000

Example:

"What is the test for negligence under tort law?"

mode · enum<string> · default: standard

Research depth. standard uses a fast model for quick answers. deep uses an advanced model for complex legal analysis.

Available options: standard, deep

Example:

"standard"

sources · boolean · default: true

Whether to include source citations in the response.

maxSources · integer · default: 5

Maximum number of source citations to return (1-30).

Required range: 1 <= x <= 30

Example:

5

countryCode · enum<string> | null

Jurisdiction. US for United States federal and state law, IN for Indian law. Defaults to US if omitted.

Available options: IN, US

Example:

"US"

sourcesFilter · enum<string> | null

Filter which sources to search. US only.

• all (default): Search both case law and statutes
• statutes_only: Search only USC/CFR statutes. Ideal for regulatory questions, compliance checks, and statutory interpretation. Faster and cheaper since it skips case law search.
• cases_only: Search only case law opinions. Useful for precedent research.

Available options: all, statutes_only, cases_only

Example:

"statutes_only"

usState · string | null

Optional US state code (2-letter ISO, e.g. tx, ca). When set and countryCode is US, retrieval is scoped to that state:

• Statutes: only that state's chunks in the statutes_us corpus (federal USC/CFR excluded).
• Case law: only opinions from that state's supreme + appellate courts (federal circuits and other states excluded).
• The model is instructed not to cite federal or other-state law unless explicitly asked.

Ignored when countryCode is not US.

Example:

"tx"

chatHistory · AskChatMessage · object[] | null

Previous conversation messages for multi-turn context. The system uses this to resolve references like 'that case' or 'compare it with Section 302'. Most recent messages last. Max 20 messages.

Maximum array length: 20

Show child attributes

Response

200

application/json

SSE event stream with thinking steps, sources, answer chunks, and metadata