68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
# 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](authentication.md).
|
|
|
|
## Documents
|
|
|
|
| Document | Endpoints | Covers |
|
|
| --- | --- | --- |
|
|
| [authentication.md](authentication.md) | — | Extracting user identity from the JWT |
|
|
| [marketing-analysis.md](marketing-analysis.md) | `/api/marketing/analysis`, `/api/marketing/v3` | Analysis generation and the full field reference |
|
|
| [marketing-strategy.md](marketing-strategy.md) | `/api/marketing/analysis` | Promotion strategy generation |
|
|
| [strategy-execution.md](strategy-execution.md) | `/api/marketing/analysis` | Launching and tracking a strategy |
|
|
| [posting-tasks.md](posting-tasks.md) | `/api/marketing/analysis` | Scheduling and managing social posts |
|
|
| [social-media-credentials.md](social-media-credentials.md) | `/api/social-media/credentials` | Storing per-user network credentials |
|
|
| [image-generation.md](image-generation.md) | `/api/marketing` | Generating post imagery |
|
|
| [research-reports.md](research-reports.md) | `/api/parser/report` | Research report generation and history |
|
|
| [chart-rendering.md](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/](../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`.
|