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)

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

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

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

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

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

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

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:

{
  "status": "success",
  "data": {
    "id": "usr_0123456789abcdef01234567",
    "username": "alice",
    "slug": "alice",
    "name": "Alice",
    "email": "[email protected]",
    "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:

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:

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:

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__ 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:

{
  "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__ 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:

{
  "token": "fsc_ath_acme_..."
}

curl:

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:

{
  "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:

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:

{
  "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:

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

curl:

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: "/" }.

• 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: }).

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

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

Unlinks a data instance (?data_instance= 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=.

• 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=).

• 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= (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:

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 _DATA_TOKEN or TUNNEL_TOKEN (a tun token).

indexTs:

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:

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:

{
  "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:

{
  "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:

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:

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=).

• Service: install (https://install.fullstacked.cloud)
• Auth: Public

GET /releases/:file

Downloads a Client GUI archive cloud-client-v-rt..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:

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