# Platform API Reference

Every public endpoint of the FullStacked Cloud fleet in this environment. Project code calls them with absolute URLs (`process.env.AUTH_URL`, ...) and `Authorization: Bearer ${process.env.AUTH_TOKEN}`. Machine-readable: `https://docs.fullstacked.cloud/api/v1/endpoints`.

## auth (`https://auth.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/me` | Bearer fsc_* (AUTH_TOKEN) | Profile of the bearer's principal: identity only, never grants or resources. BYOA principals add authority_id and omit email_verified, plan and plan_name. |
| `GET` | `/api/v1/user/access` | Bearer fsc_* (AUTH_TOKEN) | Effective access of the caller: principal, user, billing, groups, global_permissions and resources (projects, tunnels, data, mcp). Narrow with ?resource_type=projects\|tunnels\|data\|mcp. |
| `POST` | `/v1/auth/exchange/token` | Public (PKCE code_verifier) | Redeems a single-use fsc_exc_ exchange token with its PKCE code_verifier: a BYOA sign-in returns an fsc_ath_<slug>_ session token, a session handoff a fresh fsc_ses_ token. |
| `POST` | `/v1/authorities/:id/token` | X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator | Server-to-server: an enterprise IdP mints a PKCE-bound fsc_exc_ exchange token for { userId, email?, name?, groups?, ttl?, codeChallenge, metadata? }. |
| `POST` | `/v1/authorities/:id/validate` | X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator | Validates an fsc_ath_<slug>_ token issued for this authority and returns its claims (userId, email, name, groups, tokenId, issuedAt, expiresAt, metadata). |
| `POST` | `/v1/authorities/:id/revoke` | X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator | Revokes the authority's tokens by { userId }, by { token }, or { all: true }. |
| `POST` | `/v1/auth/logout` | Bearer fsc_* | Revokes the bearer token and, unless { keepClerkSession: true }, its Clerk sign-in. |
| `GET` | `/v1/tokens` | Bearer fsc_* (usr_ user) | Lists the caller's active tokens (sessions, PATs, agent and edge tokens); OAuth app connections are not included. |
| `POST` | `/v1/tokens` | Bearer fsc_* (usr_ user) | Mints a token { type: "pat" \| "agent" \| "edge", name?, ttl?, scopes? (agent), edgeId? (edge) }; the raw token is returned once (201). |
| `DELETE` | `/v1/tokens/:id` | Bearer fsc_* (usr_ user) | Revokes one of the caller's tokens. |
| `GET` | `/v1/billing` | Bearer fsc_* | The caller's effective plan (base \| pro), quota limits and counted usage. |
| `GET` | `/v1/grants` | Bearer fsc_* (usr_ user) | Lists grants on assets the caller manages, filtered by ?principal_id=, ?resource_type= and ?resource_id=. |
| `PUT` | `/v1/grants` | Bearer fsc_* (usr_ user) | Shares an asset: { principal (user id or email), resourceType, resourceId, permissions, branches?, tags? }. An unknown email becomes a pending invitation. |
| `DELETE` | `/v1/grants` | Bearer fsc_* (usr_ user) | Removes a grant, keyed by principal, resource type and id (query or JSON body). |
| `GET` | `/v1/devices` | Bearer fsc_* | The caller's registered Client GUI devices. |
| `PATCH` | `/v1/devices/:id` | Bearer fsc_* | Renames one of the caller's devices ({ name }). |
| `DELETE` | `/v1/devices/:id` | Bearer fsc_* | Forgets a device; it is registered again on its next report. |
| `GET` | `/.well-known/oauth-authorization-server` | Public | OAuth 2.1 authorization server metadata (authorize, token, register and revoke endpoints) used by MCP clients. |

