# PostMagiq API Reference

## Authentication
- Header: `X-API-Key: qx_...`
- Get a key: sign up → subscribe to Pro → workspace settings → API Keys
- Rate limits: 60 requests/minute, 10,000/day (per key, configurable)
- Keys are scoped to a single workspace

## Base URL
https://postmagiq.com/api/v1/w/{workspace_id}

All endpoints below are relative to this base URL.

---

## Quick Posts
POST /quick-posts                        → create post { title, content_style, voice_profile_id, platform }

Content styles: thought_leadership, teach, audience, promote
Platforms: linkedin, x, threads, instagram, facebook, pinterest, reddit, bluesky, mastodon, discord, slack

Response: { post_id, post_number, status }

## Voice Profiles
GET  /voice/profiles                     → list presets + custom profiles
POST /voice/profiles                     → create custom profile { name, slug, tone_description, ... }
PUT  /voice/profiles/{id}                → update profile
POST /voice/profiles/{id}/clone          → clone preset to customize
DELETE /voice/profiles/{id}              → delete custom profile
POST /voice/samples                      → submit writing sample { content, source_type }
POST /voice/analyze                      → generate voice profile from samples
GET  /voice/samples                      → list submitted samples
GET  /voice/samples/status               → check if enough samples for analysis

## Workflow (Content Generation)
POST /workflow/execute                   → start writing pipeline { story, content, post_id }
GET  /workflow/status?run_id={id}        → check run progress { running, current_state, awaiting_approval }
GET  /workflow/active                    → list active runs
POST /workflow/approve                   → approve/provide feedback { run_id, decision, feedback }
POST /workflow/abort                     → cancel running workflow { run_id }
GET  /workflow/posts/{post_id}/latest-run → get latest run + outputs for a post

Pipeline stages: story_processor → writer → style_auditor → fabrication_auditor → ai_detector → synthesizer → final_audit
Each stage has quality gates. The workflow auto-retries on low scores.

## Runs (History)
GET  /runs                               → list all runs
GET  /runs/{run_id}                      → run details { status, total_cost_usd, credits, final_state }
GET  /runs/{run_id}/outputs              → all outputs (drafts, audits, final)
GET  /runs/{run_id}/states               → state transition log
GET  /runs/{run_id}/tokens               → token usage breakdown by agent/state
GET  /runs/{run_id}/summary              → markdown summary

## Finished Posts
GET  /finished-posts                     → list finished posts with content
POST /finished-posts/{post_id}/edit      → edit content { content, edit_note }
GET  /finished-posts/{post_id}/edits     → list edit history

## Publishing
POST /publish/{connection_id}            → publish immediately { post_id }
POST /schedule                           → schedule for later { post_id, connection_id, scheduled_for }
GET  /scheduled                          → list scheduled posts
POST /scheduled/{id}/cancel              → cancel scheduled post
POST /scheduled/{id}/reschedule          → reschedule { scheduled_for }

## API Keys (requires workspace:settings scope)
POST /api-keys                           → create key { name, description, scopes } → returns full key once
GET  /api-keys                           → list keys (prefix only)
DELETE /api-keys/{id}                    → revoke key

## Billing & Credits
GET  /billing/usage                      → credits remaining, limits, tier info
GET  /billing/tiers                      → list subscription tiers and pricing

## Webhooks
POST /webhooks                           → create { url, events, name }
GET  /webhooks                           → list webhooks
GET  /webhooks/{id}/deliveries           → delivery history
POST /webhooks/{id}/test                 → send test event
DELETE /webhooks/{id}                    → delete webhook
POST /webhooks/{id}/rotate-secret        → rotate signing secret

## Webhook Event Types
- post.created, post.updated, post.published, post.deleted
- workflow.started, workflow.completed, workflow.failed
- approval.requested, approval.approved, approval.rejected

## Error Codes
- 401: Invalid or missing API key
- 402: Insufficient credits
- 403: Scope not granted on API key, feature requires higher tier, or tier downgraded
- 404: Resource not found
- 429: Rate limit exceeded (check Retry-After header and X-RateLimit-* headers)

## Rate Limit Headers
Every API key response includes:
- X-RateLimit-Limit-Minute: 60
- X-RateLimit-Limit-Day: 10000
- X-RateLimit-Remaining-Minute: N
- X-RateLimit-Remaining-Day: N

## Typical Agent Workflow
1. GET /voice/profiles → pick a voice profile ID
2. POST /quick-posts → create post with { title, content_style, voice_profile_id, platform }
3. POST /workflow/execute → start pipeline with { post_id, content: "raw source material" }
4. Poll GET /workflow/status?run_id={id} until running=false
5. If awaiting_approval=true → POST /workflow/approve { run_id, decision: "approved" }
6. GET /runs/{run_id}/outputs → get final content
7. GET /finished-posts → retrieve polished output
8. POST /publish/{connection_id} → publish to platform