API overview

The Motioness API is a single OpenAPI 3.1 surface served at https://motioness.com. Every endpoint here is auto-generated from the same Zod schemas the worker uses to validate requests, so the docs and runtime never drift.

Base URL

text
https://motioness.com

Authentication

All authenticated endpoints use a session cookie (better-auth.session_token). Three ways to obtain one:

1. POST /api/user/signup — email + password.
2. POST /api/user/signin — email + password.
3. OAuth — GET /api/user/oauth/google or GET /api/user/oauth/github redirects.

The cookie is HttpOnly, Secure, SameSite=Lax, 7-day expiry. Set automatically on the response.

For API consumers calling from a backend, sign in with curl -c cookie.txt and pass -b cookie.txt on subsequent requests.

bash
# Sign incurl -X POST https://motioness.com/api/user/signin \  -H 'Content-Type: application/json' \  -c cookie.txt \  -d '{"email":"you@example.com","password":"hunter2"}'# Authenticated callcurl https://motioness.com/api/user/me -b cookie.txt

Public endpoints (no auth)

A handful of endpoints don't need a session cookie — they use project keys instead:

• GET /v1/{projectKey}/{src}.{format} — the proxy URL. Auth via project key + allowlist or signing.
• GET /v1/{projectKey}/events/{assetId} — public SSE for asset events.
• OAuth flow URLs.

See proxy URL pattern.

Errors

All endpoints return JSON errors with a stable shape:

json
{ "error": "Project not found" }

Some endpoints add a detail field for context. Validation errors (Zod-rejected requests) return:

json
{  "error": "Validation failed",  "details": { "fieldErrors": { ... } }}

See error reference for the complete table.

Rate limits

See rate limits.

OpenAPI spec

text
https://motioness.com/api/openapi.json

OpenAPI 3.1.0. Tags: Auth, Projects, Assets, Webhooks, Upload. Use it with:

• openapi-generator for client SDKs in any language
• Stoplight Studio for a custom doc viewer
• curl https://motioness.com/api/openapi.json | jq '.paths | keys' to list every endpoint

Versioning

The proxy URL surface (/v1/...) is versioned. The REST API under /api/... is unversioned and additive — endpoints will only ever gain optional fields, never break shape.

Breaking changes (if any) ship under /api/v2/... with at least 90 days of dual-running.

SDK

The frontend SDK @motioness/proxy-client wraps the proxy URL pattern only. For REST API calls, use any HTTP client and reference this docs site (or the OpenAPI spec).

A typed REST SDK is on the v1.3 roadmap.