## git (`https://git.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/projects/:id/env` | Bearer fsc_* | The project's resolved runtime environment: DATA_* wiring and tokens of linked instances, platform URLs (AUTH_URL, AUTH_HOST, TUNNELS_HOST, DOCS_URL) and custom variables. ?format=json\|dotenv; never contains AUTH_TOKEN. |
| `PUT` | `/api/v1/projects/:id/env` | Bearer fsc_* | Merges { variables?, mappings? } into the project's environment config (null removes a key). Needs write. |
| `GET` | `/api/v1/projects/:id/actions` | Bearer fsc_* | Actions compiled in a release (?tag=, default the newest release the caller can access). |
| `POST` | `/api/v1/projects/:id/actions/:name/run` | Bearer fsc_* | Runs a release's action with the caller's own token and data wiring; answers 200 with the run result even when the run failed or timed out. |
| `GET` | `/api/v1/projects/:id/actions/runs` | Bearer fsc_* | Past action runs, filtered by ?tag=, ?action=, ?status= and ?limit=. |
| `GET` | `/api/v1/projects/:id/actions/runs/:runId` | Bearer fsc_* | One action run. |
| `GET` | `/api/v1/projects` | Bearer fsc_* | Projects the caller owns or holds any tier on (?filter= on title, name, description). |
| `POST` | `/api/v1/projects` | Bearer fsc_* | Creates a project { name, title?, description?, default_branch?, template?, owner? } (201). |
| `GET` | `/api/v1/projects/:id` | Bearer fsc_* | Project details (release-only consumers get the summary). |
| `PATCH` | `/api/v1/projects/:id` | Bearer fsc_* | Updates { title?, description? } (write) or renames { name } (admin). |
| `DELETE` | `/api/v1/projects/:id` | Bearer fsc_* | Deletes the project; needs admin and { confirm: "<owner>/<name>" }. |
| `PUT` | `/api/v1/projects/:id/data-links` | Bearer fsc_* | Links a managed data instance to the project ({ data_instance: <UUID> }). |
| `DELETE` | `/api/v1/projects/:id/data-links` | Bearer fsc_* | Unlinks a data instance (?data_instance=<UUID> or JSON body). |
| `GET` | `/api/v1/projects/:id/branches` | Bearer fsc_* | Branches. |
| `POST` | `/api/v1/projects/:id/branches` | Bearer fsc_* | Creates a branch { name, from? } (201). |
| `GET` | `/api/v1/projects/:id/tags` | Bearer fsc_* | Tags. |
| `POST` | `/api/v1/projects/:id/tags` | Bearer fsc_* | Creates a tag { name, message?, ref? } (201); a v* tag enqueues a release build. |
| `POST` | `/api/v1/projects/:id/validate-diagrams` | Bearer fsc_* | Validates ```mermaid blocks in the branch's Markdown files ({ branch?, file_path? }). |
| `GET` | `/api/v1/projects/:id/files` | Bearer fsc_* | Dev-state file tree (?branch=&path=&recursive=&ref=), submodules included. |
| `GET` | `/api/v1/projects/:id/files/content` | Bearer fsc_* | Reads a dev-state file (?branch=&path=&ref=). |
| `PUT` | `/api/v1/projects/:id/files/content` | Bearer fsc_* | Writes a dev-state file { path, content, encoding?: utf-8 \| base64, base_sha256?, branch? }, broadcast to live sync clients (needs dev_sync). |
| `DELETE` | `/api/v1/projects/:id/files/content` | Bearer fsc_* | Deletes a dev-state file (?branch=&path=). |
| `GET` | `/api/v1/projects/:id/diff` | Bearer fsc_* | Uncommitted dev-state changes against HEAD (?branch=). |
| `POST` | `/api/v1/projects/:id/commit` | Bearer fsc_* | Commits the dev state { message, branch? } (201; needs write). |
| `POST` | `/api/v1/projects/:id/stash` | Bearer fsc_* | Stashes the dev state { branch?, message? }. |
| `POST` | `/api/v1/projects/:id/revert` | Bearer fsc_* | Discards dev-state changes back to HEAD { branch? }. |
| `GET` | `/api/v1/projects/:id/releases` | Bearer fsc_* (optional on public release projects) | Release builds (v* tags) visible to the caller. |
| `GET` | `/api/v1/projects/:id/releases/latest` | Bearer fsc_* (optional on public release projects) | Newest succeeded release, with its artifact for ?runtime=<version>. |
| `GET` | `/api/v1/projects/:id/releases/tags/:tag` | Bearer fsc_* (optional on public release projects) | One release's metadata (?runtime=<version>). |
| `GET` | `/api/v1/projects/:id/releases/tags/:tag/artifact` | Bearer fsc_* (optional on public release projects) | Downloads the release .tar.gz compiled for ?runtime=<version> (compiled on demand). |
| `GET` | `/api/v1/projects/:id/releases/tags/:tag/log` | Bearer fsc_* (optional on public release projects) | The release's build log (text/plain). |
| `WS` | `/api/v1/projects/:id/sync` | Bearer fsc_* (or the fsc-sync subprotocol token / ?access_token=) | Live dev-state file sync for ?branch= (default branch otherwise); needs dev_sync. |
| `GET` | `/:owner/:repo/info/refs` | Basic (fsc_* token as password) or Bearer fsc_* | Git Smart HTTP for the git CLI (clone, fetch, push); POST git-upload-pack and git-receive-pack follow on the same path. |

## tunnels (`https://tunnels.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `WS` | `/` | Authorization: <fsc_* token>:<tun_* token> (Bearer prefix optional) | Multiplexed tunnel session dialed by fullstacked/tunnel: each registered tunnel keeps a WebSocket session (more under load), authenticated once at the upgrade, and every TCP/HTTP/WS connection to the tunnel name is a stream on it, to a data instance or Edge tunnel. |
| `GET` | `/api/v1/edges` | Bearer fsc_* | Edge machines visible to the caller. |
| `POST` | `/api/v1/edges` | Bearer fsc_* | Registers an Edge { name } (201); its daemon then authenticates with an fsc_edge_ token from auth POST /v1/tokens. |
| `GET` | `/api/v1/edges/:id` | Bearer fsc_* | One Edge. |
| `POST` | `/api/v1/edges/:id/roll` | Bearer fsc_* | Rotates an Edge's edg_ key (owner or can_register grantee): the lifeline is severed, tunnels and grants stay; the daemon needs a fresh fsc_edge_ token. |
| `DELETE` | `/api/v1/edges/:id` | Bearer fsc_* | Deletes an Edge (owner or can_register grantee). |
| `GET` | `/api/v1/tunnels` | Bearer fsc_* | LAN tunnels visible to the caller (?edgeId=); managed data tunnels are not listed. |
| `POST` | `/api/v1/tunnels` | Bearer fsc_* | Creates a tunnel { name, edgeId, internalHost, internalPort } under an Edge the caller manages (201). |
| `GET` | `/api/v1/tunnels/:id` | Bearer fsc_* | One tunnel. |
| `POST` | `/api/v1/tunnels/test` | Bearer fsc_* | Reachability of { tunnelId }, { token }, or a candidate { edgeId, internalHost, internalPort }: for a tunnel under an Edge it reports whether the Edge daemon is connected, without probing the target. |
| `POST` | `/api/v1/tunnels/:id/roll` | Bearer fsc_* | Rolls the tunnel's tun_ token. |
| `DELETE` | `/api/v1/tunnels/:id` | Bearer fsc_* | Deletes a tunnel. |

