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

# Introduction

> Base URL, authentication, and the error shape shared by every endpoint.

<Warning>
  **TODO: replace before launch.** The endpoint pages under this tab are not generated yet — see
  [Generating this reference](#generating-this-reference) below. Until then this page is the whole
  API reference, and it covers only what ships with the template.
</Warning>

## Base URL

```
https://api.scaling.cloud
```

The API is its own host and deploys independently of the web application. Note
that there is **no `/api` prefix** on this host: the endpoint is
`https://api.scaling.cloud/health`, not `/api/health`.

## Authentication

| Caller | Credential | Notes                                              |
| ------ | ---------- | -------------------------------------------------- |
| Nobody | none       | Only genuinely public endpoints, such as `/health` |

Everything else requires signing in with OAuth.

TODO: replace before launch — the OAuth flow is not settled. Document the
authorization and token endpoints, the grant type, the scopes and the token
lifetime here, then add the row to the table above.

The organisation a request operates in comes from the verified credential, never
from the request. There is no parameter for it.

## Errors

One shape, every endpoint:

```json theme={null}
{
  "code": "unauthenticated",
  "message": "Human-readable, and subject to change.",
  "requestId": "01JB2Z..."
}
```

`code` is one of `unauthenticated`, `forbidden`, `not_found`,
`invalid_request`, `conflict`, `internal`, `retry_later`, mapping to 401, 403,
404, 400, 409, 500 and 503 respectively. Narrow on `code`; treat `message` as
display text.

`retry_later` is the only one worth retrying unchanged. It means the request was
well formed and nothing is wrong — something it depends on has not finished
arriving — so the same request sent again shortly is expected to succeed. Every
other code describes a state that repeating the request will not change. Treat a
`code` you do not recognise the way you treat `internal`.

`requestId` identifies the single failure in our logs. Include it in reports —
without it, an intermittent 500 is unfindable.

## Endpoints shipped with the template

| Endpoint      | Kind     | Returns                                                                    |
| ------------- | -------- | -------------------------------------------------------------------------- |
| `GET /health` | `public` | Liveness, and the commit currently serving. No authentication              |
| `GET /me`     | `member` | The signed-in user within the active organisation. Authentication required |

TODO: replace before launch — this list stops being maintainable the moment the
product has more than a handful of endpoints. Generate it instead.

## Generating this reference

The API is built with `@hono/zod-openapi` and serves its own spec at
`/api/openapi.json`, so this reference should be generated rather than written
by hand. Mintlify reads an OpenAPI document through the `api.openapi` key in
`docs.json` and creates the endpoint pages from it.

That key is deliberately **not** set yet: it points at a spec file or URL, and
pointing it at something that does not resolve fails the Mintlify build. Wire it
up once this product's spec is committed or publicly reachable, and check the
current [Mintlify OpenAPI documentation](https://www.mintlify.com/docs/api-playground/openapi-setup)
for the exact shape rather than copying an older example.