Partner API

Everything the Stayblox CLI does goes through this REST API. You can call it directly (from CI, scripts, or your own tooling) with the same token the CLI uses.

Authentication

All endpoints sit under https://api.stayblox.com/api and require a Sanctum bearer token:

Authorization: Bearer <token>
Accept: application/json

stayblox login obtains and stores one; programmatically, POST /auth/login with your email and password returns { token, ... }.

Your user must belong to a verified partner account. If you belong to several, every endpoint accepts an ?account_id=<id> query parameter to pick the acting account; without it, themes are matched across all your partner accounts and pushes act for the account that owns the manifest slug.

Rate limits

Endpoints	Limit
/partner/themes*, /partner/teams	30 requests/minute
/partner/dev-themes*	240 requests/minute (file sync is chatty)

Error envelope

Failed requests return a consistent JSON envelope:

{
  "message": "Theme validation failed.",
  "errors":  { "package": ["The package field is required."] },
  "report":  { "passed": false, "errors": [], "warnings": [] }
}

• message: always present; human-readable summary.
• errors: only on request-validation failures: field → list of messages.
• report: only when a theme package was validated: the full validation report. Each entry is { "rule": "graphql.validate", "message": "…", "file": "graphql/unit_types.graphql" }.

Status codes: 401 unauthenticated, 403 not your theme/team or no partner account, 404 unknown resource, 422 validation or state errors (e.g. deleting a released version), 429 throttled.

Themes and versions

GET /partner/themes

Your themes across all your partner accounts:

{ "themes": [ { "slug": "breeze", "name": "Breeze", "status": "active", "is_free": true, "price": "0.00", "desktop_preview_url": null, "mobile_preview_url": null } ] }

POST /partner/themes/validate

Multipart body with a package zip (max 20 MB). Dry-run validation: writes nothing, returns the report with HTTP 200 whether it passed or not.

GET /partner/themes/{slug}/versions

All versions, newest first. Each version:

{
  "id": 12,
  "version_name": "1.2.0",
  "version_code": 4,
  "status": "rejected",
  "validation_report": { "passed": true, "errors": [], "warnings": [] },
  "review_notes": "Fix the broken checkout flow.",
  "submitted_at": "2026-06-10T12:00:00.000000Z",
  "reviewed_at": "2026-06-11T09:30:00.000000Z",
  "created_at": "2026-06-10T11:58:21.000000Z",
  "graphql_operations": [
    { "name": "UnitListing", "type": "query", "document_id": "3f1c…64 hex chars" }
  ]
}

status is one of draft, pending_review, approved, rejected.

graphql_operations lists every operation this version declared under graphql/*.graphql, with the document_id your storefront JS sends to the headless GraphQL endpoint — see Storefront data (GraphQL).

POST /partner/themes/{slug}/versions

Multipart package zip. Validates, then creates or re-pushes the draft version named by the manifest. Returns 201 with { version, report }; a failing package returns 422 with { message, report } and writes nothing.

GET /partner/themes/{slug}/versions/{id}

A single version with its full stored validation_report and review_notes.

DELETE /partner/themes/{slug}/versions/{id}

Deletes a draft version: its text files and its private-bucket assets. Released (approved/rejected) versions return 422; they are immutable history. Deleting the last version of a never-released theme removes the theme itself. Returns 204.

POST /partner/themes/{slug}/versions/{id}/submit

Moves a draft into the review queue (pending_review). Only drafts can be submitted; anything else returns 422. You'll be notified by email and in your partner dashboard when it's approved or rejected.

Dev themes

GET /partner/teams

The sites owned by your partner accounts, the candidates for stayblox theme dev. Teams are addressed by their slug:

{ "teams": [ { "slug": "demo-hotel", "name": "Demo Hotel", "domain": "demo-hotel.example" } ] }

The payload also carries legacy numeric id and account_id fields for older CLIs; new integrations should use slug.

POST /partner/dev-themes

Multipart body: team (the team slug, from GET /partner/teams) + a package zip. A legacy numeric team_id is still accepted for older CLIs. Imports the package as a private dev theme on that site. Re-posting the same manifest slug reuses the same dev theme (stable id, stable preview URL) and replaces its files:

{
  "dev_theme": { "id": 2841, "team": "demo-hotel", "name": "Breeze", "theme_slug": "breeze", "version": "1.0.0" },
  "preview_url": "https://demo-hotel.example/_theme-preview/2841/start?expires=…&signature=…",
  "files_synced": 24,
  "changed_at": 1760000000
}

On first create the dev theme's settings and pages are seeded from config/settings_schema.json / config/pages.json, exactly like a catalog install; re-syncs leave them alone so customizer state survives.

201 when created, 200 when reused. The signed preview_url is valid for two hours and only works in your browser session; visitors never see dev themes. While previewing a dev theme, the page polls for changes and reloads itself when a file is synced.

GET /partner/dev-themes/{id}

Current state plus a fresh preview_url and changed_at (the newest updated_at across the theme and its files, as a Unix timestamp).

PUT /partner/dev-themes/{id}/files

Sync a single file:

• Text file (liquid, css, js, json, svg, html, txt, xml, graphql): JSON body { "name": "views/index.liquid", "content": "…" }.
• Binary file (images, fonts, video): multipart body with name and file. Send it as POST with a _method=PUT field: PHP only parses multipart bodies on POST requests.

Names are theme-relative paths, using the same text/binary extensions as the CLI's package rules. Anything outside the supported extensions, or containing .., is rejected with 422.

DELETE /partner/dev-themes/{id}/files

JSON body { "name": "views/index.liquid" } removes the file row (text) or the asset object (binary).

Dev themes are temporary

A dev theme untouched for 30 days is deleted automatically. Run stayblox theme dev again and it is recreated from your local directory.