Ask a legal question

Ask a legal question in plain language and get an AI answer grounded in real court judgments from 20M+ cases. Standard and deep research modes.

POST /api/v1/ask

Ask a legal question

cURL

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

200

{
  "data": {
    "answer": "Qualified immunity shields government officials from damages liability unless they violated a clearly established constitutional right [1]. The doctrine asks two questions:\n\n1. **Constitutional violation**: Did the plaintiff allege deprivation of a constitutional right?\n2. **Clearly established**: Was the right clearly established at the time of the alleged misconduct? [2]\n\nThe standard protects 'all but the plainly incompetent or those who knowingly violate the law.' [1]",
    "sources": [
      {
        "sourceIndex": 1,
        "citation": "457 U.S. 800",
        "caseName": "Harlow v. Fitzgerald",
        "court": "Supreme Court of the United States",
        "year": 1982,
        "excerpt": "Government officials performing discretionary functions generally are shielded from liability...",
        "relevanceScore": 0.94,
        "judges": [
          "Powell"
        ],
        "decisionDate": "1982-06-24",
        "pdfUrl": "https://www.supremecourt.gov/opinions/81pdf/80-945.pdf",
        "disposition": "Published",
        "citeCount": 22742,
        "docketNumber": "80-945",
        "sourceType": "us_case",
        "externalUrl": "https://app.vaquill.ai/research/cases/110787"
      },
      {
        "sourceIndex": 2,
        "citation": "17 C.F.R. § 240.10b5-1 (2026)",
        "caseName": "Trading on the basis of material nonpublic information",
        "year": 2026,
        "excerpt": "A purchase or sale of a security is 'on the basis of' material nonpublic information...",
        "relevanceScore": 0.87,
        "sourceType": "us_statute",
        "corpusType": "CFR",
        "htmlUrl": "https://statutes-us.vaquill.ai/ecfr/html/2026-04-14/title-17/section-240.10b5-1.html",
        "statutePdfUrl": "https://statutes-us.vaquill.ai/ecfr/pdf/title-17/section-240.10b5-1.pdf",
        "govInfoPdfUrl": "https://www.govinfo.gov/content/pkg/CFR-2025-title17/pdf/CFR-2025-title17-sec240-10b5-1.pdf",
        "externalUrl": "https://www.ecfr.gov/current/title-17/section-240.10b5-1",
        "pageStart": 5,
        "pageEnd": 7,
        "charStart": 6424,
        "charEnd": 10119
      }
    ],
    "questionInterpreted": "What is qualified immunity?",
    "mode": "standard"
  },
  "meta": {
    "processingTimeMs": 2340.5,
    "creditsConsumed": 0.5,
    "creditsRemaining": 4.5
  }
}

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

AI-generated answer with source citations

Top-level response for the Ask endpoint.

data · AskData · object · required

The answer and supporting sources.

Show child attributes

meta · AskMeta · object · required

Request metadata and credit usage.

Show child attributes