openapi: 3.1.0 info: title: QuickTane API version: "1" summary: Manage QuickTane projects and services from CI, scripts and tools. description: | The QuickTane REST API. It offers the same operations as the QuickTane MCP server (`https://api.quicktane.com/mcp`) and the dashboard, and enforces the same rules. **Authentication.** Send a team API key as `Authorization: Bearer qt_...`. Create keys in the dashboard under *API keys*. A key acts for its team. Each endpoint below names the scope the key needs: | Scope | Allows | |---|---| | `services:read` | list projects, services and templates; read status and metrics | | `services:deploy` | roll out a new image or redeploy the current one, and read a service's status to wait for the rollout (CI) | | `services:manage` | create, change, start and stop services; manage registry credentials | | `services:delete` | permanently delete services (opt-in) | Scopes are independent: none implies another. **Responses** are flat JSON objects. Only paginated lists use `data` / `links` / `meta`. Errors always have a `message`. Validation errors (422) also have `errors`, a map from field name to a list of messages. **Teams.** You only see your own team's projects and services. Another team's id returns 404. **Suspension.** A suspended account gets 403 on every call. A team whose subscription has ended is read-only: GET works, and every other method returns 403 with the reason in `message`. **Rate limits.** Each key gets 60 requests per minute and each team 300. Deploys and redeploys share a separate limit of 10 per minute per key. Every other change (create, update, start, stop, delete) shares a limit of 30 per minute per key. These change limits are shared with the MCP server. When you are over a limit you get 429 with a `Retry-After` header. **Background work.** Creating, changing, deploying, starting, stopping and deleting a service all return right away, while the change rolls out in the background. To follow a rollout, poll `GET /v1/services/{id}/status` until `applied_fingerprint` equals the returned `deploy_fingerprint` and `is_ready` is true. contact: name: QuickTane url: https://quicktane.com/contact servers: - url: https://api.quicktane.com security: - apiKey: [] tags: - name: Projects description: A project is a private network for its services. Create projects in the dashboard. - name: Services description: A service runs one Docker/OCI image (linux/amd64) — public, or private with the project's registry credentials. - name: Registry credentials description: | Pull credentials for private registries (ghcr.io, registry.gitlab.com, Docker Hub and the other supported registries), one set per registry host and project. Services in the project use them automatically for images on that host. Passwords and tokens are write-only: no endpoint returns them. Use a read-only token. - name: Custom domains description: | Your own hostnames (app.example.com) on a public service, on paid plans. Each domain needs two DNS records: a CNAME to the platform (for an apex domain ALIAS / CNAME flattening, or www plus a redirect) and a TXT ownership record whose value is per domain. On Cloudflare DNS the CNAME must be "DNS only". Not available yet: until custom domains launch, these endpoints return 404 (403 first for a key without the endpoint's scope). See https://quicktane.com/docs/custom-domains. - name: Templates description: Ready-made service configurations (databases, caches, queues, web apps). paths: /v1/projects: get: tags: [Projects] operationId: listProjects summary: List projects description: The team's projects, newest first, 50 per page. Scope `services:read`. parameters: - $ref: "#/components/parameters/Page" responses: "200": description: A page of projects. content: application/json: schema: allOf: - $ref: "#/components/schemas/Paginated" - type: object properties: data: type: array items: $ref: "#/components/schemas/Project" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/projects/{id}: get: tags: [Projects] operationId: getProject summary: Get a project description: Scope `services:read`. parameters: - $ref: "#/components/parameters/Id" responses: "200": description: The project. content: application/json: schema: $ref: "#/components/schemas/Project" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/projects/{id}/registry-credentials: parameters: - $ref: "#/components/parameters/Id" get: tags: [Registry credentials] operationId: listRegistryCredentials summary: List a project's registry credentials description: Host, username and last use of each set. Never the password. Scope `services:read`. responses: "200": description: The project's credentials, by host. content: application/json: schema: type: object required: [registry_credentials] properties: registry_credentials: type: array items: $ref: "#/components/schemas/RegistryCredential" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } post: tags: [Registry credentials] operationId: createRegistryCredential summary: Add registry credentials description: | Adds pull credentials for one registry host. A project has at most one set per host (422 if one exists — rotate it instead) and at most 20 in all. Images are always checked anonymously first; the credentials are used (and the service pulls with them) only when the registry demands authentication. A refused token then returns 422 with "Registry rejected the credentials for …". Prefer a read-only token on a dedicated machine user: a GitHub classic token with `read:packages` reads every package its user can access. The password may span lines (a Google service account key as `_json_key`). In the dashboard only the team owner manages credentials; API keys are created by the owner. Scope `services:manage`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RegistryCredentialInput" example: host: ghcr.io username: octocat password: ghp_xxxxxxxxxxxxxxxxxxxx responses: "201": description: The saved credentials (without the password). content: application/json: schema: $ref: "#/components/schemas/RegistryCredential" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/projects/{id}/registry-credentials/{credentialId}: parameters: - $ref: "#/components/parameters/Id" - name: credentialId in: path required: true schema: { type: integer, minimum: 1 } put: tags: [Registry credentials] operationId: rotateRegistryCredential summary: Rotate registry credentials description: | Replaces the username and password/token. The id stays, so services that pull with these credentials keep using them; the cluster copy is updated in the background. Scope `services:manage`. requestBody: required: true content: application/json: schema: type: object required: [username, password] properties: username: { type: string, maxLength: 255 } password: { type: string, maxLength: 8192, writeOnly: true } responses: "200": description: The rotated credentials (without the password). content: application/json: schema: $ref: "#/components/schemas/RegistryCredential" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } delete: tags: [Registry credentials] operationId: deleteRegistryCredential summary: Delete registry credentials description: | Deletes the credentials and their cluster copy. Running services keep running, but a service whose image needs them can't be deployed again until credentials for that host are added and it is redeployed. Scope `services:manage`. responses: "204": description: Deleted. "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/templates: get: tags: [Templates] operationId: listTemplates summary: List service templates description: | Lists every template, with whether the team's plan can run it. Pass a template's `key` as `template` to `POST /v1/services`. Templates marked `experimental` have not been verified on the platform yet. Scope `services:read`. responses: "200": description: The catalog. content: application/json: schema: type: object required: [categories, templates] properties: categories: type: object description: Category key to display name, in gallery order. additionalProperties: { type: string } templates: type: array items: $ref: "#/components/schemas/Template" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services: get: tags: [Services] operationId: listServices summary: List services description: The team's services in all projects, newest first, 50 per page. Env values are never included. Scope `services:read`. parameters: - $ref: "#/components/parameters/Page" responses: "200": description: A page of services. content: application/json: schema: allOf: - $ref: "#/components/schemas/Paginated" - type: object properties: data: type: array items: $ref: "#/components/schemas/Service" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } post: tags: [Services] operationId: createService summary: Create a service description: | Creates a service in a project. The image is checked and pinned to a digest now (422 on registry errors). The rollout runs in the background. A public service (`is_public: true`) needs the container `port` and gets an HTTPS URL. Other services can only be reached inside the project, by their slug. Env values are write-only: they are stored encrypted and never returned. With `template`, the template fills in the image, port, env, size and volume, and generates the secrets it needs. Any field you send overrides the template's value (`env` is merged by name). The response includes the generated values once, in `generated_env`. They are not shown again. Scope `services:manage`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CreateServiceInput" examples: image: summary: From an image value: project_id: 12 name: Web image: ghcr.io/acme/web:1.4.2 is_public: true port: 8080 env: { APP_ENV: production } template: summary: From a template value: project_id: 12 template: postgres responses: "201": description: Created. The rollout is queued. headers: Location: description: The new service's URL (`/v1/services/{id}`). schema: { type: string, format: uri } content: application/json: schema: oneOf: - $ref: "#/components/schemas/Service" - $ref: "#/components/schemas/ServiceFromTemplate" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}: parameters: - $ref: "#/components/parameters/Id" get: tags: [Services] operationId: getService summary: Get a service description: The service's configuration and observed state. Env values are never included. Scope `services:read`. responses: "200": description: The service. content: application/json: schema: $ref: "#/components/schemas/Service" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } patch: tags: [Services] operationId: updateService summary: Change a service description: | Only the fields you send change. `env` adds or overwrites variables, and `env_remove` deletes variables by name. Other variables are kept. `command` / `args` replace the image's ENTRYPOINT / CMD; `[]` or `null` goes back to the image's own. `health_check` `null` (or `{"type": "tcp"}`) goes back to the TCP check. The slug cannot change. To change the image, use `POST /v1/services/{id}/deploy`. You may send back the current `slug` or `image` (for example, from a GET), but a different value returns 422. A body with none of the fields below returns 422. The change rolls out in the background. A volume can be added (with `volume_path` and `volume_size_gib`), moved to another path, or grown. It can never be removed or shrunk. Grow it on its own, with no other change in the same call, while an always-on service is running. Scale-to-zero volumes cannot grow. Scope `services:manage`. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/UpdateServiceInput" example: size: medium env: { FEATURE_X: "on" } env_remove: [OLD_FLAG] responses: "200": description: The changed service. The rollout is queued. content: application/json: schema: $ref: "#/components/schemas/Service" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } delete: tags: [Services] operationId: deleteService summary: Delete a service description: | Permanently deletes the service: its containers, public URL, env variables and persistent volume, with its data. This cannot be undone. `confirm` must equal the service's slug. Send it in the query string or in the JSON body. A wrong or missing `confirm` returns 422 (the error does not repeat the slug). Deleting a service that is already being deleted also returns 422, with the error under `service`. Scope `services:delete`. parameters: - name: confirm in: query required: false description: The service's slug. Required here or in the body. schema: { type: string } requestBody: required: false content: application/json: schema: type: object properties: confirm: type: string description: The service's slug. responses: "202": description: Deletion started. content: application/json: schema: type: object required: [id, slug, status, message] properties: id: { type: integer } slug: { type: string } status: { type: string, const: deleting } message: { type: string } "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/status: get: tags: [Services] operationId: getServiceStatus summary: Get a service's status description: | A small payload for CI to poll. While a saved change has not rolled out yet, `status` is `deploying`. After that, it is the observed state. Scope `services:read` or `services:deploy` (so a deploy-only CI key can wait for its rollout; it reveals no configuration). parameters: - $ref: "#/components/parameters/Id" responses: "200": description: The status. content: application/json: schema: $ref: "#/components/schemas/ServiceStatus" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/metrics: get: tags: [Services] operationId: getServiceMetrics summary: Get a service's resource metrics description: | CPU and memory compared with the size's limits, network rates, restarts, the last OOM kill and uptime. A point without data is null. In `total`, CPU and memory are the busiest replica's values, and network is the sum across replicas. Scope `services:read`. parameters: - $ref: "#/components/parameters/Id" - name: range in: query description: "`1h` (1-minute points), `24h` (5-minute points) or `7d` (hourly points)." schema: { type: string, enum: ["1h", "24h", "7d"], default: "1h" } responses: "200": description: The metrics. content: application/json: schema: type: object required: [data] properties: data: $ref: "#/components/schemas/ServiceMetrics" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/deploy: post: tags: [Services] operationId: deployService summary: Deploy a new image description: | Send `image` (a full reference) or `tag` (the current repository at a new tag). The image is checked and pinned to a digest now (422 on registry errors), and then the rollout is queued. If you send the current reference again, the pinned digest is kept, so deploy unique tags (for example, the commit SHA), not a moving `latest`. Scope `services:deploy`. parameters: - $ref: "#/components/parameters/Id" requestBody: required: true content: application/json: schema: type: object properties: image: type: string maxLength: 512 description: Full public image reference. Send this or `tag`. examples: ["ghcr.io/acme/web:1.4.2"] tag: type: string description: New tag for the current image repository. Send this or `image`. examples: ["9f3c2ab"] responses: "202": description: The image is pinned and the rollout is queued. content: application/json: schema: $ref: "#/components/schemas/Rollout" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/redeploy: post: tags: [Services] operationId: redeployService summary: Redeploy the current image description: | Checks the current image reference again. If the tag now points to a new digest, that digest is rolled out. If the digest is the same, the pods are restarted. Returns 422 while the service is stopped, while a deploy is still in progress, or after more than 3 redeploys of the service in a minute. Counts against the deploy rate limit. Scope `services:deploy`. parameters: - $ref: "#/components/parameters/Id" responses: "202": description: The rollout is queued. content: application/json: schema: $ref: "#/components/schemas/Rollout" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/start: post: tags: [Services] operationId: startService summary: Start a stopped service description: Runs one replica again. Calling it on a running service has no effect. Poll the status until `is_ready`. Scope `services:manage`. parameters: - $ref: "#/components/parameters/Id" responses: "202": description: Start queued. content: application/json: schema: $ref: "#/components/schemas/ServiceStatus" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/stop: post: tags: [Services] operationId: stopService summary: Stop a service description: Scales the service to zero replicas. Its configuration and env are kept. Calling it on a stopped service has no effect. Scope `services:manage`. parameters: - $ref: "#/components/parameters/Id" responses: "202": description: Stop queued. content: application/json: schema: $ref: "#/components/schemas/ServiceStatus" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/domains: parameters: - $ref: "#/components/parameters/Id" get: tags: [Custom domains] operationId: listDomains summary: List a service's custom domains description: | Each domain with its stage, the verifier's message and the DNS records to create, plus whether another may be added (`can_add`, and why not in `blocked_reason`) and the plan's limits. Domains the platform removed (taken over, DNS no longer pointing to us) stay listed for a few days with the reason. Poll it while a domain is in progress. Scope `services:read`. responses: "200": description: The service's domains. content: application/json: schema: type: object required: [domains, can_add, blocked_reason, limits] properties: domains: type: array items: $ref: "#/components/schemas/CustomDomain" can_add: { type: boolean } blocked_reason: { type: [string, "null"], description: "Why no domain can be added right now: plan, trust, limits, or a service that is not public." } limits: type: object required: [max_per_team, used_by_team, max_per_service] properties: max_per_team: { type: integer, description: "The plan's cap across the team; 0 = not included." } used_by_team: { type: integer } max_per_service: { type: integer } "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "429": { $ref: "#/components/responses/TooManyRequests" } post: tags: [Custom domains] operationId: addDomain summary: Add a custom domain description: | Adds a hostname to a public service with a port. It starts pending: create the CNAME and TXT records from `dns_records` (the TXT value is issued within a minute — poll the list). The domain is checked at two public resolvers and goes live once the certificate is issued. Paid plans only, after the first paid invoice; 422 with the reason otherwise. Scope `services:manage`. requestBody: required: true content: application/json: schema: type: object required: [hostname] properties: hostname: { type: string, maxLength: 253, description: "e.g. app.example.com — no scheme, path, port or wildcard." } example: hostname: app.example.com responses: "201": description: The new domain. content: application/json: schema: $ref: "#/components/schemas/CustomDomain" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/domains/{domainId}: parameters: - $ref: "#/components/parameters/Id" - $ref: "#/components/parameters/DomainId" delete: tags: [Custom domains] operationId: removeDomain summary: Remove a custom domain description: | The domain stops serving traffic at once; its certificate and edge registration are removed in the background. Adding it again needs a new TXT value. Scope `services:manage`. responses: "204": description: Removed. "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } /v1/services/{id}/domains/{domainId}/verify: parameters: - $ref: "#/components/parameters/Id" - $ref: "#/components/parameters/DomainId" post: tags: [Custom domains] operationId: verifyDomain summary: Verify a custom domain now description: | Checks the TXT record of a pending or failed domain right away and restarts its verification window (48 hours). Domains are also checked automatically. Scope `services:manage`. responses: "202": description: Check queued. content: application/json: schema: $ref: "#/components/schemas/CustomDomain" "401": { $ref: "#/components/responses/Unauthenticated" } "403": { $ref: "#/components/responses/Forbidden" } "404": { $ref: "#/components/responses/NotFound" } "422": { $ref: "#/components/responses/ValidationError" } "429": { $ref: "#/components/responses/TooManyRequests" } components: securitySchemes: apiKey: type: http scheme: bearer description: A team API key (`qt_...`). parameters: Id: name: id in: path required: true schema: { type: integer, minimum: 1 } DomainId: name: domainId in: path required: true schema: { type: integer, minimum: 1 } Page: name: page in: query schema: { type: integer, minimum: 1, maximum: 1000, default: 1 } responses: Unauthenticated: description: The API key is missing, invalid, expired or revoked. After 60 failed attempts per minute, the client IP gets 429. headers: WWW-Authenticate: { schema: { type: string, const: Bearer } } content: application/json: schema: { $ref: "#/components/schemas/Error" } Forbidden: description: The key lacks the endpoint's scope, the account is suspended, or the team's subscription has ended (writes only). content: application/json: schema: { $ref: "#/components/schemas/Error" } NotFound: description: No such resource in the key's team. content: application/json: schema: { $ref: "#/components/schemas/Error" } ValidationError: description: The input was refused, for example an invalid field, a plan limit, a registry error, or a service that is being deleted. content: application/json: schema: { $ref: "#/components/schemas/ValidationError" } TooManyRequests: description: Over a rate limit. Retry after the number of seconds in `Retry-After`. headers: Retry-After: { schema: { type: integer } } content: application/json: schema: { $ref: "#/components/schemas/Error" } schemas: Error: type: object required: [message] properties: message: { type: string } ValidationError: type: object required: [message, errors] properties: message: { type: string } errors: type: object additionalProperties: type: array items: { type: string } examples: - port: ["Public services need the port the container listens on."] Paginated: type: object required: [data, links, meta] properties: data: { type: array, items: {} } links: type: object properties: first: { type: [string, "null"] } last: { type: [string, "null"] } prev: { type: [string, "null"] } next: { type: [string, "null"] } meta: type: object properties: current_page: { type: integer } from: { type: [integer, "null"] } last_page: { type: integer } per_page: { type: integer } to: { type: [integer, "null"] } total: { type: integer } Project: type: object required: [id, name, slug, status, status_reason, services_count, created_at] properties: id: { type: integer } name: { type: string } slug: { type: string } status: { type: string, enum: [provisioning, active, deleting, failed] } status_reason: { type: [string, "null"] } services_count: { type: integer } created_at: { type: string, format: date-time } RegistryCredential: type: object description: Pull credentials for one registry host. The password/token is never returned. required: [id, project_id, host, registry, username, last_used_at, created_at, updated_at] properties: id: { type: integer } project_id: { type: integer } host: { type: string, examples: [ghcr.io] } registry: { type: string, description: Display name of the registry., examples: ["GitHub (ghcr.io)"] } username: { type: string } last_used_at: { type: [string, "null"], format: date-time, description: The last image check that used them. } created_at: { type: string, format: date-time } updated_at: { type: string, format: date-time } RegistryCredentialInput: type: object required: [host, username, password] properties: host: type: string description: A supported registry host, e.g. `ghcr.io`, `registry.gitlab.com`, `docker.io`, `quay.io`. username: { type: string, maxLength: 255, description: No spaces or colons. } password: type: string maxLength: 8192 writeOnly: true description: Password or (better) a read-only access token. Never returned. CustomDomain: type: object required: [id, service_id, hostname, status, stage, stage_label, message, dns_records, verification_expires_at, created_at, verified_at, activated_at, revoked_at] properties: id: { type: integer } service_id: { type: integer } hostname: { type: string, examples: [app.example.com] } status: { type: string, enum: [pending, verified, active, failed, revoked], description: The verifier's state. } stage: type: string enum: [verifying, pending_dns, issuing_certificate, active, failed, removed] description: | What to show: `verifying` (a TXT check is due), `pending_dns` (the last check did not see the TXT yet), `issuing_certificate`, `active`, `failed` (see `message`; verify again) or `removed`. stage_label: { type: string, examples: [Waiting for DNS] } message: { type: [string, "null"], description: "Status text from verification and the edge: what the DNS check saw, the certificate status, or why the domain failed or was removed." } dns_records: type: array description: The records to create at your DNS provider. items: type: object required: [type, name, value, purpose] properties: type: { type: string, enum: [CNAME, TXT] } name: { type: string, examples: [_quicktane-verify.app.example.com] } value: { type: [string, "null"], description: "Null for the TXT until its value is issued, within a minute.", examples: ["qt-verify=abcdefghijklmnopqrstuvwxyz234567"] } purpose: { type: string, enum: [routing, ownership] } verification_expires_at: { type: [string, "null"], format: date-time, description: "While pending: when it fails unless the TXT is seen." } created_at: { type: string, format: date-time } verified_at: { type: [string, "null"], format: date-time } activated_at: { type: [string, "null"], format: date-time } revoked_at: { type: [string, "null"], format: date-time } Mode: type: string enum: [always_on, scale_to_zero] description: "`always_on` keeps one replica running. `scale_to_zero` (public services only) sleeps when idle and wakes on the next request." Size: type: string enum: [small, medium, large, xl, 2xl] description: | The size preset. Your plan decides which sizes you can use. Each size has a guaranteed CPU share (what it bills) and a CPU burst ceiling it can use when the server has spare capacity (best effort, not guaranteed); memory does not burst. - small: 0.25 vCPU guaranteed, bursts to 1 vCPU, 512 MiB - medium: 0.5 vCPU guaranteed, bursts to 2 vCPU, 1 GiB - large: 1 vCPU guaranteed, bursts to 4 vCPU, 2 GiB - xl: 2 vCPU guaranteed, bursts to 8 vCPU, 4 GiB - 2xl: 4 vCPU guaranteed, bursts to 8 vCPU, 8 GiB Prices: https://quicktane.com/docs/services#sizes. Env: type: object description: Environment variables as a map from name to value. Values are write-only and never returned. additionalProperties: { type: [string, "null"] } maxProperties: 100 HealthCheckInput: description: | When the service is ready for traffic. `{"type": "http", "path": "/health"}`: only once `GET ` on the service's port answers 2xx/3xx — for apps that open their port before they can serve (it shows as `deploying` with "Starting — waiting for the app's health check" until then). `{"type": "tcp"}` or `null`: the default, the port accepts connections. `type` defaults to `http`; `port`, if given, must be the service's port. A failing check never restarts the container. Needs a port. oneOf: - type: "null" - type: object additionalProperties: false properties: type: { type: string, enum: [http, tcp], default: http } path: type: string maxLength: 200 pattern: "^/[\\x21-\\x7E]*$" description: Starts with `/`; printable ASCII, no spaces (percent-encode the rest). Required for `http`. examples: ["/healthz/readiness"] port: { type: integer, minimum: 1, maximum: 65535 } HealthCheck: description: The readiness check, or null for a service without a port (no check). oneOf: - type: "null" - type: object required: [type, port] properties: type: { type: string, enum: [http, tcp] } path: { type: string, description: Only for `http`. } port: { type: integer } Argv: type: [array, "null"] maxItems: 64 items: { type: string, maxLength: 4096 } description: | A list of words passed to the container exactly as given. No shell runs, so quotes, `&&`, `|` and `>` have no special meaning (use `["/bin/sh", "-c", "…"]` if you need a shell). `$(NAME)` is replaced with the value of env variable NAME; use it for secrets instead of writing them here. At most 64 words, 4096 bytes each and 16 KiB in total; no NUL bytes. `null` or `[]` means the image's default. examples: [["--bind", "0.0.0.0"]] Service: type: object required: [id, project_id, name, slug, image, image_digest, port, is_public, mode, size, volume, command, args, health_check, status, status_reason, is_stopped, public_url, internal_host, env_keys, deploy_hook, last_woke_at, status_checked_at, deployed_at, created_at, updated_at] properties: id: { type: integer } project_id: { type: integer } name: { type: string } slug: type: string description: The service's DNS name inside the project. It never changes. image: { type: string, examples: ["ghcr.io/acme/web:1.4.2"] } image_digest: type: [string, "null"] description: The digest that `image` is pinned to. port: { type: [integer, "null"] } is_public: { type: boolean } mode: { $ref: "#/components/schemas/Mode" } size: { $ref: "#/components/schemas/Size" } volume: description: The persistent volume, or null if there is none. oneOf: - type: "null" - type: object required: [path, size_gib] properties: path: { type: string } size_gib: { type: integer } command: allOf: - $ref: "#/components/schemas/Argv" description: The start command that replaces the image's ENTRYPOINT, or null for the image's own. args: allOf: - $ref: "#/components/schemas/Argv" description: The arguments that replace the image's CMD, or null for the image's own. health_check: { $ref: "#/components/schemas/HealthCheck" } status: { $ref: "#/components/schemas/Status" } status_reason: { type: [string, "null"] } is_stopped: { type: boolean } public_url: { type: [string, "null"], format: uri } internal_host: type: string description: The host name that other services in the project use to reach this one. env_keys: type: array items: { type: string } description: The names of the env variables. Values are never returned. deploy_hook: type: object required: [enabled, last_used_at] description: The service's deploy hook, a secret URL CI can call to deploy a new tag. It is created, rotated and revoked in the dashboard only; its URL is never returned. See https://quicktane.com/docs/deploy-from-ci. properties: enabled: { type: boolean } last_used_at: { type: [string, "null"], format: date-time } last_woke_at: type: [string, "null"] format: date-time description: For scale-to-zero services, when a request last woke the service. status_checked_at: { type: [string, "null"], format: date-time } deployed_at: type: [string, "null"] format: date-time description: When the last configuration change finished rolling out. created_at: { type: string, format: date-time } updated_at: { type: string, format: date-time } ServiceFromTemplate: description: A service created from a template, with the one-time reveal of its generated secrets. allOf: - $ref: "#/components/schemas/Service" - type: object required: [template, experimental, generated_env, connection] properties: template: { type: string } experimental: { type: boolean } generated_env: type: object additionalProperties: { type: string } description: The secrets the template generated, as a map from name to value. They are shown only in this response. connection: type: string description: How other services connect to this one. `${NAME}` refers to an env variable. examples: ["postgres://postgres:${POSTGRES_PASSWORD}@postgresql:5432/postgres"] Status: type: string enum: [pending, deploying, running, sleeping, waking, stopped, failed, deleting] ServiceStatus: type: object required: [id, status, status_reason, is_ready, rollout_pending, applied_fingerprint, is_stopped, image, image_digest, public_url, status_checked_at] properties: id: { type: integer } status: { $ref: "#/components/schemas/Status" } status_reason: { type: [string, "null"] } is_ready: type: boolean description: True if the service is running, sleeping (scale-to-zero, wakes on the next request) or waking. rollout_pending: type: boolean description: True if a saved change has not been rolled out yet. applied_fingerprint: type: [string, "null"] description: The fingerprint of the configuration that was last applied. is_stopped: { type: boolean } image: { type: string } image_digest: { type: [string, "null"] } public_url: { type: [string, "null"], format: uri } status_checked_at: { type: [string, "null"], format: date-time } Rollout: allOf: - $ref: "#/components/schemas/ServiceStatus" - type: object required: [image_changed, deploy_fingerprint] properties: image_changed: type: boolean description: True if the image reference or digest changed. deploy_fingerprint: type: string description: Poll the status until `applied_fingerprint` equals this value and `is_ready` is true. CreateServiceInput: type: object required: [project_id] properties: project_id: type: integer description: The project to create the service in. template: type: string description: A template key from `GET /v1/templates`. The template's values become the defaults for every other field. name: type: string maxLength: 60 description: The display name. Required unless a template provides one. image: type: string maxLength: 512 description: A public image reference (linux/amd64). Required unless a template provides one. examples: ["ghcr.io/acme/web:1.4.2"] slug: type: string maxLength: 40 pattern: "^[a-z]([a-z0-9-]*[a-z0-9])?$" description: The DNS name inside the project (lowercase, cannot change later). If you leave it out, it is derived from the name. is_public: { type: boolean, default: false } port: type: [integer, "null"] minimum: 1 maximum: 65535 description: The port the container listens on. Required for a public service. mode: { $ref: "#/components/schemas/Mode" } size: { $ref: "#/components/schemas/Size" } env: { $ref: "#/components/schemas/Env" } command: allOf: - $ref: "#/components/schemas/Argv" description: Optional. Replaces the image's ENTRYPOINT. Leave it out for the image's own. examples: [["/bin/sh", "-c", "exec node server.js"]] args: allOf: - $ref: "#/components/schemas/Argv" description: Optional. Replaces the image's CMD. Leave it out for the image's own. health_check: { $ref: "#/components/schemas/HealthCheckInput" } volume_path: type: [string, "null"] description: Optional persistent volume. The absolute path to mount it at, for example `/data`. Requires `volume_size_gib`. volume_size_gib: type: [integer, "null"] minimum: 1 description: The volume size in GiB. Your plan sets the maximum. The volume is replicated, backed up nightly, and deleted with the service. UpdateServiceInput: type: object minProperties: 1 properties: name: { type: string, maxLength: 60 } is_public: { type: boolean } port: { type: [integer, "null"], minimum: 1, maximum: 65535 } mode: { $ref: "#/components/schemas/Mode" } size: { $ref: "#/components/schemas/Size" } env: allOf: - $ref: "#/components/schemas/Env" description: Variables to add or overwrite. env_remove: type: array items: { type: string } maxItems: 100 description: Variable names to delete. command: allOf: - $ref: "#/components/schemas/Argv" description: Replaces the image's ENTRYPOINT. Send `[]` or `null` to go back to the image's own. Restarts the service. args: allOf: - $ref: "#/components/schemas/Argv" description: Replaces the image's CMD. Send `[]` or `null` to go back to the image's own. Restarts the service. health_check: allOf: - $ref: "#/components/schemas/HealthCheckInput" description: 'Send `null` or `{"type": "tcp"}` to go back to the TCP check. Restarts the service.' volume_path: { type: [string, "null"] } volume_size_gib: { type: [integer, "null"], minimum: 1 } Template: type: object required: [key, name, category, image, available] properties: key: { type: string, examples: [postgres] } name: { type: string } category: { type: string } icon: { type: [string, "null"] } description: { type: string } image: { type: string } port: { type: [integer, "null"] } is_public: { type: boolean } mode: { $ref: "#/components/schemas/Mode" } min_size: { $ref: "#/components/schemas/Size" } size: { $ref: "#/components/schemas/Size" } env: type: object additionalProperties: { type: string } description: Default env values. Generated secrets are not included. generated_env: type: array items: { type: string } description: The names of the secrets generated for each new service. volume: oneOf: - type: "null" - type: object properties: path: { type: string } size_gib: { type: integer } connection: type: string description: "How other services connect. `{host}` is the service's slug, and `${NAME}` is an env variable." notes: {} experimental: { type: boolean } first_run: {} command: allOf: - $ref: "#/components/schemas/Argv" description: The template's ENTRYPOINT override, or null. args: allOf: - $ref: "#/components/schemas/Argv" description: The template's CMD override, or null. health_check_path: type: [string, "null"] description: The template's HTTP health check path, or null for the TCP check. available: type: boolean description: Whether the team's plan can run the template. unavailable_reason: { type: [string, "null"] } ServiceMetrics: type: object properties: range: { type: string, enum: ["1h", "24h", "7d"] } step_seconds: { type: integer } from: { type: string, format: date-time } to: { type: string, format: date-time } collecting: { type: boolean } latest_sample_at: { type: [string, "null"], format: date-time } limits: type: object properties: cpu_millicores: { type: integer } memory_bytes: { type: integer } replicas: { type: array, items: { type: object } } last_oom_killed_at: { type: [string, "null"], format: date-time } last_oom_likely: { type: boolean } total: type: array items: type: object properties: t: { type: string, format: date-time } cpu: { type: [number, "null"], description: Millicores. } memory: { type: [integer, "null"], description: Bytes. } rx: { type: [number, "null"], description: Bytes per second received. } tx: { type: [number, "null"], description: Bytes per second sent. } pods: type: array items: type: object properties: name: { type: string } last_seen_at: { type: string, format: date-time } points: { type: array, items: { type: object } }