Skip to main content

​
Chat API

The Chat API runs retrieval over your indexed sources (and optional package scope), then generates an answer with citations. Use POST /chat for a single JSON response, or POST /chat/stream for Server-Sent Events (event: token, event: done, event: error).

​
Endpoints

POST /chat
POST /chat/stream
POST /chat/upload-pdf

​
Request (POST /chat)

​
query
string
required
The question to ask the Ground Agent
​
conversation_id
string
Optional. When authenticated via JWT (dashboard), continues an existing conversation.
​
top_k
integer
default:"5"
Number of sources to use as context (1-10)
​
max_context_tokens
integer
default:"4000"
Maximum tokens for context window
​
include_global
boolean
default:"true"
Include pre-indexed global packages in search
​
source_ids
string[]
Optional. Restrict retrieval to specific source IDs (e.g. “talk to one repo”).
​
scope
string
Optional. Use ground_docs to limit to Ground’s own documentation source when enabled.

​
Streaming (POST /chat/stream)

Same fields as above, plus optional package_mentions (for example [{"package_name":"react","ecosystem":"npm"}]) to blend in on-demand package context. Consume the SSE stream in your client; the done event includes citations, timing, and conversation_id when persisted.

​
PDF context (POST /chat/upload-pdf)

Multipart form: file (PDF) and conversation_id. Requires JWT auth matching the conversation. Chunks are stored for ephemeral retrieval during that conversation’s chat turns.

​
Response

​
answer
string
AI-generated answer based on Ground’s indexed documentation
​
citations
array
List of sources used to generate the answer
​
search_time_ms
number
Time taken to search Ground’s index
​
completion_time_ms
number
Time taken for AI to generate answer
​
total_time_ms
number
Total response time
​
model_used
string
AI model used (e.g., “gpt-4o”)

​
Example

curl -X POST https://api.trygroundai.com/chat \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I use React hooks for state management?",
    "top_k": 5
  }'

​
Response Example

{
  "answer": "React hooks like `useState` and `useReducer` are used for state management...",
  "citations": [
    {
      "source_name": "NPM: react",
      "content": "useState is a Hook that lets you add React state to function components...",
      "score": 0.95,
      "path": "react/index.d.ts"
    },
    {
      "source_name": "NPM: jotai",
      "content": "Primitive and flexible state management for React...",
      "score": 0.89,
      "path": "jotai/package.json"
    }
  ],
  "search_time_ms": 84.5,
  "completion_time_ms": 3200.0,
  "total_time_ms": 3284.5,
  "model_used": "gpt-4o"
}

​
Notes

  • API key requests work for core Q&A; conversation persistence uses JWT (dashboard) with /conversations APIs.
  • Model id and latency depend on your deployment’s Azure / LLM configuration.

Citations

Answers include source names, paths, and excerpts you can verify in the repo or doc.

Streaming

Use /chat/stream for token-by-token UX in custom clients.

Package scope

Combine indexed sources with on-demand package context where the API supports it.

PDF uploads

Attach PDFs per conversation for short-lived context (JWT).