3.2 KiB
API reference
The authoritative, always-current reference is the generated OpenAPI spec:
- Swagger UI —
http://localhost:8080/swagger-ui.html - Raw spec —
http://localhost:8080/v3/api-docs
The documents here add what a generated spec cannot: payload semantics, field meanings, worked examples and frontend integration notes. Where a document and the running service disagree, the service is correct — please fix the document.
Authentication
Every endpoint except health and public assets expects a JWT issued by the KonturAI auth service:
Authorization: Bearer <token>
This service validates the signature and reads the user id, email and roles from the claims; it does not issue tokens. See authentication.md.
Documents
| Document | Endpoints | Covers |
|---|---|---|
| authentication.md | — | Extracting user identity from the JWT |
| marketing-analysis.md | /api/marketing/analysis, /api/marketing/v3 |
Analysis generation and the full field reference |
| marketing-strategy.md | /api/marketing/analysis |
Promotion strategy generation |
| strategy-execution.md | /api/marketing/analysis |
Launching and tracking a strategy |
| posting-tasks.md | /api/marketing/analysis |
Scheduling and managing social posts |
| social-media-credentials.md | /api/social-media/credentials |
Storing per-user network credentials |
| image-generation.md | /api/marketing |
Generating post imagery |
| research-reports.md | /api/parser/report |
Research report generation and history |
| chart-rendering.md | — | Rendering chart JSON embedded in reports |
Endpoints without a dedicated document
Use Swagger UI for these:
| Base path | Controller | Purpose |
|---|---|---|
/api/parser/health |
HealthCheckController |
Liveness |
/api/parser/items |
MarketItemController |
Ingested news corpus |
/api/parser/admin/parsers |
ParserAdminController |
Trigger/inspect RSS parsers |
/api/targeting |
AiTargetingSystemController |
AI targeting recommendations |
/api/marketing/targeting |
TargetingCampaignController |
Campaign targeting |
/api/facebook/config |
FacebookConfigController |
Facebook app/page config |
/api/facebook/leads |
FacebookLeadsController |
Collected hot leads |
/api/facebook/webhook |
FacebookWebhookController |
Facebook webhook receiver |
/api/openai |
OpenAITestController |
OpenAI connectivity diagnostics |
Versioning
Marketing analysis exists in three generations — v1/v2 under /api/marketing/analysis
and v3 under /api/marketing/v3 — kept side by side so older frontend builds keep
working. v3 is the current path for new integrations.
Superseded revisions of these documents are preserved in ../archive/api-history/.
Errors
All errors are rendered by GlobalExceptionHandler, so the payload shape is consistent
across endpoints. Validation failures return 400 with per-field detail; a missing or
invalid token returns 401.