## data (`https://tunnels.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `GET` | `/api/v1/data` | Bearer fsc_* | Managed data instances visible to the caller (?engine=). |
| `POST` | `/api/v1/data/provision` | Bearer fsc_* | Provisions an isolated instance { engine: postgres \| redis \| mongodb \| s3, label? } (201). |
| `GET` | `/api/v1/data/:id` | Bearer fsc_* | One instance. |
| `DELETE` | `/api/v1/data/:id` | Bearer fsc_* | Deprovisions an instance (owner only, 204). |
| `GET` | `/api/v1/data/:id/connection` | Bearer fsc_* | Connection parameters, DATA_* variables and fullstacked/tunnel snippets for ?access_level=rw\|ro within the caller's permission. |
| `GET` | `/api/v1/data/:id/schema` | Bearer fsc_* | Introspects tables, keys, collections or buckets (?schema=). |
| `POST` | `/api/v1/data/:id/query` | Bearer fsc_* | Runs one operation: { sql, params? } (postgres), { command } (redis), { operation, collection, ... } (mongodb) or { operation, key?, prefix?, ... } (s3). |

## mcp (`https://mcp.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `POST` | `/mcp` | Bearer fsc_* (OAuth-connected AI apps hold agent tokens) | Streamable HTTP JSON-RPC 2.0 MCP endpoint: docs_list / docs_get (this documentation, open to every token), projects_*, data_*, tunnels_*, users_* and auth_get_my_access tools, plus fullstacked:// resources (fullstacked://docs/{topic} included). |
| `DELETE` | `/mcp` | Bearer fsc_* | Terminates the MCP session named by the Mcp-Session-Id header (204). |
| `GET` | `/sse` | Bearer fsc_* | HTTP+SSE transport (2024-11-05): opens the event stream and announces the /messages?sessionId= endpoint. |
| `POST` | `/messages` | Bearer fsc_* | Posts a JSON-RPC message for an SSE session (?sessionId=); answered on the stream. |
| `GET` | `/.well-known/oauth-protected-resource` | Public | RFC 9728 protected resource metadata pointing AI apps to the Auth OAuth server. |
| `GET` | `/api/v1/audit` | Bearer fsc_* | The caller's own agent audit trail of MCP tool calls (?limit=, default 100). |

