# Floyi API

> topic-first content strategy platform to build topical authority for SEO and AI search.
> This API provides programmatic access to brands, topical maps, content briefs, articles, topical authority data, and research.

## Authentication

All requests require an `X-API-Key` header. API keys are created in Settings > API Keys.
POST/PUT/PATCH requests also need `Content-Type: application/json`.

Base URL: `https://api.floyi.com/api/v1/`

## Docs

- [OpenAPI Schema (YAML)](https://api.floyi.com/api/v1/schema/)
- [Swagger UI](https://api.floyi.com/api/v1/docs/)
- [ReDoc](https://api.floyi.com/api/v1/redoc/)
- [Full LLM Reference](https://api.floyi.com/llms-full.txt)
- [Help Docs](https://floyi.com/help/api-keys)

## Endpoints

### User (scope: user:read)
- GET /api/v1/me/profile/ — User profile
- GET /api/v1/me/credits/ — Credit balance

### Brands (scope: brands:read, brands:write)
- GET /api/v1/brands/ — List brands (?search=)
- GET /api/v1/brands/{id}/ — Brand details
- POST /api/v1/brands/ — Create brand

### Topical Maps (scope: maps:read)
- GET /api/v1/maps/ — List maps (?brand_id=)
- GET /api/v1/maps/{brand_id}/ — Raw map clusters with keywords

### Briefs (scope: briefs:read, briefs:write)
- GET /api/v1/briefs/ — List briefs (?brand_id=, ?status=, ?search=)
- GET /api/v1/briefs/{id}/ — Brief details with result JSON
- GET /api/v1/briefs/{id}/status/ — Generation status
- POST /api/v1/briefs/generate/ — Generate brief (costs credits)

### Content Articles (scope: content:read, content:write)
- GET /api/v1/content/articles/ — List articles (?brand_id=, ?search=)
- GET /api/v1/content/articles/{id}/ — Article details
- GET /api/v1/content/articles/{id}/status/ — Generation progress
- POST /api/v1/content/articles/create-from-brief/ — Create from brief
- POST /api/v1/content/articles/{id}/generate/ — Generate draft (costs credits)

### Authority (scope: authority:read, authority:write)
- GET /api/v1/authority/ — List authority maps (?brand_id=)
- GET /api/v1/authority/{brand_id}/ — Enriched hierarchy with SERP + AI presence
- GET /api/v1/authority/{brand_id}/serp-data/{node_id}/ — SERP results for node
- PATCH /api/v1/authority/{brand_id}/nodes/{node_id}/published/ — Toggle published

### Research (scope: research:read, research:write)
- GET /api/v1/research/ — List research records
- GET /api/v1/research/{brand_id}/ — Full 4-level topic tree
- GET /api/v1/research/{brand_id}/stats/ — Tree statistics
- GET /api/v1/research/{brand_id}/task-status/ — AI generation task status
- PATCH /api/v1/research/{brand_id}/nodes/rename/ — Rename node
- POST /api/v1/research/{brand_id}/nodes/add/ — Add node
- POST /api/v1/research/{brand_id}/nodes/delete/ — Delete node
- PATCH /api/v1/research/{brand_id}/nodes/keywords/ — Add/remove keywords
- POST /api/v1/research/{brand_id}/nodes/move/ — Move node
- POST /api/v1/research/{brand_id}/nodes/merge/ — Merge nodes
- POST /api/v1/research/{brand_id}/nodes/bulk/ — Bulk operations
- POST /api/v1/research/{brand_id}/analyze/dedup/ — Semantic dedup
- POST /api/v1/research/{brand_id}/diff/ — Compare tree states

### Analytics (scope: admin:read — admin keys only)
- GET /api/v1/analytics/signups/ — Daily signup counts (?days=, ?period=)
- GET /api/v1/analytics/active-users/ — DAU/WAU/MAU
- GET /api/v1/analytics/subscriptions/ — Plan breakdown
- GET /api/v1/analytics/credits/ — Aggregate credit stats

## Permission Scopes

| Scope | Access |
|-------|--------|
| user:read | Profile, credits |
| brands:read | List/read brands |
| brands:write | Create brands |
| briefs:read | List/read briefs |
| briefs:write | Generate briefs |
| content:read | List/read articles |
| content:write | Create articles, generate drafts |
| maps:read | List/read topical maps |
| authority:read | Read authority hierarchy, SERP data |
| authority:write | Toggle published status |
| research:read | Read research trees, stats, diffs |
| research:write | Node CRUD, keywords, merge, dedup |
| admin:read | Admin analytics (staff only) |

## Rate Limits

| Key Type | Limit |
|----------|-------|
| Developer | 60/min |
| Integration | 120/min |
| Admin | 300/min |

## Errors

| Code | Meaning |
|------|---------|
| 401 | Invalid/expired/revoked API key |
| 402 | Insufficient credits |
| 403 | Missing required scope |
| 404 | Resource not found |
| 409 | Conflict (generation in progress, duplicate) |
| 429 | Rate limit exceeded |