Ask the assistant a question

Request

Use this to ask the HRC Ledger assistant one question and get its answer, the records it cites and what it read. Requires the agent:ask scope, which is separate from the read scopes because asking spends money. It does not stream, does not write and does not read the web. A run that stopped at a ceiling is a 200 carrying status: "partial" and a stopped_reason — an incomplete answer the caller can tell is incomplete, not an error. Bounded to 200 runs per key per UTC day.

Security

bearerKey

Bodyapplication/jsonrequired

questionstring, [ 8 .. 20000 ] charactersrequired

Trimmed before the bounds are applied. The same bounds the web surface enforces.

contractstring

Optional. The output contract the answer must take. Omitted resolves to general on the server and is never inferred from the question. An unknown value is a 422 naming the four, never a silent fallback.

Enum:"list""draft""actions""general"

skillstring

Deprecated, read for one release and only when contract is omitted: target_list and audience decode as list, answer as general, draft and general as themselves. Send contract instead. An unknown value is a 422.

Enum:"draft""target_list""audience""answer""general"

prior_run_idstring, [ 1 .. 24 ] characters

Optional. A prior run's public_id, when this question answers that run's clarifying question. Resolved with the caller's own key as viewer, so a public_id belonging to another account is a 404 not_found.

conversationstring^[A-Za-z0-9_-]{20,24}$

Optional. The conversation to append this question to, as returned in data.conversation.id. Omitted opens a new conversation. Resolved against the key's own account, so a conversation belonging to another account is a 404 not_found. The body never carries message content: the prior turns are rebuilt server-side, and a long thread is trimmed by the replay depth cap documented in docs/API.md.

time_zonestring

Optional. The asker's IANA time zone, which dates the run so relative dates such as last week resolve in the asker's calendar. An invalid value is never a 422: it is read as unknown, and the run assumes US Eastern (America/New_York) and says so. A zone saved on the key's account outranks this field, which is then only a fallback.

Example:"America/Chicago"

curl -i -X POST \
  https://docs.societyhealth.co/_mock/docs/openapi/api/v1/ask \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "Which Ohio hospitals changed EHR vendor this year?",
    "contract": "general"
  }'

Responses

The run's answer. status may be partial or failed.

Bodyapplication/json

okanyrequired

Value:true

dataobject(AskData)required

Response

{
  "ok": true,
  "data": {
    "run": { … },
    "conversation": { … },
    "answer": "Two Ohio hospitals posted an EHR replacement this year.",
    "citations": [ … ],
    "rows": [ … ],
    "coverage": { … },
    "usage": { … },
    "feedback": { … }
  }
}