## install (`https://install.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `GET` | `/` | Public | The Client GUI installer: an ES module evaluated by the FullStacked runtime through exec; ?force=1 reinstalls. |
| `GET` | `/deeplink` | Public | HTML launcher that opens the installer in the FullStacked runtime (?authority=&auth= for a BYOA sign-in). |
| `GET` | `/v1/install-deeplink` | Public (30 requests/minute per IP) | A signed exec deeplink for the installer, valid one hour (?authority=&auth= must name a registered authority URL). |
| `GET` | `/manifest.json` | Public | Runtime-aware Client GUI release manifest (?runtime=<version>). |
| `GET` | `/releases/:file` | Public | Downloads a Client GUI archive cloud-client-v<version>-rt.<runtime>.tar.gz. |

## docs (`https://docs.fullstacked.cloud`)

| Method | Path | Auth | Summary |
| :--- | :--- | :--- | :--- |
| `GET` | `/` | Public | The documentation portal: HTML, ?format=md (Markdown for agents) or ?format=json. |
| `GET` | `/:topic` | Public | One topic guide (runtime, project-runtime, me, data, ...) as HTML, md or json. |
| `GET` | `/api/v1/endpoints` | Public | This endpoint catalog as JSON. |
| `GET` | `/healthz` | Public | Health check. |
| `GET` | `/version` | Public | Service version. |

## Details

### GET /api/v1/me

Profile of the bearer's principal: identity only, never grants or resources. BYOA principals add authority_id and omit email_verified, plan and plan_name.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (AUTH_TOKEN)
- **Aliases**: `/v1/me`
- **In project code**: `${process.env.AUTH_URL}/api/v1/me`
- **Pitfall**: A relative fetch("/api/v1/me") reads the project's own static files: always prefix process.env.AUTH_URL.

Response:

```json
{
  "status": "success",
  "data": {
    "id": "usr_0123456789abcdef01234567",
    "username": "alice",
    "slug": "alice",
    "name": "Alice",
    "email": "alice@example.com",
    "email_verified": true,
    "avatar_url": null,
    "type": "user",
    "status": "active",
    "plan": "base",
    "plan_name": "Base",
    "has_run_client_gui": true,
    "restricted": false,
    "created_at": "2026-09-20T14:32:00.000Z"
  }
}
```

indexTs:

```ts
const res = await fetch(`${process.env.AUTH_URL}/api/v1/me`, {
    headers: { Authorization: `Bearer ${process.env.AUTH_TOKEN}` },
});
const { data: user } = await res.json();
```

curl:

```bash
curl -sS -H "Authorization: Bearer $AUTH_TOKEN" "https://auth.fullstacked.cloud/api/v1/me"
```

### GET /api/v1/user/access

Effective access of the caller: principal, user, billing, groups, global_permissions and resources (projects, tunnels, data, mcp). Narrow with ?resource_type=projects|tunnels|data|mcp.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (AUTH_TOKEN)
- **In project code**: `${process.env.AUTH_URL}/api/v1/user/access`

curl:

```bash
curl -sS -H "Authorization: Bearer $AUTH_TOKEN" "https://auth.fullstacked.cloud/api/v1/user/access?resource_type=projects"
```

### POST /v1/auth/exchange/token

Redeems a single-use fsc_exc_ exchange token with its PKCE code_verifier: a BYOA sign-in returns an fsc_ath_<slug>_ session token, a session handoff a fresh fsc_ses_ token.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Public (PKCE code_verifier)
- **In project code**: `${process.env.AUTH_URL}/v1/auth/exchange/token`

Request:

```json
{
  "exchangeToken": "fsc_exc_...",
  "codeVerifier": "..."
}
```

### POST /v1/authorities/:id/token

Server-to-server: an enterprise IdP mints a PKCE-bound fsc_exc_ exchange token for { userId, email?, name?, groups?, ttl?, codeChallenge, metadata? }.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator

### POST /v1/authorities/:id/validate

Validates an fsc_ath_<slug>_ token issued for this authority and returns its claims (userId, email, name, groups, tokenId, issuedAt, expiresAt, metadata).

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator

