Overview
Call the platform over HTTP. JSON request and response bodies. The spec is
generated from proto platform.v1 — not a sample Petstore.
The reference lists every path, with examples you can send from the browser.
Base URLs
Section titled “Base URLs”| Environment | URL |
|---|---|
| M12P | https://api.m12p.com |
| Cloud (compose) | http://cloud-api.localhost |
| Desktop (local-backend) | http://127.0.0.1:7733 |
curl https://api.m12p.com/healthzcurl https://api.m12p.com/openapi.jsonThe machine-readable spec on this site is GET /openapi.json.
Authentication
Section titled “Authentication”Send Authorization: Bearer <access token>. A person gets one by signing in
with the CLI (platform token prints it). Automation gets one as a
service principal. Tokens last 15 minutes.
GET /api/auth/me tells you who the token belongs to: the subject, home
tenant, and app, plus tenants, every tenant you can open with its apps.
App services
Section titled “App services”These routes are not in the generated reference yet. {id} is a service id
such as service_06gsviu9kcdrn6dn2rfuq1u924. A role on the service, its app,
or its tenant is enough. Reading needs platform.paas.get. Changing needs
platform.paas.create.
| Route | What it does |
|---|---|
GET /api/paas/{id}/workload | The saved spec: containers, domains, environment |
PUT /api/paas/{id}/workload | Replace the saved spec |
POST /api/paas/{id}/deploy | Deploy. Answers 202 |
GET /api/paas/{id}/deployments | Recent deployments |
GET /api/paas/{id}/deployments/{did} | One deployment: status and summary |
GET /api/paas/{id}/pods | Pods, with the reason and message of any that is not ready |
GET /api/paas/{id}/events | Kubernetes events for this service, newest first, at most 100 |
GET /api/paas/{id}/logs?container=&tail=&previous=1 | A container’s log. previous=1 shows the run before the last restart |
PATCH /api/paas/{id} | Rename: {"name": "travel"} |
POST /api/paas/{id}/webhook | Create a new deploy hook URL. The old one stops working |
DELETE /api/paas/{id}/webhook | Turn the deploy hook off |
POST /api/paas/{id}/pause, POST /api/paas/{id}/start | Stop and start the app |
Deploy
Section titled “Deploy”curl -X POST https://api.m12p.com/api/paas/$SERVICE/deploy \ -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \ -d "$(jq -n --rawfile c docker-compose.paas.yml '{compose: $c}')"| Body | What is deployed |
|---|---|
| empty | The saved spec |
{"compose": "..."} | Your Compose file. It replaces the saved one first |
{"service": "server"} | The saved spec, restarting only that container |
The answer is 202 {"deploymentId", "status", "deployment"}. The deploy runs
in the background for up to four minutes. Poll
GET /api/paas/{id}/deployments/{deploymentId} until status is
succeeded or failed. A failed summary starts with why, for example
“The cluster has no room for this pod”.
Deploy hook
Section titled “Deploy hook”POST /api/hooks/paas/{token} deploys without a token, for CI systems that
cannot sign in. See Deploy hook.
Tenants
Section titled “Tenants”| Route | What it does |
|---|---|
GET /api/tenants/{tid} | One tenant |
PATCH /api/tenants/{tid} | Rename: {"name": "travel"}. Needs iam.policy.update |
GET /api/tenants/{tid}/apps | Apps in the tenant |
GET, POST /api/tenants/{tid}/iam/applications | App registrations and service principals |
GET, PUT /api/tenants/{tid}/iam/applications/{aid}/roles | A service principal’s roles: [{"roleId", "scope"}] |
GET, POST /api/tenants/{tid}/iam/applications/{aid}/federated-credentials | Trusted outside tokens, see GitHub Actions |
DELETE /api/tenants/{tid}/iam/applications/{aid}/federated-credentials/{fid} | Stop trusting one |