API
Everything you can do in the portal, you can also do with the JSON API. The portal itself uses this API. This page explains authentication, conventions and errors, and lists the endpoints of every area.
In the examples, the panel runs at https://panel.example.com.
Base URLs#
All endpoints are under /api. Each area has its own prefix:
| Area | Prefix |
|---|---|
| Identity, users, organizations, API tokens, audit log | /api/iam |
| Cloud: projects, regions, instances, SSH keys, tasks | /api/cloud/v1 |
| Hosting plans and services | /api/hosting/v1 |
| Domains | /api/domains/v1 |
| DNS zones and records | /api/dns/v1 |
| Billing: credit, usage, invoices, payments, payment webhooks | /api/billing/v1 |
| Support tickets | /api/support/v1 |
| DDoS detector events | /api/network/v1 |
| Back office for platform staff | /api/admin |
GET /api/health needs no authentication. It returns 204 No Content when the database is reachable and 503 Service Unavailable when it is not.
Authentication#
Send credentials in the Authorization header. Stacklane accepts two kinds:
| Header | Used by |
|---|---|
Authorization: APIKey <id>$<secret> | Scripts and tools. The token belongs to an organization. |
Authorization: Bearer <access token> | The portal and other clients that sign in as a person. |
A request without valid credentials returns 401 with the code unauthorized. A request for an organization that is suspended returns 403 with the code account_suspended.
API tokens#
An organization administrator creates tokens in the portal:
- Open Settings → API tokens.
- Click Create token.
- Enter a name, choose a role and an expiry (30, 90 or 365 days, or never).
- Copy the token. Stacklane shows it only once.
The token has the form <id>$<secret>, for example 7$Zq3v.... Stacklane stores only a SHA-256 hash of the secret.
The token has one of the organization roles: administrator, engineer, billing or viewer. It can do what a user with that role can do. See Clients and users.
The $ character has a meaning in most shells. Put the header in single quotes, or store the token in a variable:
export STACKLANE_TOKEN='7$Zq3vS1x...'
curl https://panel.example.com/api/cloud/v1/projects \
-H "Authorization: APIKey $STACKLANE_TOKEN"
A token stops working when:
- it expires;
- an administrator revokes it;
- the user who created it gets another role or is removed from the organization.
An API token does not represent a person. These endpoints need a signed-in user and return 403 with the code user_required for API tokens:
- everything under
/api/iam/users/me; POST /api/iam/clients/me/tokens(create a token);POST /api/support/v1/ticketsandPOST /api/support/v1/tickets/{id}/replies;- all back-office endpoints under
/api/admin.
Access tokens#
To act as a person, sign in with email and password:
curl -X POST https://panel.example.com/api/iam/auth/login \
-H 'Content-Type: application/json' \
-d '{"email": "user@example.com", "password": "correct horse battery staple"}'
Without two-factor authentication, the response contains the access token:
{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 600,
"two_factor_setup_required": false
}
With two-factor authentication, the response asks for a code:
{ "mfa_required": true, "mfa_token": "..." }
Send the code within five minutes:
curl -X POST https://panel.example.com/api/iam/auth/login/mfa \
-H 'Content-Type: application/json' \
-d '{"mfa_token": "...", "code": "123456"}'
The code is a 6-digit code from the authenticator app or a recovery code.
expires_in is the lifetime of the access token in seconds. It follows security.access_token_minutes in the configuration file. The login also sets a refresh cookie. POST /api/iam/auth/refresh and POST /api/iam/auth/logout use that cookie and need an Origin header that matches the panel. They are meant for the portal in the browser.
When an organization requires two-factor authentication and the user has not set it up, most endpoints return 403 with the code two_factor_required.
Back-office endpoints#
Endpoints under /api/admin need the access token of a user with a platform staff role. API tokens do not work there. Each endpoint checks the staff role. See Administration.
ACCESS_TOKEN=$(curl -s -X POST https://panel.example.com/api/iam/auth/login \
-H 'Content-Type: application/json' \
-d '{"email": "ops@example.com", "password": "..."}' | jq -r .access_token)
curl https://panel.example.com/api/admin/billing/invoices?status=open \
-H "Authorization: Bearer $ACCESS_TOKEN"
For staff accounts with two-factor authentication, add the /api/iam/auth/login/mfa step.
Requests and responses#
- Request and response bodies are JSON. Send
Content-Type: application/jsonwith every body. - A request body can be at most 256 KiB. A larger body is rejected.
- Times are Unix timestamps in seconds, for example
"created_at": 1795000000. - Amounts of money are whole cents, in fields that end in
_cents.1210means 12.10. - VAT rates are basis points, in fields that end in
_bp.2100means 21%. - Organizations, users, regions, flavors, images, projects, SSH keys, plans, invoices and tickets have numeric IDs.
- Instances, tasks, snapshots, volumes, hosting services, domains, DNS zones and payments have string IDs (UUIDs).
- API responses have
Cache-Control: no-store.
Lists and pagination#
List endpoints return an object with count and results:
{
"count": 2,
"results": [
{ "id": 1, "name": "Default", "is_default": true, "client_id": 42, "created_at": 1795000000 },
{ "id": 5, "name": "Staging", "is_default": false, "client_id": 42, "created_at": 1795003600 }
]
}
Some lists are paged with limit and offset:
| Parameter | Default | Range |
|---|---|---|
limit | 25 | 1 to 200 |
offset | 0 | 0 or more |
These lists use paging: support tickets, organization users, the audit log, invoices, transactions and payments. For tickets, users, the audit log, invoices and transactions, count is the total number of matching items, so you can calculate the number of pages. For payments, count is the number of items in the response.
The task list uses only limit (default 50, at most 200). Other lists return all items.
Errors#
Errors have this format:
{
"error": {
"code": "validation",
"message": "Some fields are invalid.",
"fields": [
{ "field": "name", "code": "required" },
{ "field": "flavor_id", "code": "invalid" }
]
}
}
codeis a stable, machine-readable code. Use it in your scripts.messageis a short English text for people.fieldsis only present for validation errors.
Field codes are required, invalid, too_long, too_short, out_of_range, unavailable, unsupported and reserved.
Common status codes#
| Status | Codes | Meaning |
|---|---|---|
400 | invalid_json and others | The body cannot be read, or a value is wrong. |
401 | unauthorized, invalid_credentials | Missing or wrong credentials. |
402 | billing_hold, insufficient_credit | An invoice is overdue, or the credit balance is too low. See Billing hold. |
403 | forbidden, user_required, two_factor_required, account_suspended, quota_exceeded, registration_closed | Not allowed for this user, token or organization. |
404 | not_found | The object does not exist or belongs to another organization. |
408 | The request took longer than 30 seconds. | |
409 | busy, not_ready, conflict and others | The object is in a state that does not allow this action. |
413 | The request body is too large. | |
422 | validation | One or more fields are invalid. See fields. |
429 | throttled | Too many requests. See Rate limits. |
500 | internal | An unexpected error. The service log has the details. |
502 | payment_provider_unavailable, registrar_unavailable, panel_unavailable, dns_failed, metrics_unavailable | An external system did not answer or failed. |
503 | The panel is overloaded and sheds load. Try again later. |
Responses with 408 and 503 from the server limits have no JSON body.
Tasks and 202 Accepted#
Actions on instances, hosting services and domains take time. Stacklane does not wait for them. It saves the request, adds a task to a queue and answers with 202 Accepted. The response contains the task:
{
"instance": { "id": "3f6c...", "name": "web", "status": "creating", "...": "..." },
"task": {
"id": "a41e...",
"client_id": 42,
"project_id": 1,
"kind": "instance.create",
"resource_type": "instance",
"resource_id": "3f6c...",
"state": "pending",
"error": null,
"created_at": 1795000000,
"started_at": null,
"finished_at": null
}
}
Follow the task with GET /api/cloud/v1/tasks/{id}. This endpoint shows tasks of every kind: instance, service and domain tasks.
state | Meaning |
|---|---|
pending | Waiting in the queue. |
running | A worker is running it. |
finished | Done. |
error | Failed. The error field contains the reason. |
curl https://panel.example.com/api/cloud/v1/tasks/a41e... \
-H "Authorization: APIKey $STACKLANE_TOKEN"
Poll every few seconds until the state is finished or error. Stacklane does not retry failed tasks.
Only one task can run per instance, service or domain. A new action while a task is pending or running returns 409 with the code busy.
Task kinds:
| Kind | Started by |
|---|---|
instance.create, instance.power, instance.delete, instance.firewall, instance.snapshot, instance.volume | Cloud endpoints. |
service.create, service.suspend, service.unsuspend, service.terminate | Hosting endpoints and billing. |
domain.register, domain.renew, domain.nameservers | Domain endpoints and automatic renewal. |
Billing hold#
When an organization has an invoice that is overdue for longer than the provider allows, these requests return 402 with the code billing_hold:
- create an instance;
- start or reboot an instance;
- add a volume;
- order hosting;
- register a domain.
Pay the invoice to continue. Other requests keep working.
Registering a domain also returns 402, with the code insufficient_credit, when the credit balance does not cover the price.
Rate limits#
All API requests from one IP address share a limit of 1,200 requests per minute. Some endpoints have lower limits, for example sign-in, domain searches and payments. See Network protection for the full list.
When you go over a limit, Stacklane answers 429 with:
{ "error": { "code": "throttled", "message": "Too many attempts. Try again later." } }
The response has no Retry-After header. Wait before you try again. The limits use fixed windows of one to sixty minutes.
When more than 1,024 requests are in progress at the same time, Stacklane answers new requests with 503 at once, without a body.
Trace IDs#
Every response has an X-Trace-Id header. The audit log stores the same ID with each record, so you can find the record of a request.
To use your own trace ID, send a W3C traceparent header:
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Stacklane then uses the trace ID from that header (4bf92f3577b34da6a3ce929d0e0e4736) for the request.
Endpoints#
The tables use these role names for organization users and API tokens:
- any: every role;
- resources:
administratorandengineer; - billing:
administratorandbilling; - admin:
administratoronly; - user: a signed-in person, not an API token;
- public: no authentication.
Identity: /api/iam#
| Method | Path | Access | Description |
|---|---|---|---|
GET | /frontend/variables | public | Product name, accent color, support email, links, sign-up status and default language. |
POST | /auth/register | public | Sign up. Body: name, email, password, optional company_name, locale. Returns 202. |
POST | /auth/login | public | Sign in. Body: email, password. |
POST | /auth/login/mfa | public | Second step. Body: mfa_token, code. |
POST | /auth/refresh | cookie | New access token from the refresh cookie. |
POST | /auth/logout | cookie | End the session. |
POST | /auth/verify-email | public | Confirm an email address. Body: token. |
POST | /auth/verify-email/resend | public | Send a new confirmation link. Body: email. Returns 202. |
POST | /auth/password/forgot | public | Send a reset link. Body: email. Returns 202. |
POST | /auth/password/reset | public | Set a new password. Body: token, password. |
GET, PATCH | /users/me | user | Read or change your profile: name, locale, timezone, theme. |
POST | /users/me/password | user | Change password. Body: current_password, password. |
POST | /users/me/2fa/setup | user | Start two-factor setup. Returns secret, otpauth_url and qr_code. |
POST | /users/me/2fa/enable | user | Turn on two-factor. Body: code, password. Returns recovery_codes. |
POST | /users/me/2fa/disable | user | Turn off two-factor. Body: password, code. |
POST | /users/me/2fa/recovery-codes | user | New recovery codes. Body: password. |
GET | /users/me/logins | user | Sign-in attempts. Query: hours (default 24, at most 2,160). |
GET | /users/me/sessions | user | Active sessions. |
POST | /users/me/sessions/revoke-others | user | Sign out other sessions. Body: password. |
DELETE | /users/me/sessions/{id} | user | Sign out one session. |
GET | /clients/me | any | Organization details. |
PATCH | /clients/me | billing | Change organization details. Starts the VIES check. |
PUT | /clients/me/two-factor-policy | admin | Body: {"required": true}. |
GET, POST | /clients/me/users | admin | List users (query search, limit, offset) or invite one (body email, name, role, optional locale). |
PATCH, DELETE | /clients/me/users/{id} | admin | Change the role (body role) or remove a user. |
GET | /clients/me/tokens | admin | List API tokens. |
POST | /clients/me/tokens | admin, user | Create a token. Body: name, role, optional description, expires_in_days (1 to 3,650). Returns the secret once. |
DELETE | /clients/me/tokens/{id} | admin | Revoke a token. |
GET | /clients/me/audit-logs | admin | Audit log. Query: event (prefix), hours, limit, offset. |
Cloud: /api/cloud/v1#
Instance paths contain the project ID and the region ID: /instances/{project}/{region}/{id}.
| Method | Path | Access | Description |
|---|---|---|---|
GET | /regions | any | Active regions. |
GET | /flavors | any | Active flavors with monthly_price_cents and hourly_price_cents. |
GET | /images | any | Active images. Query: region_id to show only images with a template in that region. |
GET | /quotas | any | limits and usage of the organization. |
POST | /pricing/instances | any | Price of a flavor with the customer's VAT. Body: {"flavor_id": 2}. |
GET, POST | /projects | any / resources | List projects, or create one (body name). |
PATCH, DELETE | /projects/{project} | resources | Rename (body name) or delete a project. |
GET, POST | /ssh_keys/{project} | any / resources | List keys, or add one (body name, public_key). |
DELETE | /ssh_keys/{project}/{id} | resources | Remove a key. |
GET | /instances/{project}/{region} | any | List instances. |
POST | /instances/{project}/{region} | resources | Create an instance. Returns 202 with instance and task. |
GET, DELETE | /instances/{project}/{region}/{id} | any / resources | Read or delete an instance. Delete returns 202 with the task. |
POST | /instances/{project}/{region}/{id}/action | resources | Power action. Body: {"action": "start"}. Actions: start, stop, shutdown, reboot. |
GET, PUT | /instances/{project}/{region}/{id}/firewall | any / resources | Read or replace the firewall rules. |
GET | /instances/{project}/{region}/{id}/metrics | any | Graph data. Query: timeframe = hour, day, week or month. |
GET, POST | /instances/{project}/{region}/{id}/snapshots | any / resources | List snapshots, or take one (body name, optional description). |
DELETE | /instances/{project}/{region}/{id}/snapshots/{snapshot} | resources | Delete a snapshot. |
POST | /instances/{project}/{region}/{id}/snapshots/{snapshot}/rollback | resources | Restore a snapshot. |
GET, POST | /instances/{project}/{region}/{id}/volumes | any / resources | List volumes, or add one (body name, size_gb). |
DELETE | /instances/{project}/{region}/{id}/volumes/{volume} | resources | Delete a volume. |
GET | /instances/{project}/{region}/{id}/ddos | any | protected, under_attack and the last 20 attacks. |
GET | /tasks | any | Tasks of the organization. Query: active=true, limit. |
GET | /tasks/{id} | any | One task. |
Body for creating an instance:
| Field | Rules |
|---|---|
name | Up to 63 characters. |
flavor_id | An active flavor. |
image_id | An active image with a template in the region. |
ssh_key_ids | IDs of SSH keys in the project. |
password | 12 to 128 characters. |
You need at least one SSH key or a password.
Body for the firewall:
{
"rules": [
{ "direction": "in", "action": "accept", "protocol": "tcp", "port": "22", "source": "198.51.100.0/24", "comment": "office ssh" },
{ "direction": "in", "action": "accept", "protocol": "tcp", "port": "443" },
{ "direction": "out", "action": "drop", "protocol": "tcp", "port": "25" }
]
}
direction is in (default) or out. action is accept (default) or drop. protocol is tcp, udp, icmp, or empty for any. port is a port or a range like 8000:8100, only for TCP and UDP. source is an IP address or network. Up to 50 rules.
Hosting: /api/hosting/v1#
| Method | Path | Access | Description |
|---|---|---|---|
GET | /plans | any | Active plans with features, price and needs_domain. |
GET | /services | any | Services of the organization. |
POST | /services | resources | Order. Body: plan_id, label, and domain when the plan needs one. Returns 202 with service and task. |
GET | /services/{id} | any | One service. |
DELETE | /services/{id} | resources | Cancel the service. Returns 202 with the task. |
POST | /services/{id}/login | resources | One-click sign-in. Returns {"url": "..."}. |
GET | /services/{id}/credentials | resources | Returns username and password. |
Game servers: /api/hosting/v1/services/{id}/game#
These endpoints work for Pterodactyl services when the provider has set a Client API key. Responses use the same JSON shape as the Pterodactyl Client API (object, attributes, data).
| Method | Path | Description |
|---|---|---|
GET | /game | Server details and current resource use. |
POST | /game/power | Body {"signal": "start" | "stop" | "restart" | "kill"}. |
POST | /game/command | Body {"command": "say hello"}. |
POST | /game/console | Returns a single-use websocket URL that is valid for 60 seconds. Connect with the Origin of the portal. |
GET | /game/files?directory=/ | List a folder. |
GET, PUT | /game/files/contents?file=/server.properties | Read or write a text file. PUT takes {"content": "..."}. |
POST | /game/files/upload?directory=/plugins | Multipart upload with the field files, up to 1 GiB. |
POST | /game/files/download | Body {"file": "/world.zip"}. Returns a single-use download URL. |
POST | /game/files/rename, /copy, /delete, /folder, /compress, /decompress, /pull | File operations. |
GET, POST | /game/backups | List or create backups. |
POST | /game/backups/{uuid}/lock, /restore, /download | Lock, restore or download a backup. |
DELETE | /game/backups/{uuid} | Delete a backup. |
GET, POST | /game/databases | List or create databases. |
POST | /game/databases/{id}/rotate-password | Set a new password. |
DELETE | /game/databases/{id} | Delete a database. |
GET, POST | /game/schedules | List or create schedules. |
GET, POST, DELETE | /game/schedules/{id} | Read, update or delete a schedule. |
POST | /game/schedules/{id}/execute | Run a schedule now. |
POST | /game/schedules/{id}/tasks | Add a task. |
POST, DELETE | /game/schedules/{id}/tasks/{task} | Update or delete a task. |
GET, POST | /game/allocations | List ports or add one. |
POST, DELETE | /game/allocations/{id} | Set notes or remove a port. |
POST | /game/allocations/{id}/primary | Make a port the primary port. |
GET | /game/startup | Startup command, variables and Docker images. |
PUT | /game/startup/variable | Body {"key": "MINECRAFT_VERSION", "value": "1.21.11"}. |
PUT | /game/docker-image | Body {"docker_image": "..."}. |
POST | /game/rename, /game/reinstall | Rename or reinstall the server. |
GET | /game/activity | Recent activity. |
Minecraft: /api/hosting/v1#
| Method | Path | Description |
|---|---|---|
GET | /minecraft/versions?flavor=paper | Released versions for paper, purpur, fabric or vanilla. |
GET | /services/{id}/minecraft | Current type and version, the free address, and the running installation. |
POST | /services/{id}/minecraft/version | Body {"flavor": "paper", "version": "1.21.11"}. Runs in the background. |
GET | /services/{id}/minecraft/search?kind=addon&query=luckperms | Search Modrinth. kind is addon or modpack. |
POST | /services/{id}/minecraft/install | Body {"project": "luckperms"}. Installs the newest compatible file. |
POST | /services/{id}/minecraft/modpack | Body {"project": "...", "clean": true}. Runs in the background. |
PUT, DELETE | /services/{id}/minecraft/subdomain | Claim or remove a free address. PUT takes {"name": "survival"}. |
Domains: /api/domains/v1#
| Method | Path | Access | Description |
|---|---|---|---|
GET | /tlds | any | Active extensions with prices. |
POST | /check | any | Availability. Body: {"query": "bakery"} or {"query": "bakery.com"}. |
GET | /domains | any | Domains of the organization. |
POST | /domains | billing | Register. Body: name, years (1 to 10, default 1), optional nameservers. Returns 202 with domain and task. |
GET | /domains/{id} | any | One domain. |
PUT | /domains/{id} | resources | Body: nameservers (2 to 6) and auto_renew. |
DNS: /api/dns/v1#
| Method | Path | Access | Description |
|---|---|---|---|
GET, POST | /zones | any / resources | List zones, or add one (body name). |
GET | /zones/{id} | any | The zone with nameservers and all rrsets. |
DELETE | /zones/{id} | resources | Delete the zone. |
PUT | /zones/{id}/rrsets | resources | Create or replace a record set. |
DELETE | /zones/{id}/rrsets?name=www&type=A | resources | Delete a record set. |
Body for a record set:
{ "name": "www", "type": "A", "ttl": 3600, "records": ["203.0.113.10", "203.0.113.11"] }
name is @ for the zone itself, a label, or a full name inside the zone. type is A, AAAA, CNAME, MX, TXT, NS, SRV or CAA. ttl is 60 to 604,800 (default 3,600). records has 1 to 50 values.
Billing: /api/billing/v1#
| Method | Path | Access | Description |
|---|---|---|---|
GET | /account | billing | Balance, available payment methods, minimum top-up, bank details and open invoices. |
GET | /usage | billing | Usage of a month with VAT estimate. Query: month as YYYY-MM, default the current month. |
GET | /transactions | billing | The credit ledger. |
GET | /invoices | billing | Invoices. Query: status (open, paid, void). |
GET | /invoices/{id} | billing | Invoice with lines, customer and seller. |
GET | /payments | billing | Payments. |
POST | /payments | billing | Start a payment. Body: provider and either invoice_id or amount_cents. Returns payment, checkout_url and reference. |
GET | /payments/{id} | billing | One payment. Also asks the provider for the latest status. |
POST | /webhooks/{provider} | public | Webhooks for mollie, stripe and paypal. See Billing. |
provider is mollie, stripe, paypal or bank_transfer, and must be one of the methods from /account.
Support: /api/support/v1#
| Method | Path | Access | Description |
|---|---|---|---|
GET | /tickets | any | Tickets of the organization. Query: status (active, open, answered, closed), limit, offset. |
POST | /tickets | user | Open a ticket. Body: subject, body, optional category and priority. |
GET | /tickets/{id} | any | The ticket with its messages. |
POST | /tickets/{id}/replies | user | Reply. Body: {"body": "..."}. |
POST | /tickets/{id}/close | any | Close the ticket. |
category is general (default), technical, billing, sales or abuse. priority is low, normal (default), high or urgent.
Network: /api/network/v1#
| Method | Path | Access | Description |
|---|---|---|---|
POST | /ddos/events | signed | Events from a DDoS detector. See Network protection. |
Back office: /api/admin#
All endpoints need the access token of a staff user. The last column shows the staff roles.
| Method | Path | Staff roles | Description |
|---|---|---|---|
GET, PUT | /platform/settings | owner, admin | Brand and access settings. |
GET, POST | /cloud/regions | owner, admin | List or create regions. |
GET, PATCH | /cloud/regions/{id} | owner, admin | Read or update a region. |
POST | /cloud/regions/{id}/check | owner, admin | Test the cluster connection. |
GET, PUT | /cloud/regions/{id}/images | owner, admin | Template VM IDs per image. |
GET, POST | /cloud/regions/{id}/addresses | owner, admin | IPv4 pool. |
DELETE | /cloud/regions/{id}/addresses/{address} | owner, admin | Remove a free address. |
GET, POST | /cloud/flavors | owner, admin | List or create flavors. |
PATCH | /cloud/flavors/{id} | owner, admin | Update a flavor. |
GET, POST | /cloud/images | owner, admin | List or create images. |
PATCH | /cloud/images/{id} | owner, admin | Update an image. |
GET, PUT | /cloud/settings | owner, admin | Limits and volume price. |
GET, PUT | /network/settings | owner, admin | DDoS settings and secret rotation. |
GET | /network/attacks | owner, admin, support | The last 200 attacks. |
GET, POST | /hosting/servers | owner, admin | List or add panel servers. |
PUT | /hosting/servers/{id} | owner, admin | Update a panel server. |
POST | /hosting/servers/{id}/check | owner, admin | Test the panel connection. |
GET, POST | /hosting/plans | owner, admin | List or add plans. |
PUT | /hosting/plans/{id} | owner, admin | Update a plan. |
GET | /hosting/services | owner, admin, support | Services of all organizations. |
POST | /hosting/services/{id}/{action} | owner, admin, support | suspend, unsuspend or terminate. |
GET, PUT | /domains/settings | owner, admin | Registrar settings. |
GET | /domains/tlds | owner, admin | Extensions and prices. |
PUT, DELETE | /domains/tlds/{tld} | owner, admin | Save or remove an extension. |
GET | /domains/domains | owner, admin, support | Domains of all organizations. |
POST | /domains/domains/{id}/activate | owner, admin, support | Mark a pending domain as registered. |
GET, PUT | /dns/settings | owner, admin | DNS hosting settings. |
GET, PUT | /billing/settings | owner, admin | Billing settings and payment providers. |
GET | /billing/invoices | owner, admin, billing | Invoices of all organizations. Query: status, client_id, limit, offset. |
GET | /billing/invoices/{id} | owner, admin, billing | One invoice. |
POST | /billing/invoices/{id}/paid | owner, admin, billing | Mark as paid. |
POST | /billing/invoices/{id}/void | owner, admin, billing | Void. |
POST | /billing/clients/{id}/balance | owner, admin, billing | Adjust credit. Body: amount_cents, description. |
POST | /billing/run | owner, admin | Run metering, invoicing, reminders and suspension now. |
GET | /support/tickets | all staff | The helpdesk queue. Query: status, mine, limit, offset. |
GET, PUT | /support/tickets/{id} | all staff | Read a ticket, or change status, priority and assigned_to. |
POST | /support/tickets/{id}/replies | all staff | Reply or add an internal note. Body: body, internal. |
Examples#
The examples use an API token in $STACKLANE_TOKEN, project 1 and region 2.
List the regions and flavors#
curl https://panel.example.com/api/cloud/v1/regions \
-H "Authorization: APIKey $STACKLANE_TOKEN"
curl https://panel.example.com/api/cloud/v1/flavors \
-H "Authorization: APIKey $STACKLANE_TOKEN"
Create an instance and wait for it#
curl -X POST https://panel.example.com/api/cloud/v1/instances/1/2 \
-H "Authorization: APIKey $STACKLANE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "web-1", "flavor_id": 3, "image_id": 1, "ssh_key_ids": [4]}'
Take task.id from the response and poll it:
curl https://panel.example.com/api/cloud/v1/tasks/<task-id> \
-H "Authorization: APIKey $STACKLANE_TOKEN"
When the state is finished, read the instance to get its address:
curl https://panel.example.com/api/cloud/v1/instances/1/2/<instance-id> \
-H "Authorization: APIKey $STACKLANE_TOKEN"
Reboot an instance#
curl -X POST https://panel.example.com/api/cloud/v1/instances/1/2/<instance-id>/action \
-H "Authorization: APIKey $STACKLANE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"action": "reboot"}'
Set a DNS record#
curl -X PUT https://panel.example.com/api/dns/v1/zones/<zone-id>/rrsets \
-H "Authorization: APIKey $STACKLANE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "@", "type": "MX", "ttl": 3600, "records": ["10 mx1.example.net", "20 mx2.example.net"]}'
Delete a DNS record#
curl -X DELETE 'https://panel.example.com/api/dns/v1/zones/<zone-id>/rrsets?name=www&type=A' \
-H "Authorization: APIKey $STACKLANE_TOKEN"
Add credit#
curl -X POST https://panel.example.com/api/billing/v1/payments \
-H "Authorization: APIKey $STACKLANE_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"provider": "mollie", "amount_cents": 5000}'
Open the checkout_url from the response in a browser to pay. The token needs the administrator or billing role.
Read open invoices#
curl 'https://panel.example.com/api/billing/v1/invoices?status=open&limit=50' \
-H "Authorization: APIKey $STACKLANE_TOKEN"