🔌 API Reference

The implemented API is same-origin JSON plus multipart upload and server-sent events. Handlers return { error: string } with a real non-2xx status on failure. A successful route does not fabricate success data when the underlying operation fails.

Identity

GET /api/me

• source:
  • Authelia injected remote-user header
• response:
  • { id, username }
• test-only policy:
  • X-Pwiz-Test-User is accepted only when PWIZ_ALLOW_TEST_IDENTITY=1 and the request originates from loopback
  • production requires the Authelia-injected Remote-User header

Collections

GET /api/collections/:name?filter=<json>

• names:
  • wizards
  • blueprints
  • prompt_history
  • saved_prompts
  • likes
  • admin_prompts
  • llm_logs
• response:
  • newest-first array
• filter:
  • URL-encoded JSON object
  • equality only
  • allowed indexed keys:
    • is_public
    • user_id
    • blueprint_id
    • key
  • unknown key: 400

POST /api/collections/:name

• request:
  • JSON row payload
• server-owned fields:
  • id
  • created_at
  • applicable user_id
• response:
  • created row
• event:
  • broadcasts affected collection

PATCH /api/collections/:name/:id

• request:
  • partial JSON patch
• response:
  • updated row or mutation result
• event:
  • broadcasts affected collection

DELETE /api/collections/:name/:id

• response:
  • success object or empty success response
• event:
  • broadcasts affected collection

Likes

POST /api/likes/toggle

• request:
  • { blueprint_id }
• transaction:
  • if not liked, insert like row and increment blueprint count
  • if liked, delete like row and decrement blueprint count
• response:
  • { liked: boolean, likes_count: number }
• events:
  • broadcasts likes
  • broadcasts blueprints

Uploads

POST /api/uploads

• request:
  • multipart form-data
  • field: file
• accepted types:
  • image/png
  • image/jpeg
  • image/webp
• maximum size:
  • 8 MB
• write target:
  • data/uploads/<uuid>.<ext>
• response:
  • { url: "/uploads/<uuid>.<ext>" }

AI text

POST /api/ai/text

• request:
  • { system, messages, json, kind, templateKey }
• response:
  • { content }
• behavior:
  • calls ompText
  • stores server-side llm_logs row
  • JSON mode retries once on invalid JSON
• errors:
  • 400 for invalid request
  • 502 for generation failure or invalid JSON after retry
  • 504 for timeout

See omp-integration for command details.

AI image

POST /api/ai/image

• request:
  • { subject, aspectRatio, kind }
• response:
  • { url, provider, model }
• behavior:
  • calls ompImage
  • copies generated WebP into uploads
  • stores server-side llm_logs row
• accepted aspect ratios:
  • 1:1
  • 3:4
  • 4:3
  • 9:16
  • 16:9
• errors:
  • 400 for invalid subject or aspect ratio
  • 502 for tool failure or missing image event
  • 504 for timeout

Client errors

POST /api/errors

• request:
  • { type, message, stack }
• server action:
  • log with client prefix
• response:
  • 204

Events

GET /api/events

• protocol:
  • server-sent events
• headers:
  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • X-Accel-Buffering: no
• event payload:
  • data: {"collection":"<name>"}
• keepalive:
  • comment every 25 seconds

See runtime for the client useQuery invalidation model.