REST API reference

The Marriska HTTP API is a FastAPI service. Schemas, validation rules, and per-endpoint detail are auto-generated from the live OpenAPI spec — this page covers the parts that aren’t worth re-generating: base URL, auth, conventions, and the high-level resource map.

Base URL

https://api.marriska.com/api/v1

Every endpoint is prefixed with /api/v1. There’s no unversioned path — versioning lives in the URL.

Authentication

The API supports two auth mechanisms; pick whichever fits the call site.

API key (CLI, CI, server-to-server)

Send the key as a Bearer token. Keys all start with ak_live_:

Authorization: Bearer ak_live_•••

Create keys under Settings → API Keys in the web UI. See Creating an API key. Keys are scoped to one organization and can be revoked at any time.

API-key auth is required for the /api/v1/cli/* endpoints used by marriska-runner. Mismatched, missing, or revoked keys return 401.

The web app authenticates via a server-issued httpOnly refresh cookie (refresh_token) plus a short-lived access token held in memory. The cookie is created by the email/password login or OAuth flows under /api/v1/auth/* and refreshed silently as the access token expires. You almost certainly don’t want to drive the API this way unless you’re the web frontend.

Org context

Many endpoints operate on the caller’s currently-active organization, resolved from the API key (one key, one org) or the session’s X-Org-Id header. Cross-org reads return 403.

Conventions

Content type: application/json for both requests and responses.
Timestamps: ISO 8601 in UTC (e.g. 2026-04-26T12:34:56.789Z).
IDs: UUIDs as strings.
Errors: { "detail": "..." } body with the appropriate HTTP status.
Pagination: not all list endpoints paginate. When they do, parameters are documented in the OpenAPI spec.
Cache: every /api/* response sets Cache-Control: no-store, no-cache, must-revalidate — don’t cache.

CORS

The API allows browser requests from origins listed in CORS_ORIGINS. Allowed methods: GET, POST, PUT, DELETE, OPTIONS. Allowed headers include Authorization, Content-Type, X-Org-Id, and X-Requested-With. Credentials are allowed (cookie auth).

Security headers

Every response carries X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection: 1; mode=block, and Referrer-Policy: strict-origin-when-cross-origin.

Resource map

The API is grouped by tag. Browse the OpenAPI spec for each tag’s endpoints, parameters, and response shapes.

Tag	Prefix	What it covers
`Authentication`	`/auth`	Email/password login, signup, password reset
`OAuth`	`/auth`	Google / GitHub OAuth start + callback
`Sessions`	`/auth/sessions`	List and revoke active sessions
`Email Verification`	`/auth`	Email address verification flow
`Tests`	`/tests`	Create, read, update, delete tests; duplicate tests
`Test Steps`	`/tests/{id}/steps`	Edit, reorder, and delete the steps inside a test
`Test Sets`	`/test-sets`	Named collections of tests
`Test Set Items`	`/test-sets`	Add/remove tests inside a set, reorder
`Tags`	—	Apply and remove tags from tests
`Folders`	`/folders`	Folder tree for organizing tests
`Projects`	`/projects`	Top-level project containers
`Parse`	`/tests`	Translate plain English into structured steps
`Import`	`/tests`	Bulk import tests
`Export`	`/tests`	Export a test as code (Playwright / Cypress / Selenium)
`Test Export`	—	Test-set-level export
`Executions`	`/executions`	Read past run details and per-browser results
`Reports`	`/reports`	Shareable run reports + share links
`Runner`	`/runner`	Cloud run dispatch and control
`Screenshots`	`/tests`	Read step screenshots from a run
`Baselines`	`/tests`	Manage visual regression baselines (per step + browser)
`Schedules`	`/schedules`	Cron-style scheduled runs
`Notifications`	`/notifications`	Notification contacts and preferences
`Organizations`	`/organizations`	Org settings and metadata
`Members`	—	List members; change roles; remove
`Invites`	`/invites`	Invite team members; accept invitations
`API Keys`	`/api-keys`	Create, list, revoke API keys
`CLI`	`/cli`	Endpoints called by `marriska-runner` (require API key auth)
`Plan`	`/plan`	Read current plan; cancel scheduled changes
`PlanChange`	`/plan/change`	Create, confirm, schedule, apply plan changes
`Catalog`	`/catalog`	Public plan catalog (no auth)
`Entitlements`	`/entitlements`	Computed capabilities for the current user/org
`Connection`	—	Connection-status checks
`Settings`	`/settings`	Per-user settings (BYOK keys, preferences)
`Usage`	`/usage`	Per-org usage counters and quota readouts
`Dashboard`	`/dashboard`	Aggregates for the dashboard page
`Admin`	`/admin`	Admin-only endpoints
`Health`	—	Liveness checks

WebSockets

Two real-time channels run alongside the REST API. Both speak JSON messages.

Endpoint	Purpose
`/api/v1/ws`	Browser-driven test execution: step events stream from cloud runs back to the web UI
`/api/v1/ws/agent`	Persistent connection used by `marriska-agent` to receive dispatches and report results

Auth: the agent endpoint accepts the same ak_live_ API key (sent during the connect handshake). Browser WS connections piggy-back on the session cookie.

Webhooks

/api/v1/webhooks/stripe receives Stripe events. The handler verifies the signature via stripe.Webhook.construct_event, dedupes by event id through a webhook_events table, and applies plan changes for checkout.session.completed events (with payment_status=paid and a plan_change_request_id in metadata). Bad signatures return 400, events we don’t act on return 200 "ignored". When PAYMENT_PROVIDER=dev the route also returns 200 "ignored" so misconfigured proxies don’t fail loudly in test environments.

Outbound webhooks (Marriska → your URL) aren’t implemented yet. When they ship, they’ll land here as a separate page.

Fetching the spec

Any running backend exposes the OpenAPI spec at:

curl https://api.marriska.com/api/v1/openapi.json

Pipe it into your code generator of choice (openapi-typescript, openapi-generator, etc.) for typed clients. Schemas are stable within /api/v1; breaking changes would land under /api/v2.