Studio API

Auto-generated from the OpenAPI spec. Run node docs-site/scripts/fetch-openapi.js to regenerate.

GET /api/v1/studio/branding

Get Studio Branding

Responses

• 200 — Successful Response

---

GET /api/v1/studio

Get Studio Settings

Responses

• 200 — Successful Response

---

PUT /api/v1/studio

Update Studio Settings

Request body

Field	Required	Type	Description
studio_name	No	string
address	No	string
country	No	string
tax_id	No	string
default_vat_rate	No	number
timezone	No	string
cancellation_hours	No	integer
cancellation_deducts_credit	No	boolean
late_cancel_fee	No	number
no_show_fee	No	number
checkin_open_minutes_before	No	integer
checkin_close_minutes_after	No	integer
waitlist_confirm_minutes	No	integer
guest_bookings_enabled	No	boolean
self_service_purchases_enabled	No	boolean
reminder_hours_before	No	integer
calendar_start_hour	No	integer
calendar_end_hour	No	integer
primary_color	No	string
secondary_color	No	string
tunnel_url	No	string

Responses

• 200 — Successful Response
• 422 — Validation Error

---

GET /api/v1/studio/status

Get Studio Status

Responses

• 200 — Successful Response

---

POST /api/v1/studio/license

Redeem License

Redeems a license key issued by the license-server's checkout flow (docs/PRODUCT_SPEC.md § 14.6, docs/TECHNICAL_SPEC.md § 6.18). Manager only. Synchronously calls the same license-server verify endpoint the 24h background check uses (see License Server endpoints); on any failure, nothing is written to StudioSettings — license_key, plan, license_status, and license_grace_until are only updated together, on success.

Request body

Field	Required	Type	Description
license_key	Yes	string	The key issued once on the license-server's checkout success page.

Responses

• 200 — Same licensing shape as GET /studio/status:

  {
    "plan": "base_ai",
    "license_status": "active",
    "license_grace_until": "2026-09-19T09:15:00"
  }

  license_key itself is never returned (docs/SECURITY_GUIDELINES.md §0/§8).

• 404 LICENSE_KEY_INVALID — The license-server doesn't recognize the submitted key. Nothing is stored.

• 502 LICENSE_SERVER_UNAVAILABLE — The call to the license-server failed, timed out, or returned an unexpected non-200/404 status. Nothing is stored. Safe to retry.

• 422 — Validation Error (missing license_key).

The custom error codes above aren't captured by fetch-openapi.js's regeneration (FastAPI's OpenAPI spec doesn't include raise_api_error responses) — added by hand from app/routers/studio.py's redeem_license. Keep them if this page is regenerated.

---

POST /api/v1/studio/backup

Trigger Backup

Responses

• 200 — Successful Response

---

GET /api/v1/studio/ai/providers

List Ai Providers

Manager only, base_ai plan only (AI_REQUIRES_UPGRADE otherwise — see below). Lists the AI providers a manager can bring their own key for. This is the single source of truth for the provider dropdown in the desktop app's Settings → AI Assistant "Advanced settings" section — never hardcode this list client-side.

Responses

• 200

  [
    {
      "id": "gemini",
      "display_name": "Google Gemini",
      "key_help_url": "https://aistudio.google.com/apikey"
    },
    {
      "id": "groq",
      "display_name": "Groq",
      "key_help_url": "https://console.groq.com/keys"
    }
  ]

  Note there is no litellm_model field — the internal model string used to validate and call each provider is never exposed to any client.

• 403 AI_REQUIRES_UPGRADE — Studio is on the base plan, not base_ai.

---

GET /api/v1/studio/ai

Get Ai Status

Manager only, base_ai plan only. The AI Assistant already works for every studio out of the box via Agon's bundled, centrally-metered license-server proxy — configured here reflects only whether a manager has additionally opted into bringing their own key for one of the providers above; it is not whether the assistant works at all.

Responses

• 200

  { "configured": true, "provider": "gemini" }

  provider is the id of the currently active BYO provider when configured is true, otherwise null. Never returns the API key itself (docs/SECURITY_GUIDELINES.md §0/§8).

• 403 AI_REQUIRES_UPGRADE — Studio is on the base plan, not base_ai.

---

POST /api/v1/studio/ai

Configure Ai

Manager only, base_ai plan only, requires a valid license (require_valid_license — see License Server endpoints). Validates the submitted key with a live test call to the chosen provider before persisting anything; the key is then stored encrypted at rest (Fernet, app/services/crypto.py) and is never returned by any response.

Request body

Field	Required	Type	Description
provider	Yes	string	One of the id values from GET /studio/ai/providers (e.g. "gemini", "groq").
api_key	Yes	string	The provider's API key. Write-only — never echoed back.

Responses

• 200 — {"success": true}
• 400 AI_KEY_INVALID — The provider rejected the key on the live validation call.
• 403 AI_REQUIRES_UPGRADE — Studio is on the base plan, not base_ai.
• 403 LICENSE_INVALID — require_valid_license rejected the request (license canceled, invalid, or grace_expired).
• 422 AI_INVALID_PROVIDER — provider is not one of the registered provider ids. Checked before any live call is made.
• 422 — Validation Error (missing provider or api_key).

The custom error codes above aren't captured by fetch-openapi.js's regeneration (FastAPI's OpenAPI spec doesn't include raise_api_error responses) — added by hand from app/routers/studio.py's configure_ai/get_ai_status/get_ai_providers and app/services/ai_providers.py's provider registry. Keep them if this page is regenerated.

---