Pictage / Docs / API

Public API v1

Programmatic access to workspaces, shoots, galleries, clients, photos, and webhooks. Create a token at Settings → API tokens. This page lists the routes that exist today. It does not invent endpoints.

Base URL and auth

• Base: https://pictage.ai/api/v1
• Header: Authorization: Bearer pk_live_...
• JSON in, JSON out. Set Content-Type: application/json on writes.

Rate limits

600 requests / 60 seconds per API token, fail-closed. Exhaustion returns 429 rate_limited. A limiter outage refuses the request rather than opening a scrape path. Retry-After is set when the durable limiter supplies it.

Hidden 404s

A token scoped to another workspace, a caller who is not a member, or another tenant's resource id returns 404 not_found with { "ok": false, "error": "not_found" } and no reason. A 403 would confirm the row exists. Intra-tenant role shortage (a viewer registering webhooks) stays 403 forbidden.

Live endpoints

Generated from the same registry as the public OpenAPI 3.1 artifact at /docs/api/openapi-v1.json.

• GET /auth/whoami · Token introspection
• POST /client-sessions · Exchange a portal token for a client session
• GET /workspaces · List workspaces
• GET /galleries · List galleries
• POST /galleries · Create a gallery from keepers
• GET /galleries/:id · Get a gallery
• GET /galleries/:id/photos · List gallery photos
• POST /galleries/:id/favorites · Favorite a photo
• DELETE /galleries/:id/favorites · Unfavorite a photo
• GET /shoots · List shoots
• POST /shoots · Create a shoot
• GET /clients · List clients
• POST /clients · Create a client
• GET /orders · List paid orders
• GET /search · Unified cross-entity search
• GET /webhook-endpoints · List legacy webhook endpoints
• POST /webhook-endpoints · Register a legacy webhook (admin+)
• DELETE /webhook-endpoints/:id · Delete a legacy webhook (admin+)
• POST /webhooks/subscriptions · Subscribe a Zapier REST hook (admin+)
• DELETE /webhooks/subscriptions · Delete a Zapier REST hook (admin+)
• GET /webhook-endpoints/:id/deliveries · List delivery history for a webhook endpoint
• POST /webhook-deliveries/:id/replay · Replay a webhook delivery (admin+)
• POST /webhook-endpoints/:id/rotate-secret · Rotate a webhook endpoint signing secret (admin+)
• POST /photos · Start a single-shot upload
• POST /photos/:id/finalize · Finalize a single-shot upload
• POST /upload-sessions · Open a multipart upload session
• POST /upload-sessions/:id/files · Register files on a session
• POST /upload-sessions/:id/files/:fileId/parts/sign · Sign multipart part PUT URLs
• POST /upload-sessions/:id/files/:fileId/parts/complete · Record a part ETag
• POST /upload-sessions/:id/files/:fileId/complete · Assemble a multipart file
• POST /upload-sessions/:id/files/:fileId/abort · Abort one file
• POST /upload-sessions/:id/finalize · Close an upload session
• GET /upload-sessions/:id · Read a session and its files
• POST /upload-sessions/:id/resume · Get the resume manifest for a session
• POST /upload-sessions/:id/pause · Pause an in-flight upload session
• POST /upload-sessions/:id/unpause · Resume a paused upload session
• GET /mobile/dashboard · Mobile home-screen dashboard
• GET /shoots/:id · Get a shoot
• PATCH /shoots/:id/shot-list · Tick or untick a shot-list item
• POST /ai/cull-jobs · Start a background cull job
• GET /ai/jobs/:id · Poll an AI job
• POST /galleries/:id/publish · Publish a gallery
• GET /invoices · List invoices
• GET /tasks · List tasks

Webhooks

One outbound system (API-10 consolidated the two that used to exist). Every event signs with X-Pictage-Signature. Verification recipes live at /docs/webhooks. Legacy /webhook-endpoints is a deprecated compatibility shim over the same system; prefer /webhooks/subscriptions. Every event type, including gallery.delivered and shoot.completed, now has a real emitter.

Long form

Request and response examples (pulled from route test fixtures) live in the repository at docs/api/v1.md. HTTP architecture: API_ARCHITECTURE.md.

Questions? Email support@pictage.ai.