Skip to content

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:

bash
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.

ScopeAllows
services:readList services and read their status and URL.
services:deployRoll out a new image tag, e.g. from CI, and read the status of the rollout.
services:manageCreate services, change their settings and env, start and stop them.
services:deletePermanently delete services. Anyone holding the key can remove a service with its data.

Endpoints #

Method and pathDoesScope
GET /v1/projectsList projectsservices:read
GET /v1/projects/{id}Get a projectservices:read
GET /v1/templatesList templatesservices:read
GET /v1/servicesList servicesservices:read
POST /v1/servicesCreate a serviceservices:manage
GET /v1/services/{id}Get a serviceservices:read
PATCH /v1/services/{id}Change a serviceservices:manage
DELETE /v1/services/{id}Delete a serviceservices:delete
GET /v1/services/{id}/statusRollout status, for pollingservices:read or services:deploy
GET /v1/services/{id}/metricsCPU, memory, network, restartsservices:read
POST /v1/services/{id}/deployDeploy a new image or tagservices:deploy
POST /v1/services/{id}/redeployRe-check the tag and roll outservices:deploy
POST /v1/services/{id}/startStart a stopped serviceservices:manage
POST /v1/services/{id}/stopStop a serviceservices:manage

Create a service #

bash
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.

bash
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:

.github/workflows/deploy.yml
- 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.

bash
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:

bash
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.

StatusMeaning
401Missing, wrong or revoked API key.
403The key lacks the scope, or the team is suspended. A team whose subscription ended is read-only: GET works, changes return 403.
404Not found — also for another team's project or service.
422Invalid input, a plan limit, or an image the registry can't provide.
429Over a rate limit; wait for Retry-After seconds.

Something missing or wrong? Tell us — or open a ticket from the dashboard.