# Conventions

URL: https://docs.spacerun.co/docs/platform/guides/conventions

> Base URLs, JSON, request IDs, CORS, idempotency and versioning.

## Base URLs

| Environment | Base URL |
| --- | --- |
| Your deployment | `https://api.example.com` (placeholder; use your API host) |
| Local development | `http://localhost:8787` (default `PORT`) |
| Behind dashboard/portal host | `https://<app-host>/api` |

The dashboard and portal serve a static SPA and proxy `/api/` to the API, stripping the prefix: `GET https://<app-host>/api/v1/me` reaches `GET /v1/me`. The Vite dev servers do the same to `http://localhost:8787`. Direct API hosts have no `/api` prefix.

All paths in this reference are relative to the API root and start with `/v1`.

## Requests and responses

- Bodies are JSON; send `Content-Type: application/json`.
- Responses are JSON unless noted. Error shapes are in [Errors, pagination and limits](https://docs.spacerun.co/docs/platform/guides/errors-pagination-limits).

## Request IDs

Responses from the developer API routes carry an `x-request-id` header. If you send your own `X-Request-Id`, it is reused; otherwise the server generates a UUID. Quote it when reporting problems. The operational root `/health` probe runs before this middleware.

## CORS

Browser calls to `/v1/*` allow the dashboard's `WEB_ORIGIN` (default `http://localhost:5173`) with credentials. Operators can additionally configure `DOCS_ORIGIN` (for example `http://localhost:3100`) for the API playground. The docs origin uses explicit Bearer headers and does not receive credentialed CORS. Other origins receive no matching allow-origin header; use a server integration or the same-origin `/api` proxy.

## Idempotency

`POST /v1/me/sessions` requires an `Idempotency-Key` header (8-128 characters). Use a fresh key per user action and reuse it only when retrying the same action. See [Session lifecycle](https://docs.spacerun.co/docs/platform/guides/session-lifecycle). Other endpoints do not take this header.

## Values and versioning

Optional means a field can be absent; nullable means its value can be null. Some billing and database numeric fields accept string or number representations; normalize them before arithmetic and verify units. Most date-time strings are ISO timestamps, while some Stripe fields are Unix seconds. Read the specific field schema.

The major version is in the path (`/v1`). Clients should tolerate unknown response fields. See [API changes and compatibility](https://docs.spacerun.co/docs/platform/guides/api-changelog) for the current reference changes and maintenance policy.