Request:

```json
{
  "token": "fsc_ath_acme_..."
}
```

curl:

```bash
curl -sS -X POST -H "X-FullStacked-Authority-Key: $AUTHORITY_KEY" -H "Content-Type: application/json" -d '{"token":"fsc_ath_..."}' "https://auth.fullstacked.cloud/v1/authorities/<authorityId>/validate"
```

### POST /v1/authorities/:id/revoke

Revokes the authority's tokens by { userId }, by { token }, or { all: true }.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: X-FullStacked-Authority-Key, or Bearer fsc_* of an authority administrator

### POST /v1/auth/logout

Revokes the bearer token and, unless { keepClerkSession: true }, its Clerk sign-in.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

Response:

```json
{
  "status": "revoked"
}
```

### GET /v1/tokens

Lists the caller's active tokens (sessions, PATs, agent and edge tokens); OAuth app connections are not included.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### POST /v1/tokens

Mints a token { type: "pat" | "agent" | "edge", name?, ttl?, scopes? (agent), edgeId? (edge) }; the raw token is returned once (201).

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### DELETE /v1/tokens/:id

Revokes one of the caller's tokens.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### GET /v1/billing

The caller's effective plan (base | pro), quota limits and counted usage.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /v1/grants

Lists grants on assets the caller manages, filtered by ?principal_id=, ?resource_type= and ?resource_id=.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### PUT /v1/grants

Shares an asset: { principal (user id or email), resourceType, resourceId, permissions, branches?, tags? }. An unknown email becomes a pending invitation.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### DELETE /v1/grants

Removes a grant, keyed by principal, resource type and id (query or JSON body).

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (usr_ user)

### GET /v1/devices

The caller's registered Client GUI devices.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### PATCH /v1/devices/:id

Renames one of the caller's devices ({ name }).

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /v1/devices/:id

Forgets a device; it is registered again on its next report.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /.well-known/oauth-authorization-server

OAuth 2.1 authorization server metadata (authorize, token, register and revoke endpoints) used by MCP clients.

- **Service**: `auth` (`https://auth.fullstacked.cloud`)
- **Auth**: Public
- **Aliases**: `/.well-known/openid-configuration`

### GET /api/v1/projects/:id/env

The project's resolved runtime environment: DATA_* wiring and tokens of linked instances, platform URLs (AUTH_URL, AUTH_HOST, TUNNELS_HOST, DOCS_URL) and custom variables. ?format=json|dotenv; never contains AUTH_TOKEN.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

curl:

```bash
curl -sS -H "Authorization: Bearer $AUTH_TOKEN" "https://git.fullstacked.cloud/api/v1/projects/<projectId>/env?format=dotenv"
```

### PUT /api/v1/projects/:id/env

Merges { variables?, mappings? } into the project's environment config (null removes a key). Needs write.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

Request:

```json
{
  "variables": {
    "API_BASE": "https://example.com"
  }
}
```

### GET /api/v1/projects/:id/actions

Actions compiled in a release (?tag=, default the newest release the caller can access).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/actions/:name/run

Runs a release's action with the caller's own token and data wiring; answers 200 with the run result even when the run failed or timed out.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

Request:

```json
{
  "tag": "v1.0.0",
  "params": {
    "customerId": "cus_123"
  }
}
```

curl:

```bash
curl -sS -X POST -H "Authorization: Bearer $AUTH_TOKEN" -H "Content-Type: application/json" -d '{"tag":"v1.0.0","params":{"customerId":"cus_123"}}' "https://git.fullstacked.cloud/api/v1/projects/<projectId>/actions/sync-orders/run"
```

### GET /api/v1/projects/:id/actions/runs

Past action runs, filtered by ?tag=, ?action=, ?status= and ?limit=.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/actions/runs/:runId

One action run.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects

Projects the caller owns or holds any tier on (?filter= on title, name, description).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects

Creates a project { name, title?, description?, default_branch?, template?, owner? } (201).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id

Project details (release-only consumers get the summary).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### PATCH /api/v1/projects/:id

Updates { title?, description? } (write) or renames { name } (admin).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/projects/:id

Deletes the project; needs admin and { confirm: "<owner>/<name>" }.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### PUT /api/v1/projects/:id/data-links

Links a managed data instance to the project ({ data_instance: <UUID> }).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/projects/:id/data-links

