Automatiser Suble med v3-API'et
Et REST-API til alt i konsollen: opret en projektnøgle, lav dit første kald, opret en instans og følg jobbet i mål — de samme endpoints, som dashboardet, CLI'en og MCP bruger.
The Suble team
Engineering ·
Alt du kan i Suble-konsollen kan du gøre over HTTP. v3-API'et er en ren REST-flade — JSON ind, JSON ud — og det er præcis det, dashboardet, CLI'en og MCP-serveren kalder under motorhjelmen. Denne guide tager dig fra nul til en kørende instans. Den fulde endpoint-reference findes på API-docs-siden.
1. Få en API-nøgle
I konsollen: åbn Projekt → API-nøgler → Opret nøgle, navngiv den og kopier hemmeligheden — den vises kun en gang. Nøgler er sk_proj_…, afgrænset til det projekt, og har fuld adgang til det.
2. Autentificer
Base-URL'en er https://api.suble.io/v3. Send din nøgle som Bearer-token på hvert kald:
export SUBLE_KEY=sk_proj_din_nøgle
export BASE=https://api.suble.io/v3
curl $BASE/projects \
-H "Authorization: Bearer $SUBLE_KEY"3. Gennemse kataloget
Planer, OS-images og 1-klik-apps er projekt-frie reads — nyttige til at bygge en opret-formular eller vælge en plan-kode:
curl $BASE/plans -H "Authorization: Bearer $SUBLE_KEY" # cx11, cx21, cx31…
curl $BASE/apps -H "Authorization: Bearer $SUBLE_KEY" # docker, coolify, postgresql…4. Opret en instans
POST til projektets instans-collection. source er en af { app }, { image } eller { template }. Du får instansen plus det job, der opretter den, retur:
curl -X POST $BASE/projects/$PROJECT/instances \
-H "Authorization: Bearer $SUBLE_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "web-01",
"plan": "cx21",
"source": { "app": "docker" }
}'
# → { "instance": { "uid": "ins_…", "status": "queued" }, "job": { "uid": "job_…" } }5. Følg jobbet i mål
Provisionering er asynkron. Poll jobbet for live trin-fremgang ("Cloning disk 43%", "Running install steps"…) indtil det lykkes:
curl $BASE/projects/$PROJECT/jobs/$JOB \
-H "Authorization: Bearer $SUBLE_KEY"
# → { "status": "running", "progress": { "step": 2, "total": 5, "message": "Cloning disk 43%" } }Når status er succeeded, returnerer GET /projects/$PROJECT/instances/$INSTANCE den kørende boks med dens IP, og …/instances/$INSTANCE/app giver dig appens forbindelsesdetaljer.
6. Håndter den
POST …/instances/:id/actions { "action": "stop" }— sluk/tænd/genstartDELETE …/instances/:id— riv ned (returnerer et job)GET …/instances/:id/containers+POST …/app/action— Docker-styringPOST …/app/action { "action": "db.create_database", … }— managed-DB-operationerPOST …/projects/:p/networks— private netværk;…/api-keys— håndter nøgler
Konsistente formater
Reads returnerer camelCase-JSON; collections kommer indpakket (fx { "instances": [...] }). Fejl bruger en stabil konvolut: { "error": { "code", "message", "request_id" } } — log request_id, hvis du får brug for support.
Behandl nøgler som adgangskoder
En sk_proj_-nøgle har fuld adgang til sit projekt. Gem den i en secret manager, commit den aldrig, og tilbagekald den fra API-nøgle-siden så snart den ikke er nødvendig. Vil du begrænse skadevirkningen? Brug en nøgle pr. projekt.
Det er hele løkken: nøgle → kald → opret → poll → håndter. Gennemse API-docs for den fulde endpoint-liste, eller lad CLI'en og MCP styre det for dig.
Skrevet af
The Suble team
Engineering