--- title: HTTP API description: Routes the ArtFloe studio uses. Auth is Bearer JWT unless noted. url: https://artfloe-docs.thally.app/reference/http-api --- # HTTP API Routes the ArtFloe studio uses. Auth is Bearer JWT unless noted. ArtFloe does not ship a separate public SDK. The studio and any HTTP client share these routes. ## Conventions | Rule | Value | |------|--------| | Auth | `Authorization: Bearer ` on signed-in routes. No query-string tokens. | | JSON body | `Content-Type: application/json` except multipart uploads (`image` file field). | | Origin | Mutating studio routes require `Sec-Fetch-Site` ∈ `same-origin`, `same-site`, `none`. | | Max body | 8 MB (`MAX_CONTENT_LENGTH`). Oversized bodies: `413` `file_too_large`. | | JWT | Supabase ES256, audience `authenticated`, issuer `{SUPABASE_URL}/auth/v1`. | Access token lives in JS memory. Refresh token is cookie `af_refresh` (HttpOnly, SameSite=Strict, Secure on HTTPS). Recovery JWTs (`amr` method `recovery`) work only on `POST /reset-password`; elsewhere they return `recovery_token_not_allowed`. Error catalog: [Error codes](/reference/errors). Session design: [Auth and billing](/concepts/auth-and-billing). ## Auth and pages ### `GET /` Studio HTML. If cookie `af_refresh` is missing, `302` to `/login`. ### `GET /login` Login HTML. ### `GET /auth/config` Public client bootstrap. Prefer the `data-auth-config` element on HTML pages. | Field | Type | Notes | |-------|------|--------| | `supabase_url` | string | Project URL | | `supabase_publishable_key` | string | Publishable / anon key | | `turnstile_site_key` | string | Empty when Turnstile is unset | ### `POST /signup` Body: | Field | Type | Required | Notes | |-------|------|----------|--------| | `email` | string | yes | | | `password` | string | yes | 8–128 characters | | `captcha_token` | string | if Turnstile is enforced | Missing/invalid CAPTCHA returns generic `Signup failed. Please try again.` | On Modal, missing Turnstile secret returns `503` `signup_disabled`. Rate limit: 5 attempts / 15 minutes / IP. ```json { "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...", "user": {"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "email": "ada@example.com"} } ``` Sets `af_refresh`. ### `POST /login` Same email/password body (no captcha). `401` `Invalid credentials` on failure, including unconfirmed-email paths that cannot be auto-confirmed. Rate limit: 5 / 15 minutes / IP. Response shape matches signup. ### `POST /forgot-password` | Field | Type | Required | |-------|------|----------| | `email` | string | yes | | `captcha_token` | string | if Turnstile is enforced | Always returns the same 200 body when the request is well-formed (no account enumeration), including when the email is unknown or Supabase errors. On Modal without Turnstile: `503` `reset_disabled`. Per IP+email: 3 / hour, still the generic 200. ```json { "ok": true, "message": "If an account exists for that email, we sent a password reset link. Check your inbox and spam folder." } ``` ### `GET /reset-password` Reset HTML. ### `POST /reset-password` Requires a recovery-session Bearer JWT. Body: `{ "password": "..." }` (8–128). Success: `{ "ok": true, "message": "Password updated. You can sign in with your new password." }` and the refresh cookie is cleared. ### `POST /auth/refresh` Uses cookie `af_refresh`. Returns `{ "access_token": "..." }` and rotates the cookie. Missing cookie: `401` `no_refresh_token`. ### `POST /auth/session` Establish `af_refresh` from a one-time body `{ "access_token", "refresh_token" }` (OAuth PKCE return). If the cookie already exists: `409` `session_already_exists`. Rate limit: 30 / 15 minutes / IP. ### `POST /logout` `{ "ok": true }`. Clears `af_refresh`. ## Catalog ### `GET /styles` No auth. Only catalog entries whose files exist on the style-images volume. ```json { "styles": [ { "id": "vg_starry_night", "display_name": "Starry Night", "era_collection": "post_impressionism", "mood_collection": "dreamy", "file": "vg_starry_night.jpg", "lut_path": "luts/vg_starry_night.cube", "has_lut": true } ], "era_collections": ["post_impressionism", "early_modernism", "art_nouveau", "modernism"], "mood_collections": ["dreamy", "nature", "cozy", "dramatic", "expressive", "tropical", "bold", "elegant", "playful", "vibrant", "dynamic"] } ``` `lut_path` is omitted when the `.cube` file is missing. `has_lut` is always present. ### `GET /presets` Client blend presets. `subject_blend_strength` seeds the **studio slider only**; it is not a `/predict` field. ```json { "natural": {"label": "Natural", "subject_blend_strength": 0.0}, "soft": {"label": "Soft blend", "subject_blend_strength": 0.05}, "artistic": {"label": "Artistic", "subject_blend_strength": 0.1} } ``` ### `GET /data/style-images/` Catalog style image bytes. Missing file: `404` `not_found`. ## Uploads and custom styles Allowed extensions: `.jpg`, `.jpeg`, `.png`, `.bmp`, `.webp`. Magic-byte validation plus 4096 px / 16M pixel cap. Default upload rate: 20 / user / hour / endpoint (`UPLOAD_RATE_LIMIT`). ### `POST /upload_content` Multipart field `image`. NudeNet before disk write. Stored under `/data/temp-content/` as `content_<8 hex>_`. ```json {"filename": "content_a1b2c3d4_photo.jpg"} ``` ### `POST /upload_style` Multipart field `image`. Persists Storage + `custom_styles`. Default 100 per account. ```json { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filename": "custom_3fa85f64-5717-4562-b3fc-2c963f66afa6.jpg", "display_name": "my painting", "url": "/custom_styles/3fa85f64-5717-4562-b3fc-2c963f66afa6/image" } ``` ### `GET /custom_styles` ```json { "styles": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filename": "custom_3fa85f64-5717-4562-b3fc-2c963f66afa6.jpg", "display_name": "my painting", "url": "/custom_styles/3fa85f64-5717-4562-b3fc-2c963f66afa6/image", "created_at": "2026-09-13T16:01:00+00:00" } ] } ``` ### `GET /custom_styles//image` Owner-only bytes. Invalid UUID or foreign id: `404` `not_found`. ### `DELETE /custom_styles/` ```json {"ok": true} ``` ### `GET /data/temp-styles/` Disabled. Returns `404`. ## Predict ### `POST /predict` Starts GPU work. Response `text/event-stream`. Quota reserved **before** GPU. Default predict rate: 10 / user / hour. | Field | Type | Required | Default | Notes | |-------|------|----------|---------|--------| | `content_img_name` | string | yes | | Filename from `upload_content` (or a curated content file). | | `style_img_name` | string | yes | | Catalog `file`, or `custom_.`. `temp_*` still copies from `/data/temp-styles/` if present. | | `person_preserve` | boolean or string | no | true | Any value whose string form is not `false` (case-insensitive) keeps preservation on. | JSON or form fields are accepted. SSE events (each line is `data: \n\n`): | Payload | When | |---------|------| | `{ "log": "Starting neural style transfer..." }` | First event | | `{ "progress": 0–100, "status": "processing", "log": "..." }` | Optimizer iteration lines | | `{ "log": "..." }` | Other GPU log lines | | `{ "progress": 100, "status": "done", "url", "generation_id", "dir_name", ... }` | Success | | `{ "error": "" }` | Failure after the stream starts | Done payload extra keys, when present: `url_blend`, `url_grade`, `url_blend_grade`, `url_content`, `person_detected`, `person_bbox`, `image_hw`. `dir_name` is `All___