Unlinks a data instance (?data_instance=<UUID> or JSON body).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/branches

Branches.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/branches

Creates a branch { name, from? } (201).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/tags

Tags.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/tags

Creates a tag { name, message?, ref? } (201); a v* tag enqueues a release build.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/validate-diagrams

Validates ```mermaid blocks in the branch's Markdown files ({ branch?, file_path? }).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/files

Dev-state file tree (?branch=&path=&recursive=&ref=), submodules included.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/files/content

Reads a dev-state file (?branch=&path=&ref=).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### PUT /api/v1/projects/:id/files/content

Writes a dev-state file { path, content, encoding?: utf-8 | base64, base_sha256?, branch? }, broadcast to live sync clients (needs dev_sync).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/projects/:id/files/content

Deletes a dev-state file (?branch=&path=).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/diff

Uncommitted dev-state changes against HEAD (?branch=).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/commit

Commits the dev state { message, branch? } (201; needs write).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/stash

Stashes the dev state { branch?, message? }.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/projects/:id/revert

Discards dev-state changes back to HEAD { branch? }.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/projects/:id/releases

Release builds (v* tags) visible to the caller.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (optional on public release projects)

### GET /api/v1/projects/:id/releases/latest

Newest succeeded release, with its artifact for ?runtime=<version>.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (optional on public release projects)

### GET /api/v1/projects/:id/releases/tags/:tag

One release's metadata (?runtime=<version>).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (optional on public release projects)

### GET /api/v1/projects/:id/releases/tags/:tag/artifact

Downloads the release .tar.gz compiled for ?runtime=<version> (compiled on demand).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (optional on public release projects)

### GET /api/v1/projects/:id/releases/tags/:tag/log

The release's build log (text/plain).

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (optional on public release projects)

### WS /api/v1/projects/:id/sync

Live dev-state file sync for ?branch= (default branch otherwise); needs dev_sync.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (or the fsc-sync subprotocol token / ?access_token=)

### GET /:owner/:repo/info/refs

Git Smart HTTP for the git CLI (clone, fetch, push); POST git-upload-pack and git-receive-pack follow on the same path.

- **Service**: `git` (`https://git.fullstacked.cloud`)
- **Auth**: Basic (fsc_* token as password) or Bearer fsc_*

shell:

```bash
git clone https://git.fullstacked.cloud/<owner>/<name>.git
```

### WS /

Multiplexed tunnel session dialed by fullstacked/tunnel: each registered tunnel keeps a WebSocket session (more under load), authenticated once at the upgrade, and every TCP/HTTP/WS connection to the tunnel name is a stream on it, to a data instance or Edge tunnel.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Authorization: <fsc_* token>:<tun_* token> (Bearer prefix optional)
- **In project code**: `${process.env.TUNNELS_HOST}`
- **Pitfall**: Pass both halves joined by ':': the user's AUTH_TOKEN and the env's <ENGINE>_DATA_TOKEN or <PREFIX>_TUNNEL_TOKEN (a tun_ token).

indexTs:

```ts
import tunnel from "fullstacked/tunnel";

const pgHost = await tunnel.register({
    host: process.env.TUNNELS_HOST,
    authorization: `${process.env.AUTH_TOKEN}:${process.env.PG_DATA_TOKEN}`,
});
```

### GET /api/v1/edges

Edge machines visible to the caller.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/edges

Registers an Edge { name } (201); its daemon then authenticates with an fsc_edge_ token from auth POST /v1/tokens.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/edges/:id

One Edge.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/edges/:id/roll

Rotates an Edge's edg_ key (owner or can_register grantee): the lifeline is severed, tunnels and grants stay; the daemon needs a fresh fsc_edge_ token.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/edges/:id

Deletes an Edge (owner or can_register grantee).

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/tunnels

LAN tunnels visible to the caller (?edgeId=); managed data tunnels are not listed.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/tunnels

Creates a tunnel { name, edgeId, internalHost, internalPort } under an Edge the caller manages (201).

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/tunnels/:id

One tunnel.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/tunnels/test

Reachability of { tunnelId }, { token }, or a candidate { edgeId, internalHost, internalPort }: for a tunnel under an Edge it reports whether the Edge daemon is connected, without probing the target.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/tunnels/:id/roll

Rolls the tunnel's tun_ token.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/tunnels/:id

Deletes a tunnel.

- **Service**: `tunnels` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/data

Managed data instances visible to the caller (?engine=).

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

curl:

