Skip to content
Docs/API Reference
API REFERENCE

REST API

Social Inference Engine exposes a FastAPI-generated REST API with full OpenAPI 3.1 documentation. Browse the interactive Swagger UI at http://localhost:8000/docs when your instance is running.

Base URL: http://localhost:8000Auth: Bearer JWTRate limit: 60 req/min
Authentication: All endpoints except /health and POST /api/v1/auth/login require a valid JWT in the Authorization: Bearer <token> header. Tokens expire after 60 minutes. Use POST /api/v1/auth/refresh before expiry.

Authentication

POST/api/v1/auth/loginPublic

Exchange email + password for a JWT access token.

Request body / params
{ email, password }
Response schema
{ access_token, token_type, expires_in }
POST/api/v1/auth/refreshJWT required

Refresh an expiring access token.

Request body / params
Bearer token in header
Response schema
{ access_token, expires_in }

Signal Queue

GET/api/v1/signals/queueJWT required

Fetch the prioritised signal queue. Supports filtering by signal_type, priority_tier, min_urgency, page, limit.

Request body / params
Query params
Response schema
SignalQueueResponse
GET/api/v1/signals/streamJWT required

Server-Sent Events stream. Pushes new signals as they are classified. Pass token as ?token= query param.

Request body / params
token query param
Response schema
text/event-stream
GET/api/v1/signals/{id}JWT required

Fetch a single signal by ID including evidence spans, scores, and action history.

Request body / params
—
Response schema
SignalDetail
POST/api/v1/signals/{id}/actJWT required

Record an action on a signal (dm_outreach, reply_public, internal_alert, create_content, monitor, dismiss).

Request body / params
ActionPayload
Response schema
ActionResponse
POST/api/v1/signals/{id}/feedbackJWT required

Submit a classification correction. Triggers one calibrator gradient-descent step immediately.

Request body / params
FeedbackPayload
Response schema
{ updated: true }
POST/api/v1/signals/{id}/assignJWT required

Assign a signal to a specific analyst (MANAGER role required).

Request body / params
{ user_id }
Response schema
SignalDetail

Platform Connectors

GET/api/v1/connectorsJWT required

List all configured platform connectors and their status.

Request body / params
—
Response schema
ConnectorList
POST/api/v1/connectors/{name}/testJWT required

Trigger a test fetch for a specific connector and return the results.

Request body / params
—
Response schema
FetchResult

Calibration

GET/api/v1/calibration/stateJWT required

Return the current temperature scalar for each signal type.

Request body / params
—
Response schema
CalibrationState
POST/api/v1/calibration/resetJWT required

Reset all scalars to 1.0 (uncalibrated). MANAGER role required.

Request body / params
—
Response schema
{ reset: true }

Health

GET/healthPublic

Returns API, database, and Redis health. Excluded from rate limiting.

Request body / params
—
Response schema
{ status, database, redis, version }

Interactive Swagger UI

When your Social Inference Engine instance is running, browse the full interactive API documentation at:

http://localhost:8000/docs

The ReDoc alternative is available at http://localhost:8000/redoc