API Reference - Poindexter

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-05-23.

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	Preview a pre-publish post using a signed one-shot token
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 /episodes`	public	List all podcast episodes
Media	`GET /episodes/{post_id}.mp3`	public	Stream a podcast audio episode
Media	`GET /episodes/{post_id}.mp4`	public	Stream a podcast video episode
Media	`POST /generate/{post_id}`	bearer	Regenerate audio/video for a specific post
Subscribers	`GET /subscribers/count`	public	Total opted-in newsletter subscribers
Subscribers	`POST /subscribe`	public	Double opt-in newsletter signup (captcha recommended)
Subscribers	`POST /unsubscribe`	public	One-click unsubscribe by token
Feed	`GET /feed.xml`	public	RSS 2.0 feed of published posts
Webhooks	`POST /alertmanager`	signed	Prometheus Alertmanager webhook receiver (routes to Discord)
Frontend	`POST /revalidate-cache`	bearer	Trigger Next.js ISR cache revalidation after publish
Frontend	`GET /preview/{preview_token}`	token	Server-rendered preview HTML for vision-gate QA

Everything prefixed /api is the REST surface. Media routes (/episodes/*, /images/generated/*) and the RSS feed sit at the server root without the /api prefix to match classic web expectations.

Webhook security

POST /alertmanager verifies the Alertmanager webhook signature (HMAC-SHA256, shared secret in app_settings.alertmanager_webhook_secret). Invalid signatures are rejected with 401. Preview tokens (/api/posts/preview/{token}, /preview/{token}) are single-purpose signed tokens issued by the worker at post creation. They expire after 24 hours and can only be used to read — never to 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

​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 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

Webhook security

Error Responses

Related Documentation