# 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`.