OpenAPI 3.1 Spec

Peacock ships a machine-readable OpenAPI 3.1 specification you can plug into Postman, Stoplight, ReadMe, openapi-generator, and other tooling.

Endpoints

http

GET /v1/openapi.json    # JSON form
GET /v1/openapi.yaml    # YAML form (hand-rolled emitter — no symfony/yaml dep)
GET /openapi.json       # alias to /v1/openapi.json
GET /openapi.yaml       # alias to /v1/openapi.yaml

All four return the same spec. No auth, no rate limit (the spec itself doesn't change between deploys).

What's covered

The spec is auto-generated from Laravel routes by php artisan peacock:generate-openapi, with 14 hand-curated overrides where the auto-generator can't infer enough (response shapes, discriminated unions, etc.).

Total: 73 endpoints documented. Layout:

Section	Endpoints	Auth
Auth (`/v1/auth/*`)	4	none for register/login, sanctum for me/logout
Spaces (`/v1/spaces` + CRUD)	6	sanctum
Stories CRUD + workflow + bulk	18	sanctum + space.scope
Component blueprints	4	sanctum + space.scope
Assets + image transforms	5	mixed (uploads sanctum, reads anonymous)
AI Co-Pilot endpoints	8	sanctum + space.scope
Audience Segments + Variants	6	sanctum + space.scope
Datasources + sync + webhook	6	sanctum (CRUD) + anonymous-signed (webhook)
Plugins + rotate-secret + log	5	sanctum + space.scope
Public CDN (stories, search, assets, og.svg, beacon, graphql)	7	anonymous
Discovery (openapi, version, whoami)	4	mixed

Regenerating

When you add a new route, regenerate the spec:

bash

cd apps/api
php artisan peacock:generate-openapi
# Writes apps/api/storage/app/openapi.json

A commit-hook (Phase-17 polish) will auto-run this on push if any file in routes/api.php or app/Http/Controllers/Api/V1/* changed.

Using with `openapi-generator`

bash

# Generate a TypeScript client:
npx @openapitools/openapi-generator-cli generate \
  -i https://peacock-cms.webhoch.com/v1/openapi.json \
  -g typescript-fetch \
  -o ./peacock-client

# Generate a Python client:
openapi-generator-cli generate \
  -i https://peacock-cms.webhoch.com/v1/openapi.yaml \
  -g python \
  -o ./peacock-python-client

Using with Postman / Stoplight

Both accept the JSON URL directly:

Postman: Import → Link → paste https://peacock-cms.webhoch.com/v1/openapi.json
Stoplight: New Project → Import → OpenAPI 3.1 from URL

Anti-regression

OpenApiEndpointTest (PHPUnit) asserts both URLs return 200 and the parsed spec contains at least the 7 public CDN paths.

OpenAPI 3.1 Spec ​

Endpoints ​

What's covered ​

Regenerating ​

Using with openapi-generator ​

Using with Postman / Stoplight ​

Anti-regression ​

See also ​