API reference · Query

Ask

POST/v1/ask

A question in plain words, answered from cited items by the deterministic grammar and templates, or a typed abstention. With Accept text/event-stream the plan streams first.

scope: read
auth: Bearer key
operationId: Ask
MCP tool: ask

Request body

application/json · AskRequest · no other fields

Request body fields
Field	Type	Required	Limits	Holds
question	string	yes	1 to 2000 characters
max_age_seconds	integer	no	1 to 315360000
mode	strict · standard · broad	no		Which items could be served. Each mode returns everything the one before it does.

Response

200 · AskResponse. An answer, a partial answer, or typed abstentions. As server-sent events: plan, then items, answer.delta, and done, or abstained; error carries a problem.

Response fields
Field	Type	Holds
response_id	ResponseID	A response's ID. It replays and compares that exact response.
status	answered · partial · abstained	Whether there is an answer.
as_of	AsOf	When the answer applies (valid_at), and what the record held then (known_at).
mode	strict · standard · broad	Which items could be served. Each mode returns everything the one before it does.
preset	string · nullable	The key's preset, if any.
items	Item[]	The cited facts.
abstentions	Abstention[]	Why part of the question has no answer.
negative_results	NegativeResult[]	What was searched, and found nothing.
withheld	Withheld[]	Items left out, by reason and count.
attributions	Attribution[]	Text to repeat where you show the data.
meta	Meta	The policy version, the index versions, and the milliseconds the server took.
plan	Plan	What the question was parsed into, with each list's resolution of the subject. A refusal is the detail code of the abstention a question gets without running.
answer	Answer	Sentences, each citing fact version IDs; the method, template, and models.
events	Event[]	Events the answer cites.

Rate-limit headers

RateLimit-Limit: The bucket's size.
RateLimit-Remaining: Tokens left in it.
RateLimit-Reset: Seconds until it is full.

Problems

RFC 9457 application/problem+json. An abstention is not one of these: it is a 200.

Problems
HTTP	Code	When
400	INVALID_REQUEST	Malformed JSON, unknown fields, bad filter, limit exceeded
401	UNAUTHENTICATED	Missing, malformed, or revoked key
403	FORBIDDEN_SCOPE	The key lacks the required scope
413	PAYLOAD_TOO_LARGE	Body or upload over the limit
429	RATE_LIMITED	Rate limit or per-tenant model cap
500	INTERNAL, POLICY_ASSERT_FAILED, RESPONSE_UNREPLAYABLE	Server fault. The last two also alert
503	STORE_UNAVAILABLE, LLM_UNAVAILABLE, LOG_UNAVAILABLE	A dependency is down or a budget tripped
504	TIMEOUT	A deadline was exceeded

Sample

Request

POST /v1/ask
Content-Type: application/json

{
  "question": "Is OFAC UID 3751 sanctioned?",
  "mode": "standard"
}

Sample response · GET /v1/samples/ask

{
  "abstentions": [],
  "answer": {
    "method": "template",
    "models": [],
    "sentences": [
      {
        "fact_version_ids": [
          "fv_06GR5VVHQHSDX77J2HD9CC6QH4"
        ],
        "text": "MOA NICKEL SA is listed on SDN List (OFAC Sanctions List Service (SDN and Consolidated non-SDN lists))."
      },
      {
        "fact_version_ids": [
          "fv_06GR5VVHQHTW9CFS9DCX9R3YX4"
        ],
        "text": "MOA NICKEL SA is listed under program CUBA on SDN List."
      },
      {
        "fact_version_ids": [
          "fv_06GR5VVHQHWAQATR0FWRTCDXKM"
        ],
        "text": "MOA NICKEL SA is listed under program CUBA-EO14404 on SDN List."
      }
    ],
    "template": "templates/v1"
  },
  "as_of": {
    "known_at": "2026-10-28T14:34:53.191177Z",
    "valid_at": "2026-10-28T14:34:53.191177Z"
  },
  "attributions": [
    {
      "source_id": "ofac_sls",
      "text": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service"
    }
  ],
  "events": [],
  "items": [
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHSDX77J2HD9CC6QH4",
      "field": "sanctions.listing_status",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "1995-05-23T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "status": "listed",
        "measures": [
          "Block"
        ],
        "legal_bases": [
          "Cuban Assets Control Regulations (CACR)",
          "Executive Order 14404 (Cuba)"
        ]
      }
    },
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHTW9CFS9DCX9R3YX4",
      "field": "sanctions.program",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "2026-10-21T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "program": "CUBA"
      }
    },
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHWAQATR0FWRTCDXKM",
      "field": "sanctions.program",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "2026-10-21T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "program": "CUBA-EO14404"
      }
    }
  ],
  "meta": {
    "index_versions": {
      "ofac_sls": "01a182ef-71a0-7861-9595-c4ecfc82ba02"
    },
    "policy_version": 1,
    "server_ms": 2
  },
  "mode": "standard",
  "negative_results": [],
  "plan": {
    "grammar": "grammar/v1",
    "question": "Is OFAC UID 3751 sanctioned",
    "intent": "sanctions_status",
    "operation": "fetch",
    "subject": {
      "identifier": {
        "scheme": "ofac_uid",
        "value": "3751"
      }
    },
    "fields": [
      "sanctions.listing_status",
      "sanctions.program"
    ],
    "time": {
      "phrase": "",
      "kind": "now",
      "valid_at": null,
      "since": null
    },
    "lists": [
      {
        "source_id": "ofac_sls",
        "outcome": "resolved",
        "selection": "single",
        "entity_id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "candidates": [
          {
            "entity_id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
            "name": "MOA NICKEL SA",
            "score": 1,
            "matched_on": ""
          }
        ]
      }
    ]
  },
  "preset": null,
  "response_id": "resp_06GR5VVKH9TSQAMANY5B2VQ7R4",
  "status": "answered",
  "withheld": []
}