Automate
REST API
Manage services from CI and scripts with the /v1 REST API: API keys, scopes and curl examples.
The REST API does everything the dashboard does with services: list, create, change, deploy, start, stop and delete them, and read their status and metrics. It is built for CI pipelines and scripts.
- Base URL:
https://api.quicktane.com/v1 - Reference: the full OpenAPI 3.1 spec — import it into Postman, Insomnia or a client generator.
- JSON in, JSON out. Projects are created in the dashboard; everything about services works through the API.
API keys #
Create a key in the dashboard under API keys. A key belongs to your team and acts for it. It starts with qt_ and is shown once: we only store a hash, so if you lose it, create a new one and revoke the old one. Send it as a Bearer token:
curl https://api.quicktane.com/v1/services \
-H "Authorization: Bearer $QUICKTANE_API_KEY"
Scopes #
Each key has one or more scopes. They are independent — none implies another — so give each key only what it needs. A CI key usually needs only services:deploy: it can deploy and read the status of a service to wait for the rollout, but not list services or read their settings.
| Scope | Allows |
|---|---|
services:read | List services and read their status and URL. |
services:deploy | Roll out a new image tag, e.g. from CI, and read the status of the rollout. |
services:manage | Create services, change their settings and env, start and stop them. |
services:delete | Permanently delete services. Anyone holding the key can remove a service with its data. |
Endpoints #
| Method and path | Does | Scope |
|---|---|---|
GET /v1/projects | List projects | services:read |
GET /v1/projects/{id} | Get a project | services:read |
GET /v1/templates | List templates | services:read |
GET /v1/services | List services | services:read |
POST /v1/services | Create a service | services:manage |
GET /v1/services/{id} | Get a service | services:read |
PATCH /v1/services/{id} | Change a service | services:manage |
DELETE /v1/services/{id} | Delete a service | services:delete |
GET /v1/services/{id}/status | Rollout status, for polling | services:read or services:deploy |
GET /v1/services/{id}/metrics | CPU, memory, network, restarts | services:read |
POST /v1/services/{id}/deploy | Deploy a new image or tag | services:deploy |
POST /v1/services/{id}/redeploy | Re-check the tag and roll out | services:deploy |
POST /v1/services/{id}/start | Start a stopped service | services:manage |
POST /v1/services/{id}/stop | Stop a service | services:manage |
Create a service #
curl -X POST https://api.quicktane.com/v1/services \
-H "Authorization: Bearer $QUICKTANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"project_id": 12,
"name": "web",
"image": "ghcr.io/acme/web:1.4.2",
"is_public": true,
"port": 8080,
"mode": "always_on",
"size": "small",
"env": {"APP_ENV": "production"}
}'
The response (201) is the new service, including its id and public_url. The rollout runs in the background.
Deploy from CI #
Deploy a new tag, then poll the status until the new configuration is live. Deploy a unique tag per build (the commit SHA works well): sending the same reference again keeps the image that is already pinned.
RESPONSE=$(curl -sf -X POST https://api.quicktane.com/v1/services/42/deploy \
-H "Authorization: Bearer $QUICKTANE_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"tag\": \"$GIT_SHA\"}")
FINGERPRINT=$(echo "$RESPONSE" | jq -r .deploy_fingerprint)
for i in $(seq 1 60); do
STATUS=$(curl -sf https://api.quicktane.com/v1/services/42/status \
-H "Authorization: Bearer $QUICKTANE_API_KEY")
if [ "$(echo "$STATUS" | jq -r .status)" = "failed" ]; then
echo "$STATUS" | jq -r .status_reason; exit 1
fi
if [ "$(echo "$STATUS" | jq -r .applied_fingerprint)" = "$FINGERPRINT" ] \
&& [ "$(echo "$STATUS" | jq -r .is_ready)" = "true" ]; then
echo "Deployed"; exit 0
fi
sleep 5
done
echo "Timed out"; exit 1
In GitHub Actions, store the key as a repository secret and pass it in:
- name: Deploy to QuickTane
env:
QUICKTANE_API_KEY: ${{ secrets.QUICKTANE_API_KEY }}
GIT_SHA: ${{ github.sha }}
run: ./scripts/deploy.sh
Change settings and env #
PATCH changes only the fields you send. env adds or overwrites variables; env_remove deletes them by name.
curl -X PATCH https://api.quicktane.com/v1/services/42 \
-H "Authorization: Bearer $QUICKTANE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"size": "medium", "env": {"FEATURE_X": "on"}, "env_remove": ["OLD_FLAG"]}'
Delete a service #
Deleting is permanent and removes the service's volume too. It needs the services:delete scope and the service's slug as confirmation:
curl -X DELETE "https://api.quicktane.com/v1/services/42?confirm=web" \
-H "Authorization: Bearer $QUICKTANE_API_KEY"
Errors #
Every error has a message. Validation errors (422) also have errors, a map from field name to messages — the same messages the dashboard shows.
| Status | Meaning |
|---|---|
401 | Missing, wrong or revoked API key. |
403 | The key lacks the scope, or the team is suspended. A team whose subscription ended is read-only: GET works, changes return 403. |
404 | Not found — also for another team's project or service. |
422 | Invalid input, a plan limit, or an image the registry can't provide. |
429 | Over a rate limit; wait for Retry-After seconds. |
Something missing or wrong? Tell us — or open a ticket from the dashboard.