Docs · Control plane

Control-plane API.

HTTP API at https://api.remoco.dev. Bearer auth via REMOCO_API_TOKEN. The CLI is a thin shell over this; agents and scripts can call it directly.

Authentication

Send Authorization: Bearer <token> on every /v1/* request. In v0.1 the token is tenant-shared; v0.2 replaces it with WorkOS-issued per-user JWTs.

$ export REMOCO_API_TOKEN=...
$ curl -H "authorization: Bearer $REMOCO_API_TOKEN" https://api.remoco.dev/v1/workstations

Workstations

GET /v1/workstations

List workstations in the tenant.

{ "workstations": [{ "name": "wiley", "state": "STATE_RUNNING" }] }

POST /v1/workstations

Create + start a workstation.

$ curl -X POST https://api.remoco.dev/v1/workstations \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"name":"luke","email":"luke@doss.com"}'

GET /v1/workstations/:name

Describe a workstation. Returns state + host.

POST /v1/workstations/:name/suspend

POST /v1/workstations/:name/resume

DELETE /v1/workstations/:name

Lifecycle controls. Delete uses --quiet under the hood; persistent disk retention follows the config's reclaim policy.

Expose / Links

POST /v1/expose

Publish a stable URL. v0.1 returns a plan; the CLI applies it. v0.2 moves mutation server-side.

$ curl -X POST https://api.remoco.dev/v1/expose \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"workstation":"wiley","alias":"main.web.wiley","access":"private"}'

GET /v1/links

List exposed URLs. Stub until v0.2 persists expose state in Postgres.

Artifacts

POST /v1/artifacts

Publish an HTML (or any text) report. Returns a public URL + a shortlink at a.remoco.dev/{id}--{slug}.

$ curl -X POST https://api.remoco.dev/v1/artifacts \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"title":"Q2 infra review","content":"<html>...","tags":["infra"]}'

{
  "id": "a1b2c3d4e5f6a1b2",
  "slug": "q2-infra-review",
  "url": "https://storage.googleapis.com/remoco-artifacts/2026-04-21_a1b2...html",
  "shortLink": "https://a.remoco.dev/a1b2c3d4e5f6a1b2--q2-infra-review",
  "gcsPath": "gs://remoco-artifacts/2026-04-21_a1b2...html"
}

GET /v1/artifacts

Stub until v0.2 lists from Postgres. For now enumerate via gsutil ls gs://remoco-artifacts.

Design systems

POST /v1/ds/:slug/files/:filename

Upload a single DS file (tokens.css, primitives, skill.md). The CLI remoco ds push loops over a folder and calls this per file.

GET /v1/ds/:slug

Describe a DS. Returns the base URL where artifacts can link its tokens.

Billing (Stripe)

POST /v1/billing/checkout

Create a Stripe Checkout session. Stub mode returns a fake URL when STRIPE_SECRET_KEY is unset.

$ curl -X POST https://api.remoco.dev/v1/billing/checkout \
  -H "authorization: Bearer $TOKEN" -H "content-type: application/json" \
  -d '{"email":"wiley@doss.com","plan":"pro","term":"annual"}'

GET /v1/billing/me

Stubbed customer + credit balance. v0.2 returns the real view from Stripe + usage meters.

POST /v1/billing/webhook

Stripe webhook ingest. v0.2 verifies Stripe-Signature.

Shortlinks

Not a JSON endpoint. a.remoco.dev/{id}--{slug} returns a 302 to the artifact's public URL. The resolver reads gs://remoco-artifacts/_short/{id}.txt, which is seeded on artifact upload.

Return codes

Code	Meaning
200 / 201	OK. Body is JSON.
302	Redirect (shortlinks only).
400	Missing or invalid body.
401	Missing or wrong Bearer token.
404	Resource not found.
502	Upstream failure (gcloud, Stripe, GCS).

Source of truth: /Users/wileyjones/Documents/remoco/api/src/server.ts. All routes are registered there; this page mirrors the file.

← CLI reference Back to docs →