🔌 OKF Wiki Builder API v1.0.0
A JSON API for other systems to drive this one — manage workspaces,
query knowledge, ingest documents, and run AI data extraction.
Base URL /api/v1. Machine-readable spec:
openapi.json.
Authentication
The API is currently open (no key required). To require one,
set OKF_API_KEY in .env and restart; callers then send
Authorization: Bearer <key> or X-API-Key: <key>.
Quick start
# health
curl http://127.0.0.1:5000/api/v1/health
# create a workspace
curl -X POST http://127.0.0.1:5000/api/v1/workspaces \
-H "Content-Type: application/json" \
-d '{"name":"Invoices","language":"English"}'
# run an extraction and wait for evidence-linked results
curl -X POST "http://127.0.0.1:5000/api/v1/workspaces/invoices/extractions/<def_id>/runs?wait=true" \
-H "Content-Type: application/json" \
-d '{"text":"Invoice No: INV-9\nTotal: $50"}'
Meta
| Method | Path | Summary | Params | Body |
|---|
| GET |
/api/v1/health |
Liveness + capability probe |
— |
— |
| GET |
/api/v1/openapi.json |
This OpenAPI document |
— |
— |
Workspaces
| Method | Path | Summary | Params | Body |
|---|
| GET |
/api/v1/workspaces |
List workspaces |
limit, offset |
— |
| POST |
/api/v1/workspaces |
Create a workspace |
— |
JSON |
| GET |
/api/v1/workspaces/{slug} |
Get a workspace + stats |
slug |
— |
| GET |
/api/v1/workspaces/{slug}/stats |
Workspace stats |
slug |
— |
| GET |
/api/v1/workspaces/{slug}/export.html |
The workspace as one self-contained printable HTML file (text/html) |
slug, download |
— |
Knowledge
| Method | Path | Summary | Params | Body |
|---|
| GET |
/api/v1/workspaces/{slug}/entities |
List entities |
slug, type, folder, q, limit, offset |
— |
| GET |
/api/v1/workspaces/{slug}/entities/{entity_id} |
Get one entity with facts + relationships |
slug, entity_id |
— |
| GET |
/api/v1/workspaces/{slug}/relationships |
List relationships |
slug, predicate, limit, offset |
— |
| GET |
/api/v1/workspaces/{slug}/predicates |
Relationship-type vocabulary |
slug |
— |
| GET |
/api/v1/workspaces/{slug}/search |
Full-text search |
slug, q, limit, offset |
— |
| GET |
/api/v1/workspaces/{slug}/timeline |
Timeline items |
slug |
— |
| GET |
/api/v1/workspaces/{slug}/graph |
Knowledge graph (nodes + edges) |
slug |
— |
| GET |
/api/v1/workspaces/{slug}/sources |
List ingested sources |
slug, limit, offset |
— |
| GET |
/api/v1/workspaces/{slug}/sources/{rel_path} |
Get one source (add ?include_content=1) |
slug, rel_path, include_content |
— |
Ingestion
| Method | Path | Summary | Params | Body |
|---|
| POST |
/api/v1/workspaces/{slug}/ingest |
Add sources (multipart files, or JSON {text}|{folder}) and build |
slug |
JSON |
| GET |
/api/v1/workspaces/{slug}/job |
Ingestion job status |
slug |
— |
| POST |
/api/v1/workspaces/{slug}/rebuild |
Re-render bundle from registry |
slug |
— |
Extraction
| Method | Path | Summary | Params | Body |
|---|
| GET |
/api/v1/workspaces/{slug}/extractions |
List extraction definitions |
slug, limit, offset |
— |
| POST |
/api/v1/workspaces/{slug}/extractions |
Create an extraction definition |
slug |
JSON |
| GET |
/api/v1/workspaces/{slug}/extractions/{def_id} |
Get a definition |
slug, def_id |
— |
| PUT |
/api/v1/workspaces/{slug}/extractions/{def_id} |
Update a definition (bumps version) |
slug, def_id |
JSON |
| DELETE |
/api/v1/workspaces/{slug}/extractions/{def_id} |
Delete a definition |
slug, def_id |
— |
| GET |
/api/v1/workspaces/{slug}/extractions/{def_id}/runs |
List runs for a definition |
slug, def_id, limit, offset |
— |
| POST |
/api/v1/workspaces/{slug}/extractions/{def_id}/runs |
Run extraction over documents (?wait=true to block for results) |
slug, def_id, wait, timeout, values_only |
JSON |
| GET |
/api/v1/workspaces/{slug}/runs |
List all runs |
slug, limit, offset |
— |
| GET |
/api/v1/workspaces/{slug}/runs/{run_id} |
Get a run's results + evidence (?values_only=1) |
slug, run_id, values_only |
— |
| POST |
/api/v1/workspaces/{slug}/runs/{run_id}/rerun |
Re-run with the same documents |
slug, run_id |
— |
Chat
| Method | Path | Summary | Params | Body |
|---|
| POST |
/api/v1/workspaces/{slug}/chat/ask |
Ask one grounded question; nothing is stored |
slug |
JSON |
| GET |
/api/v1/workspaces/{slug}/chat/conversations |
List conversations |
slug, limit, offset |
— |
| POST |
/api/v1/workspaces/{slug}/chat/conversations |
Start a conversation (a 'question' is answered in the same call) |
slug |
JSON |
| GET |
/api/v1/workspaces/{slug}/chat/conversations/{conv_id} |
Get a conversation with its messages |
slug, conv_id |
— |
| DELETE |
/api/v1/workspaces/{slug}/chat/conversations/{conv_id} |
Delete a conversation |
slug, conv_id |
— |
| POST |
/api/v1/workspaces/{slug}/chat/conversations/{conv_id}/messages |
Ask inside a conversation (history is carried) |
slug, conv_id |
JSON |
Collections return { "data": [...], "pagination": {...} };
single resources return the object directly; errors return
{ "error": { "code", "message" } } with the matching HTTP status.