DocumentationAPI
API
Our backend exposes a REST API powered by Django REST Framework (DRF), and a WebSocket API via Django Channels.
Auth
- Session Auth: Primarily used by the Next.js frontend during browser sessions.
- Token Auth: Supported for programmatic access.
Base Path
Because of the project-centric design, almost all resources are nested under:
/api/v1/projects/{project_id}/...
This enforces the strict scoping of data and prevents cross-project spillage.
Per-Resource Endpoint Table
| Resource | Path | Methods | Notes |
|---|---|---|---|
| Projects | /api/v1/projects/ | GET, POST | List projects you have membership in. |
| Content | /api/v1/projects/{pid}/content/ | GET, PATCH | Read ingested items. Patch is_relevant. |
| Entities | /api/v1/projects/{pid}/entities/ | GET, PATCH | Tracked entities over time. |
| Sources | /api/v1/projects/{pid}/sources/ | GET, POST, PATCH, DELETE | Configure plugin ingestion settings. |
| Members | /api/v1/projects/{pid}/members/ | GET, POST, DELETE | Invite users / manage roles. |
| Feedback | /api/v1/projects/{pid}/content/{cid}/feedback/ | POST | Submit upvote/downvote for topic centroid drift. |
Inbound Webhook
/api/v1/inbound/...
This surface is explicitly deliberately unscoped by project ID in the path because external systems (like Anymail handling Resend callbacks) do not know our internal project_id. The application code looks up the correct project using tokens or sender records.
Messaging
- REST Path:
/api/v1/messages/ - WebSocket Path:
/ws/messages/(Served via Django Channels / ASGI)
Pagination & Filtering
- Cursor-based or PageNumber pagination depending on the endpoint scale.
- Filtering standardizes on
django-filterparams (e.g.,?category=tutorial&min_relevance=0.8).
drf-spectacular Schema Link
A full OpenAPI V3 schema is auto-generated by drf-spectacular.
Available in dev at:
- Swagger UI:
/api/schema/swagger-ui/ - Raw YAML:
/api/schema/