> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motioness.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

The Motioness REST API — auth, base URL, and how to use the OpenAPI spec.

# 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`](/api/auth/signup) — email + password.
2. [`POST /api/user/signin`](/api/auth/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 in
curl -X POST https://motioness.com/api/user/signin \
  -H 'Content-Type: application/json' \
  -c cookie.txt \
  -d '{"email":"you@example.com","password":"hunter2"}'

# Authenticated call
curl 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](/api/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](/api/errors) for the complete table.

## Rate limits

See [rate limits](/api/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](https://openapi-generator.tech/) for client SDKs in any language
- [Stoplight Studio](https://stoplight.io/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`](/sdks/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.