Quickstart

Five steps from zero to a cited answer. Replace https://api.your-host with your deployment’s base URL.

Creating a project is an administrative action and uses the operator’s admin credential. Everything after that uses the project API key returned in step 1. See Authentication.

1. Create a project

curl -X POST https://api.your-host/v1/projects \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "partner-acme"}'

The response contains a one-time api_key — store it securely; it is not retrievable again.

{ "id": "a40ccdf2-…", "name": "partner-acme", "api_key": "grag_…", "created_at": "…" }

2. Upload a document

curl -X POST https://api.your-host/v1/projects/$PROJECT_ID/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@handbook.pdf"

{ "document_id": "…", "job_id": "…", "status": "pending" }

3. Poll the ingestion job

Ingestion is asynchronous. Poll until the job reaches a terminal state.

curl https://api.your-host/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $API_KEY"
# status: queued → processing → succeeded   (or terminal_failed with an error_code)

4. Ask a question

curl -X POST https://api.your-host/v1/answer \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is the refund window?", "k": 6}'

{
  "answer": "Refunds are issued within 14 days [chunk:doc:…:3].",
  "citations": [{ "chunk_id": "…", "document_id": "…", "text": "…", "source": "retrieval" }],
  "graph_used": false
}

5. Or retrieve raw passages

Skip synthesis and get the ranked passages directly:

curl -X POST https://api.your-host/v1/search \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "refund window", "k": 6}'

That’s the whole loop. Next, understand what happens under the hood in Architecture.

← PreviousIntroduction Next →Architecture