API Reference

Base URL: http://localhost:8002 (local worker — the only supported deployment today). Status: Alpha. Surface area is broad but not contractually stable across releases. Last updated: 2026-09-28.

Jump to a group

Authentication

OAuth 2.1 Client Credentials grant. poindexter setup provisions the initial CLI client.

Tasks

Create, list, approve, and reject content tasks. The lifecycle is pending → in_progress → awaiting_approval.

Posts

Public post list + search, plus authenticated update / soft-delete.

Settings

Read and update app_settings rows over the REST surface.

Overview

Reference for the REST API exposed by the Poindexter worker. All routes are under /api/* — there is no URL-based versioning.

Stability warning. The API is not yet considered stable. Route shapes change between releases, especially around task metadata. Pin to a specific commit until the first tagged release.

API Principles

RESTful: Standard HTTP methods and status codes
JSON: All requests/responses in JSON format
Authentication: Bearer token in Authorization header
Pagination: Limit/offset for list endpoints

Authentication

OAuth 2.1 Client Credentials

All protected endpoints require an OAuth-issued JWT in the Authorization header:

curl -H "Authorization: Bearer <jwt>" \
     http://localhost:8002/api/tasks

poindexter setup provisions an initial CLI OAuth client on first run. Mint a fresh JWT for ad-hoc curl tests with:

poindexter auth mint-token \
  --client-id <pdx_xxx> --client-secret <secret>

Or POST against the token endpoint directly:

curl -X POST http://localhost:8002/token \
  -d grant_type=client_credentials \
  -d client_id=<pdx_xxx> \
  -d client_secret=<secret>

To register additional clients (brain daemon, MCP servers, scripts, OpenClaw, Grafana), run the matching poindexter auth migrate-* helper. The legacy static-Bearer fallback was removed in Glad-Labs/poindexter#249.

Development Bypass

When development_mode is true in app_settings, the literal token dev-token is accepted as a Bearer credential:

curl -H "Authorization: Bearer dev-token" \
     http://localhost:8002/api/tasks

Never enable development_mode in production. As of the 2026-04-25 rotation, development_mode=false by default — the bypass is dormant unless an operator explicitly flips the flag.

Public Endpoints (no auth required)

GET /api/health — system health
GET /api/posts — published post list
GET /api/posts/{slug} — single post by slug
GET /api/categories — category list
GET /api/posts/search?q=... — post search

Core Endpoints

System Health

GET `/api/health`

curl http://localhost:8002/api/health

Response (200 OK):

{
  "status": "healthy",
  "service": "cofounder-agent",
  "version": "0.5.0",
  "timestamp": "2026-05-23T10:30:00Z",
  "components": {
    "database": "healthy",
    "connection_pool": { "size": 5, "idle": 5 }
  }
}

(services/task_executor.py was deleted 2026-05-16 in the Prefect Stage 4 cutover; dispatch is now Prefect-native and there is no task_executor component in the health payload.)

Tasks

GET `/api/tasks`

List tasks (requires auth). Supports ?status=pending&limit=20&offset=0.

curl -H "Authorization: Bearer $TOKEN" \
     http://localhost:8002/api/tasks?status=awaiting_approval

POST `/api/tasks`

Create a content task.

curl -X POST http://localhost:8002/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"topic": "Why Docker changed everything", "category": "technology"}'

The task enters the pipeline automatically: pending → in_progress → awaiting_approval (or rejected if QA fails).

POST `/api/tasks/{task_id}/approve`

Approve a task for publishing. Publishes immediately unless publish_at is set.

# Publish now
curl -X POST http://localhost:8002/api/tasks/481/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved": true}'

# Schedule for later
curl -X POST http://localhost:8002/api/tasks/481/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approved": true, "publish_at": "2026-04-18T13:00:00Z"}'

POST `/api/tasks/{task_id}/reject`

Reject a task with feedback.

curl -X POST http://localhost:8002/api/tasks/481/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feedback": "Off-topic for the brand", "reason": "off-topic"}'

Posts

GET `/api/posts`

List published posts. Public (no auth).

GET `/api/posts/{slug}`

Get a single post by slug. Public.

GET `/api/posts/search?q={query}`

Search posts by title/content. Public.

Settings

GET `/api/settings`

List all app_settings (requires auth).

PUT `/api/settings/{key}`

Update a setting.

curl -X PUT http://localhost:8002/api/settings/auto_publish_threshold \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": "80"}'

Other Endpoints

Group	Method + Path	Auth	Purpose
Categories	`GET /api/categories`	public	List all content categories with post counts
Categories	`GET /api/categories/{slug}`	public	Single category metadata + posts
Posts	`GET /api/posts`	public	Paginated post list (status, category, limit, offset query)
Posts	`GET /api/posts/{slug}`	public	Single published post by slug
Posts	`GET /api/posts/search?q=...`	public	Full-text + pgvector similarity search
Posts	`GET /api/posts/preview/{preview_token}`	token	Draft preview as JSON, with its podcast/video availability
Posts	`PATCH /api/posts/{post_id}`	bearer	Update post metadata (title, tags, SEO fields)
Posts	`DELETE /api/posts/{post_id}`	bearer	Soft delete (archive) a post
Tags	`GET /api/tags`	public	List all tags with post counts
Memory	`GET /api/memory/search?q=...`	bearer	Semantic search via pgvector (top-k cosine similarity)
Memory	`GET /api/memory/stats`	bearer	Embedding counts by source_table / writer
Pipeline	`GET /api/pipeline/events`	bearer	Live event stream (recent task transitions, with pagination)
Pipeline	`GET /api/pipeline/events/task/{task_id}`	bearer	Event history for a single task
Analytics	`GET /api/analytics/views`	bearer	Page view rollups (day, post_id, geo if configured)
Export	`POST /api/export/rebuild`	bearer	Trigger static JSON + RSS rebuild to R2 / configured storage
Media	`GET /images/generated/{filename}`	public	Serve a generated image-gen / Pexels image
Media	`GET /api/podcast/episodes/{task_id}.mp3`	public	Stream the podcast MP3 a pipeline task rendered
Media	`POST /api/podcast/generate/{post_id}`	bearer	Render an episode for a published post (hand-written posts)
Subscribers	`GET /api/newsletter/subscribers/count`	bearer	Total opted-in newsletter subscribers
Subscribers	`POST /api/newsletter/subscribe`	public	Email and name only, no double opt-in; site signups use Resend
Subscribers	`POST /api/newsletter/unsubscribe`	public	One-click unsubscribe by token
Feeds	`GET /api/podcast/feed.xml`	public	Podcast RSS feed (Apple/Spotify compatible)
Feeds	`GET /api/video/feed.xml`	public	Video RSS feed; each enclosure is the approved video in storage
Webhooks	`POST /api/webhooks/alertmanager`	bearer	Prometheus Alertmanager webhook receiver (routes to Discord)
Frontend	`POST /api/revalidate-cache`	bearer	Trigger Next.js ISR cache revalidation after publish
Frontend	`GET /preview/{preview_token}`	token	Server-rendered draft preview (the operator’s review link)

Everything prefixed /api is the REST surface. Generated images (/images/generated/{filename}) and the server-rendered preview (/preview/{preview_token}) sit at the server root without the /api prefix. The posts RSS feed (/feed.xml) is served by the public site, not the worker. Video has no public list or stream endpoint. The video feed’s enclosures point at each approved video in object storage, and an operator streams a local render through the authenticated GET /api/media-approval/{post_id}/video/preview. The old /api/video/episodes list and stream routes were removed: they looked files up by post id, and renders are named by task id. The podcast feed likewise lists each approved episode with its URL in object storage, and an episode awaiting review streams through the authenticated GET /api/media-approval/{post_id}/podcast/preview. One podcast stream route remains: GET /api/podcast/episodes/{task_id}.mp3 serves the file a pipeline task rendered, which is how the operator console plays a podcast-type task. The GET /api/podcast/episodes list was removed for the same reason as the video routes. A preview reports a podcast or long-form video as ready once one is rendered for the post or its source task. It plays one only after it is approved and published to object storage: the same file the RSS feed serves. POST /api/newsletter/subscribe takes email plus optional first_name and last_name. It stores those, a verified flag and a fresh unsubscribe token, and mirrors the signup into the Resend segment when one is configured. It does not record the caller’s IP address or user-agent. The public site does not call it: site signups go to Resend, and the worker pulls them from there. company, interest_categories and marketing_consent were retired on 2026-09-28. Nothing read them, so the worker no longer stores them and their columns are gone. A request that still sends any of them succeeds as before. The fields are ignored, the OpenAPI schema marks them deprecated, and the response carries two headers:

Deprecation: true
Warning: 299 - "Ignored retired field(s): company, marketing_consent. Send only email, first_name and last_name."

The warning names only the retired fields that were actually sent. Drop them from the caller to clear it.

Webhook and preview-token security

POST /api/webhooks/alertmanager requires Authorization: Bearer <token>: either an OAuth JWT (mint one with poindexter auth mint-grafana-token) or the static token in app_settings.alertmanager_webhook_token. A missing or mismatched token is rejected with 401; with neither configured the route fails closed with 503. Preview tokens (/api/posts/preview/{token}, /preview/{token}) are random 32-character hex strings. The pipeline mints one per task and stores it in the task’s metadata; older posts carry one in posts.preview_token. The token is the only credential. It does not expire, and it can only read, never modify state.

Error Responses

{
  "error_code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "errors": { "feedback": "Field required" },
  "request_id": "3c158a96-..."
}

Common status codes: 400 validation, 401 missing/bad token, 404 not found, 500 server error.

Local Development Setup — full setup walkthrough
Troubleshooting — production issues and fixes

Catalogs

Service deep dives

API

Jump to a group

Authentication

Tasks

Posts

Settings

Overview

API Principles

Authentication

OAuth 2.1 Client Credentials

Development Bypass

Public Endpoints (no auth required)

Core Endpoints

System Health

GET `/api/health`

Tasks

GET `/api/tasks`

POST `/api/tasks`

POST `/api/tasks/{task_id}/approve`

POST `/api/tasks/{task_id}/reject`

Posts

GET `/api/posts`

GET `/api/posts/{slug}`

GET `/api/posts/search?q={query}`

Settings

GET `/api/settings`

PUT `/api/settings/{key}`

Other Endpoints

Webhook and preview-token security

Error Responses

​Jump to a group

Authentication

Tasks

Posts

Settings

​Overview

​API Principles

​Authentication

​OAuth 2.1 Client Credentials

​Development Bypass

​Public Endpoints (no auth required)

​Core Endpoints

​System Health

​GET /api/health

​Tasks

​GET /api/tasks

​POST /api/tasks

​POST /api/tasks/{task_id}/approve

​POST /api/tasks/{task_id}/reject

​Posts

​GET /api/posts

​GET /api/posts/{slug}

​GET /api/posts/search?q={query}

​Settings

​GET /api/settings

​PUT /api/settings/{key}

​Other Endpoints

​Newsletter signup payload

​Webhook and preview-token security

​Error Responses

​Related Documentation

Jump to a group

Overview

API Principles

Authentication

OAuth 2.1 Client Credentials

Development Bypass

Public Endpoints (no auth required)

Core Endpoints

System Health

GET `/api/health`

Tasks

GET `/api/tasks`

POST `/api/tasks`

POST `/api/tasks/{task_id}/approve`

POST `/api/tasks/{task_id}/reject`

Posts

GET `/api/posts`

GET `/api/posts/{slug}`

GET `/api/posts/search?q={query}`

Settings

GET `/api/settings`

PUT `/api/settings/{key}`

Other Endpoints

Newsletter signup payload

Webhook and preview-token security

Error Responses

Related Documentation