REST API reference

The SAG API is the self-hosted HTTP boundary for the complete product. Its default base URL is http://localhost:8000/api/v1. After starting an instance, use /docs for interactive OpenAPI documentation and /openapi.json for the machine-readable schema.

Authentication

Signing in with a local identity returns a JWT:

curl -s http://localhost:8000/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"name":"Developer"}'

Include it with most subsequent requests:

Authorization: Bearer <SAG_TOKEN>

POST /auth/register is controlled by SAG_ALLOW_REGISTRATION. The default local-identity onboarding does not depend on open email registration.

Resource map

Domain	Prefix	Primary capabilities
System	`/system`	health, ready, capabilities, model settings, and preferences
Identity	`/auth`	login, register, me
Sources	`/sources`	connectors, CRUD, synchronization, source chunks, and source MCP configuration
Documents	`/sources/{id}/documents`	upload, text ingestion, preview, parse output, pause, resume, reprocess, and delete
Jobs	`/jobs/{job_id}`	background-job state
Retrieval	`/search` and `/sources/{id}/search`	global or source-scoped vector/multi retrieval
Graph	`/sources/{id}/entities` and `/graph`	event-entity structure
Agents	`/agents`	Agents, bindings, conversations, messages, ask, and run cancellation
OpenAI	`/openai/{agent_id}/chat/completions`	Chat Completions compatibility and SSE
Knowledge Universe	`/universe`	manifest, expand, timeline, node detail, and exploration
MCP	`/mcp/`	Streamable HTTP knowledge tools

Create a source

curl -s -X POST http://localhost:8000/api/v1/sources \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Product docs",
    "description": "Product and API documentation",
    "connector_kind": "file_upload",
    "config": {}
  }'

The returned SourceOut includes the ID, status, document count, chunk count, event count, and timestamps.

Ingest text

Provide either text or messages:

curl -s -X POST \
  http://localhost:8000/api/v1/sources/<SOURCE_ID>/documents/ingest \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "SAG",
    "text": "SAG uses event-entity indexes and query-time dynamic hyperedges."
  }'

A background job continues processing. Wait for DocumentOut.status to become ready before expecting stable retrieval results.

Run retrieval

Global retrieval:

curl -s -X POST http://localhost:8000/api/v1/search \
  -H "Authorization: Bearer <SAG_TOKEN>" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "How does SAG retrieve knowledge?",
    "source_ids": ["<SOURCE_ID>"],
    "strategy": "multi",
    "top_k": 5,
    "save_exploration": false
  }'

Use POST /sources/{source_id}/search for retrieval within one source. Its request body does not need source_ids.

SearchRequest constraints

Field	Type	Constraint
`query`	string	1 to 4,000 characters
`strategy`	string	`vector` or `multi`; omit to use the default
`top_k`	integer	1 to 50
`source_ids`	string[]	Global endpoint only, up to 256 values
`save_exploration`	boolean	Global endpoint only; whether to save an exploration session

Health and readiness

GET /system/health means the HTTP process can respond.
GET /system/ready means critical dependencies are initialized and normal traffic can be accepted.
GET /system/capabilities returns the active knowledge engine and available capabilities.

Container health checks use the ready endpoint. Load balancers and orchestrators should also use ready before routing traffic.

Error handling

Validation errors use FastAPI/Pydantic structured responses. Background-processing errors are recorded in document and job state. SQL and local-storage details are sanitized at the API boundary; complete stack traces remain only in service logs.

When a custom frontend and API use different origins, add the frontend origin to SAG_CORS_ORIGINS. Do not combine * with credentialed requests to bypass configuration.