API reference

The REST API covers everything the dashboard and CLI can do. It’s JSON over HTTPS at:

https://api.fwoop.dev/v1

Authentication

Create a token under Settings → API tokens and send it as a bearer token. Tokens are scoped (read, deploy, admin) and can be limited to one project.

$ curl https://api.fwoop.dev/v1/servers \
    -H "Authorization: Bearer $FWOOP_TOKEN"

Requests and responses

List endpoints return a page of results and a cursor for the next page:

{
  "data": [
    { "id": "srv_7Hk2", "name": "fra-prod-01", "labels": { "role": "api", "region": "eu" }, "status": "online" }
  ],
  "next_cursor": "c_9aQx"
}

Pass ?limit= (up to 100) and ?cursor= to page through. Timestamps are ISO 8601 in UTC.

Errors use HTTP status codes and a consistent body:

{ "error": { "code": "not_found", "message": "No service named \"apii\" in project production." } }

Rate limits

600 requests per minute per token. Responses include RateLimit-Remaining and RateLimit-Reset; over the limit you get 429 with Retry-After.

Endpoints

Method	Path	Description
GET	/servers	List servers
GET	/servers/{id}	Get a server with current metrics
PATCH	/servers/{id}	Update a server’s name or labels
GET	/services	List services
POST	/services/{id}/deploys	Create a release and start a rollout
GET	/services/{id}/releases	Release history
POST	/services/{id}/rollback	Roll back to a release
GET	/jobs	List jobs
POST	/jobs/{id}/runs	Run a job now
GET	/jobs/{id}/runs	Run history
GET	/backups	List backup plans
POST	/backups/{id}/runs	Take a snapshot now
GET	/secrets/{env}	List secret names and versions (never values)
PUT	/secrets/{env}/{name}	Set a secret value
GET	/audit-log	Audit entries, filterable by actor, action and time

Example: deploy from a script

$ curl -X POST https://api.fwoop.dev/v1/services/api/deploys \
    -H "Authorization: Bearer $FWOOP_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{ "image": "ghcr.io/acme/api:1.42.0", "target": "role=api" }'

{ "id": "rel_r142", "release": "r142", "status": "rolling", "servers": { "total": 3, "healthy": 0 } }

Webhooks

Add an endpoint under Settings → Webhooks and choose which events it receives:

Event	When
deploy.succeeded / deploy.failed	A rollout finished or stopped
job.failed / job.missed	A run failed after retries, or couldn’t run
backup.failed	A snapshot or verification failed
alert.triggered / alert.resolved	An alert rule fired or cleared
server.offline / server.online	An agent lost or regained its connection

Each delivery is a POST with a JSON body and a Fwoop-Signature header: an HMAC-SHA256 of the raw body, keyed with your endpoint’s signing secret. Verify it before trusting the payload:

POST /hooks/fwoop HTTP/1.1
Content-Type: application/json
Fwoop-Signature: t=1792980123,v1=5f2b…

{ "type": "job.failed", "project": "production", "data": { "job": "nightly-report", "run": 412 } }

Failed deliveries are retried with backoff for up to 24 hours.