```bash
curl -sS -H "Authorization: Bearer $AUTH_TOKEN" "https://tunnels.fullstacked.cloud/api/v1/data"
```

### POST /api/v1/data/provision

Provisions an isolated instance { engine: postgres | redis | mongodb | s3, label? } (201).

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

Request:

```json
{
  "engine": "postgres"
}
```

### GET /api/v1/data/:id

One instance.

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### DELETE /api/v1/data/:id

Deprovisions an instance (owner only, 204).

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/data/:id/connection

Connection parameters, DATA_* variables and fullstacked/tunnel snippets for ?access_level=rw|ro within the caller's permission.

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /api/v1/data/:id/schema

Introspects tables, keys, collections or buckets (?schema=).

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /api/v1/data/:id/query

Runs one operation: { sql, params? } (postgres), { command } (redis), { operation, collection, ... } (mongodb) or { operation, key?, prefix?, ... } (s3).

- **Service**: `data` (`https://tunnels.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

Request:

```json
{
  "sql": "select now()"
}
```

### POST /mcp

Streamable HTTP JSON-RPC 2.0 MCP endpoint: docs_list / docs_get (this documentation, open to every token), projects_*, data_*, tunnels_*, users_* and auth_get_my_access tools, plus fullstacked:// resources (fullstacked://docs/{topic} included).

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Bearer fsc_* (OAuth-connected AI apps hold agent tokens)

mcpUrl:

```ts
https://mcp.fullstacked.cloud/mcp
```

### DELETE /mcp

Terminates the MCP session named by the Mcp-Session-Id header (204).

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /sse

HTTP+SSE transport (2024-11-05): opens the event stream and announces the /messages?sessionId= endpoint.

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### POST /messages

Posts a JSON-RPC message for an SSE session (?sessionId=); answered on the stream.

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /.well-known/oauth-protected-resource

RFC 9728 protected resource metadata pointing AI apps to the Auth OAuth server.

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Public
- **Aliases**: `/.well-known/oauth-protected-resource/mcp`, `/.well-known/oauth-protected-resource/sse`

### GET /api/v1/audit

The caller's own agent audit trail of MCP tool calls (?limit=, default 100).

- **Service**: `mcp` (`https://mcp.fullstacked.cloud`)
- **Auth**: Bearer fsc_*

### GET /

The Client GUI installer: an ES module evaluated by the FullStacked runtime through exec; ?force=1 reinstalls.

- **Service**: `install` (`https://install.fullstacked.cloud`)
- **Auth**: Public

shell:

```bash
exec https://install.fullstacked.cloud
```

### GET /deeplink

HTML launcher that opens the installer in the FullStacked runtime (?authority=&auth= for a BYOA sign-in).

- **Service**: `install` (`https://install.fullstacked.cloud`)
- **Auth**: Public

### GET /v1/install-deeplink

A signed exec deeplink for the installer, valid one hour (?authority=&auth= must name a registered authority URL).

- **Service**: `install` (`https://install.fullstacked.cloud`)
- **Auth**: Public (30 requests/minute per IP)

### GET /manifest.json

Runtime-aware Client GUI release manifest (?runtime=<version>).

- **Service**: `install` (`https://install.fullstacked.cloud`)
- **Auth**: Public

### GET /releases/:file

Downloads a Client GUI archive cloud-client-v<version>-rt.<runtime>.tar.gz.

- **Service**: `install` (`https://install.fullstacked.cloud`)
- **Auth**: Public
- **Aliases**: `/dist/:file`

### GET /

The documentation portal: HTML, ?format=md (Markdown for agents) or ?format=json.

- **Service**: `docs` (`https://docs.fullstacked.cloud`)
- **Auth**: Public

curl:

```bash
curl -sS "https://docs.fullstacked.cloud/?format=md"
```

### GET /:topic

One topic guide (runtime, project-runtime, me, data, ...) as HTML, md or json.

- **Service**: `docs` (`https://docs.fullstacked.cloud`)
- **Auth**: Public

### GET /api/v1/endpoints

This endpoint catalog as JSON.

- **Service**: `docs` (`https://docs.fullstacked.cloud`)
- **Auth**: Public

### GET /healthz

Health check.

- **Service**: `docs` (`https://docs.fullstacked.cloud`)
- **Auth**: Public

### GET /version

Service version.

- **Service**: `docs` (`https://docs.fullstacked.cloud`)
- **Auth**: Public