OpenAI-compatible chat

Every agent is a model on Grounded's OpenAI-compatible API, named agent:<team>/<agent>: the team's slug and the agent's address. Point any OpenAI client at your install and use a team API key with the query scope.

• GET /v1/models lists the agents the key can use.
• POST /v1/chat/completions asks one, streamed or not.

The endpoint is stateless: transcripts are never stored. Send the conversation so far in messages; the last user message is the question.

A requestCopy Anchor Link

curl https://grounded.example.org/v1/chat/completions \
  -H "Authorization: Bearer $GROUNDED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent:admissions/student-help",
    "messages": [{"role": "user", "content": "How do I request a transcript?"}]
  }'

What's different from OpenAICopy Anchor Link

• model must be agent:<team>/<agent>.
• System messages from the client are dropped: the agent's own instructions win. The other messages are the history.
• tools and n greater than 1 are refused (400).
• Temperature, output length and other generation settings come from the agent, not the request.
• Errors use OpenAI's shape: {"error": {"message", "type", "code", "param"}}.

The responseCopy Anchor Link

A normal chat completion, plus two extension fields:

{
  "id": "…",
  "object": "chat.completion",
  "model": "agent:admissions/student-help",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Order an official transcript from the student portal [1]. Each copy costs $10 [2]." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 1830, "completion_tokens": 41, "total_tokens": 1871 },
  "citations": [
    { "n": 1, "title": "Transcripts", "snippet": "…", "headingPath": ["Records", "Transcripts"],
      "url": "https://example.org/records/transcripts", "documentId": "…", "sourceId": "…",
      "verification": "verified", "confidence": 0.97,
      "markers": [{ "verification": "verified", "confidence": 0.97 }] },
    { "n": 2, "title": "Fees", "snippet": "…", "headingPath": ["Fees"], "documentId": "…", "sourceId": "…",
      "verification": "unsupported", "confidence": 0.88,
      "markers": [{ "verification": "unsupported", "confidence": 0.88 }] }
  ],
  "claims": [
    { "index": 0, "start": 0, "end": 57, "text": "Order an official transcript from the student portal.",
      "verdict": "supported", "sources": [1], "confidence": 0.97,
      "checks": [{ "n": 1, "occurrence": 0, "verification": "verified", "confidence": 0.97 }] },
    { "index": 1, "start": 58, "end": 82, "text": "Each copy costs $10.",
      "verdict": "not_supported", "sources": [], "confidence": 0.88,
      "checks": [{ "n": 2, "occurrence": 0, "verification": "unsupported", "confidence": 0.88 }] }
  ]
}

(An illustrative response; values are made up.)

citationsCopy Anchor Link

The sources the answer's [n] markers refer to. Each has its number n, the document's title, a snippet of the passage (up to about 300 characters), its headingPath, pageStart and pageEnd for paginated documents, and documentId and sourceId. url is set only for web pages, when the agent's citation mode includes links; uploaded files are cited by title only.

With SystemOne citation checks on, each citation also has verification (verified, unsupported, contradicted or unchecked, the worst verdict of the claims that cite it), confidence, and markers: one verdict per [n] marker of this source, in order.

claimsCopy Anchor Link

Set when SystemOne citation checks are on for the agent. Each claim is one factual sentence of content (a list item or table row counts as one):

The app's summary line ("9 of 10 claims supported · 1 uncited") counts supported claims over supported, not supported and uncited ones. claims isn't set for refusals, when citations weren't checked, or when the agent doesn't cite. See Claims and verdicts for what counts as a claim.

In enforce mode, non-streamed answers are released after the check: unsupported markers are already removed from content, and a strictly grounded agent with nothing supported returns its refusal.

StreamingCopy Anchor Link

With "stream": true the reply is chat.completion.chunk events:

• delta.content carries the answer, and delta.reasoning_content a reasoning model's thinking when the model streams it.
• A final chunk has finish_reason and citations, and claims when checks are on. It's held until the citation check ends; streamed answers are annotated, never rewritten.
• With stream_options.include_usage, a usage chunk follows.
• Then data: [DONE].

curl -N https://grounded.example.org/v1/chat/completions \
  -H "Authorization: Bearer $GROUNDED_API_KEY" -H "Content-Type: application/json" \
  -d '{"model": "agent:admissions/student-help", "stream": true,
       "messages": [{"role": "user", "content": "How do I request a transcript?"}]}'

ErrorsCopy Anchor Link

Moderation that blocks a question returns the policy's notice as the answer. Each answer counts against the team's and the agent's query and chat limits, and the key's own rate limit.