Every route in the App API: what it takes, what it returns and who can call it.

The API is at https://api.rustward.com. Authenticate with a workspace API token (create one on the API tokens page of your workspace settings) in the Authorization header. Requests and responses are JSON, and errors come back as { "error": "…" } with a 4xx status.

curl https://api.rustward.com/servers \
  -H "Authorization: Bearer YOUR_TOKEN"

Each route shows who can call it:

  • API tokens: a token, which always acts in its own workspace, or a signed-in session, which picks one with the Workspace header (else its personal workspace). The scope shown (such as servers:write) is the one the token needs.
  • Signed-in only: the dashboard only, not API tokens.
  • No sign-in needed: anyone, e.g. to sign in.

The spec is generated from the API itself: download openapi.yaml for client generators, or try requests in the API explorer.

Auth

Signing in by emailed link, and signing out.

POST /auth/sign-in/email

Sign in or sign up inline by email

New address: opens an unverified account and sets the session cookie. Existing address: emails a sign-in code (answer `auth: "code"`); redeem it with /auth/sign-in/code.

No sign-in needed

Request body

  • email string required min length 3max length 254

Responses

200 Signed in, or a code was sent
  • Option 1 object
  • auth string required
  • created boolean required

    True when a new (unverified) account was just opened

  • Option 2 object
  • auth string required
  • email string required
  • notice string

    Set when a code was already on its way

  • 400 Not an email address
  • 502 The email could not be sent
POST /auth/sign-in/code

Sign in with an emailed code

Checks the 6-digit code from /auth/sign-in/email and sets the session cookie. Each code allows 5 attempts.

No sign-in needed

Request body

  • email string required min length 3max length 254
  • code string required min length 1max length 16

Responses

200 Signed in
  • ok boolean required
  • 400 Wrong, expired or used-up code
POST /auth/logout

Sign out

Ends the session and clears its cookie. Succeeds when already signed out.

No sign-in needed

Responses

200 Signed out
  • ok boolean required

Profile

Your own account.

GET /profile

Get the profile

Signed-in only

Responses

200 Success
  • user object required
  • id string required
  • name string required
  • email string required
  • avatarUrl string | null required
PATCH /profile

Update the profile

Updates the signed-in user's name and avatar URL. An empty avatarUrl clears it.

Signed-in only

Request body

  • name string required min length 1max length 100

    Display name; surrounding whitespace is trimmed

  • avatarUrl one of

    URL of the avatar image; null, empty or omitted clears it

  • Option 1 string | null
  • Option 2 string

Responses

200 Success
  • user object required
  • id string required
  • name string required
  • email string required
  • avatarUrl string | null required
  • 400 Invalid request
GET /sessions

List signed-in sessions

Every device signed in to your account, the current one first. Needs a signed-in session.

Signed-in only

Responses

200 Your sessions
  • items array<SignedInSession> required
  • id string required

    A reference for this session (not its cookie or its stored hash)

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    When you signed in

  • expiresAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    Extended while the session is in use

  • current boolean required

    The session making this request

  • 401 Not signed in
POST /sessions/revoke-others

Sign out of all other devices

Ends every session except the one making this request. Needs a signed-in session.

Signed-in only

Responses

200 How many sessions ended
  • ok boolean required
  • count integer required min -9007199254740991max 9007199254740991
  • 401 Not signed in
DELETE /sessions/{id}

Sign out a device

Ends one of your other sessions. To end this one, use logout. Needs a signed-in session.

Signed-in only

Parameters

  • id path · string required pattern ^[0-9a-f]{32}$

Responses

200 Signed out
  • ok boolean required
  • 400 This is the current session
  • 401 Not signed in
  • 404 No such session

Currency

Exchange rates for showing prices in other currencies.

GET /currency/rates

USD exchange rates for the currencies we sell in

At most an hour old. When the rate service is down, only USD is returned and `stale` is true.

No sign-in needed

Responses

200 Rate table
  • base string required
  • rates object required

    Multipliers against one USD, e.g. { "EUR": 0.92 }

  • fetchedAt string required
  • stale boolean required

    True when the rate service was unreachable and only USD is real

Orders

Ordering and paying for servers.

POST /orders

Order a server

Validates the order against the live catalogue and locks its prices in. Prepaid workspaces get an invoice and payment is attempted; postpaid ones are built straight away.

Signed-in only

Request body

  • package string required min length 1max length 100

    Package slug

  • location string required min length 1max length 100

    Host group slug

  • image string required min length 1max length 100

    OS image slug

  • hostname string required min length 1max length 253
  • sshPublicKey string | null max length 16384
  • sshKeyIds array<string> max 20 itemsdefault []

    Saved SSH keys in the workspace, for signed-in buyers

  • workspaceId string required min length 1max length 64
  • currency string default "USD"

    The currency the page showed prices in; the order is charged in it

    USDEURGBPCADAUDNZDSEKPLNBRLJPY

Responses

201 Order placed
  • orderId string required
  • status string required

    completedawaiting_payment

  • 400 A field is invalid (see `fields`), or the order breaks a rule (limits, unpaid balance, missing rate)
POST /orders/{id}/pay

Pay an order's open invoice

Retries payment for an order awaiting payment. Builds the server once it succeeds.

Signed-in only

Parameters

  • id path · string required min length 1max length 64

Responses

200 Paid
  • ok boolean required
  • 400 Nothing to pay, or payment failed
  • 404 No such order of yours

Workspaces

Your workspaces: personal and team.

GET /workspaces

List your workspaces

Your personal workspace first, then your teams, with your role in each. Needs a signed-in user.

Signed-in only

Responses

200 Your workspaces
  • items array<MyWorkspace> required
  • id string required

    Use this (or the slug) as `:workspaceId` in other routes

  • slug string required
  • name string required
  • type string required

    PERSONALTEAM

  • role string required

    OWNERADMINBILLINGMEMBER

  • 401 Not signed in
POST /workspaces

Create a team

A new team workspace with you as its owner, billed to your email address until you change it. Its slug comes from the name, with a random ending if it's taken. Needs a signed-in user.

Signed-in only

Request body

  • name string required min length 1max length 100

    The team's name. Its slug (web address) is made from it.

Responses

201 Created
  • id string required

    Use this (or the slug) as `:workspaceId` in other routes

  • slug string required
  • name string required
  • type string required

    PERSONALTEAM

  • role string required

    OWNERADMINBILLINGMEMBER

  • 400 No name
  • 401 Not signed in
  • 409 You own too many teams
GET /workspaces/{workspaceId}/overview

Get the overview

Server counts and the newest servers (with `servers:read`), what needs attention, the monthly cost and credit (with `billing:read`), and recent activity (with `audit:read`). Parts the caller may not see are null. Any member or token of the workspace can call it.

API tokens

Parameters

  • workspaceId path · string required min length 1max length 64

Responses

200 The overview
  • servers object | null required

    Null without `servers:read`

  • total integer required min -9007199254740991max 9007199254740991
  • counts object required
  • items array<object> required

    Up to 6, newest first

  • id string required
  • name string required
  • status string required
  • state string required

    runningstoppedsetting_upbusyrescuesuspendederror

  • ipv4 string | null required
  • plan string required
  • region string required
  • billing object | null required

    Null without `billing:read`

  • status string | null required

    ACTIVEPAST_DUESUSPENDEDCLOSED

  • mode string | null required

    PREPAID_MONTHLYPOSTPAID_USAGE

  • currency string required
  • creditBalanceCents integer required min -9007199254740991max 9007199254740991
  • monthly array<object> required

    What active subscriptions renew at each month, per currency

  • currency string required
  • cents integer required min -9007199254740991max 9007199254740991
  • attention array<AttentionItem> required

    Things that need a look; only those the caller's permissions cover

  • Option 1 object
  • kind string required

    server_errorserver_suspended

  • serverId string required
  • serverName string required
  • reason string | null required
  • Option 2 object
  • kind string required
  • invoiceId string required
  • number string | null required
  • amountDueCents integer required min -9007199254740991max 9007199254740991
  • currency string required
  • dueAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • overdue boolean required
  • Option 3 object
  • kind string required

    billing_past_duebilling_suspended

  • Option 4 object
  • kind string required
  • serverId string required
  • serverName string required
  • snapshotName string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • activity array<ActivityEntry> | null required

    The latest 8 entries; null without `audit:read`

  • id string required
  • action string required

    Dotted action, e.g. `server.start`

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • actor object required
  • type string required

    usertokenstaffsystem

  • name string required

    A member's name, "API token <name>", "Support" or "Automatic"

  • email string | null required
  • summary string required

    What they did, to follow the actor's name

  • targetType string required
  • targetId string required
  • href string | null required

    The dashboard page for what it happened to, when it still exists

  • ipAddress string | null required

    Only for members' and API tokens' actions

  • metadata object | null required
  • 400 The request failed validation
  • 404 No such workspace
PATCH /workspaces/{workspaceId}

Rename a team

Its slug, and so its URLs, stay the same. Personal workspaces can't be renamed. Needs `workspace:write` and a signed-in user.

Signed-in only workspace:write

Parameters

  • workspaceId path · string required min length 1max length 64

Request body

  • name string required min length 1max length 100

Responses

200 Renamed
  • id string required
  • slug string required
  • name string required
  • type string required

    PERSONALTEAM

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 A personal workspace, or no name
  • 403 Not allowed
  • 404 No such workspace
DELETE /workspaces/{workspaceId}

Delete a team

Refused while it has servers, unpaid invoices or active subscriptions. Its API tokens and pending invites stop working. Personal workspaces can't be deleted. Needs `workspace:delete` (owners only) and a signed-in user.

Signed-in only workspace:delete

Parameters

  • workspaceId path · string required min length 1max length 64

Request body

  • confirmName string required max length 200

    The workspace's current name, typed to confirm

Responses

200 Deleted
  • ok boolean required
  • 400 A personal workspace, or the name doesn't match
  • 403 Not allowed
  • 404 No such workspace
  • 409 Something still needs dealing with first

Servers

Servers in a workspace: power, rebuild, network, snapshots.

GET /servers/deploy-options

What you can deploy

Plans with their locations, OS images, the workspace's limits and saved SSH keys, and how it's billed. Needs `servers:create`.

API tokens servers:create

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Responses

200 Options
  • packages array<object> required
  • slug string required
  • name string required
  • vcpus integer required min -9007199254740991max 9007199254740991
  • memoryMb integer required min -9007199254740991max 9007199254740991
  • diskGb integer required min -9007199254740991max 9007199254740991
  • trafficGb integer | null required min -9007199254740991max 9007199254740991
  • monthlyPriceCents integer required min -9007199254740991max 9007199254740991

    USD cents

  • ipv4MonthlyCents integer required min -9007199254740991max 9007199254740991
  • backupMonthlyPriceCents integer required min -9007199254740991max 9007199254740991
  • locations array<object> required
  • slug string required
  • name string required
  • imageGroups array<string> | null required

    Allowed image groups; null = all

  • imageGroups array<object> required
  • slug string required
  • name string required
  • icon string | null required

    Logo key, e.g. ubuntu

  • images array<object> required
  • slug string required
  • name string required
  • minDiskGb integer required min -9007199254740991max 9007199254740991
  • limits object required
  • servers object required
  • used integer required min -9007199254740991max 9007199254740991
  • max integer required min -9007199254740991max 9007199254740991
  • vcpus object required
  • used integer required min -9007199254740991max 9007199254740991
  • max integer required min -9007199254740991max 9007199254740991
  • billing object required
  • mode string required

    PREPAID_MONTHLYPOSTPAID_USAGE

  • status string required

    ACTIVEPAST_DUESUSPENDEDCLOSED

  • currency string required
  • creditBalanceCents integer required min -9007199254740991max 9007199254740991
  • paymentMethod object | null required
  • type string required
  • brand string | null required
  • last4 string | null required
  • expMonth integer | null required min -9007199254740991max 9007199254740991
  • expYear integer | null required min -9007199254740991max 9007199254740991
  • sshKeys array<object> required
  • id string required
  • name string required
  • fingerprint string required
  • type string required
  • 403 Not allowed
GET /servers

List servers

Newest first. Destroyed servers are left out. Needs `servers:read`.

API tokens servers:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • q query · string max length 100

    Name, hostname or the start of an IP address

  • status query · string

    `building` and `setting_up` are the same group

    runningstoppedbuildingsetting_upbusyrescuesuspendederror

Responses

200 The servers
  • items array<Server> required
  • id string required
  • name string required
  • hostname string required
  • status string required

    PENDINGPROVISIONINGRUNNINGSTOPPEDSTARTINGSTOPPINGREBOOTINGRESIZINGREBUILDINGRESTORINGMIGRATINGRESCUESUSPENDEDERRORDESTROYINGDESTROYED

  • statusReason string | null required

    Why it is suspended, or the last error

  • desiredPowerState string required

    RUNNINGSTOPPED

  • ipv4 array<string> required
  • ipv6 array<string> required

    Routed /64 networks

  • hostId string | null required
  • backupsEnabled boolean required
  • activeSnapshotId string | null required
  • deletionProtection boolean required
  • vcpus integer required min -9007199254740991max 9007199254740991
  • memoryMb integer required min -9007199254740991max 9007199254740991
  • diskGb integer required min -9007199254740991max 9007199254740991
  • package object required
  • id string required
  • slug string required
  • name string required
  • image object | null required
  • id string required
  • name string required
  • distribution string required
  • version string required
  • defaultUser string required
  • windows boolean required
  • region object required
  • slug string required
  • name string required
  • city string | null required
  • country string required
  • location string required
  • traffic object required
  • usedBytes number required
  • limitGb integer | null required min -9007199254740991max 9007199254740991

    Monthly allowance; null = unlimited

  • throttleMbps integer | null required min -9007199254740991max 9007199254740991
  • throttled boolean required
  • periodStart string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • measuredAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • operation object | null required

    The action queued or in progress, if any

  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such workspace
POST /servers

Deploy a server

Places an order billed to the workspace, with prices locked in. Prepaid: an invoice is issued and charged; once paid, the server is built (`serverId` is set). Postpaid: the server is built at once. Needs `servers:create` (and `ssh_keys:read` to choose saved keys).

API tokens servers:create

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Request body

  • package string required min length 1max length 100

    Package slug, e.g. nvme-2 (see GET /servers/deploy-options)

  • location string required min length 1max length 100

    Location slug, e.g. dallas

  • image string required min length 1max length 100

    OS image slug, e.g. ubuntu-24-04-x64

  • hostname string required min length 1max length 253

    Also the server’s name

  • sshKeyIds array<string> max 20 itemsdefault []

    Saved SSH keys in the workspace

  • sshPublicKey string | null max length 16384

    A new public key to add (saved to the workspace too)

  • currency string default "USD"

    Prepaid orders are charged in this currency. Postpaid accounts use their own.

    USDEURGBPCADAUDNZDSEKPLNBRLJPY

Responses

201 Order placed
  • orderId string required
  • status string required

    `completed`: the server is being built. `awaiting_payment`: pay invoiceId first.

    completedawaiting_payment

  • serverId string | null required

    Set once the order is paid (or at once, for postpaid)

  • invoiceId string | null required
  • 400 A field is invalid (see `fields`)
  • 403 Not allowed
  • 409 Over a limit, an unpaid balance, an unpaid order for the same name, or an SSH key not in the workspace
GET /servers/{id}

Get a server

With its network interfaces, and its price when you can see billing (`billing:read`). Needs `servers:read`.

API tokens servers:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The server
  • id string required
  • name string required
  • hostname string required
  • status string required

    PENDINGPROVISIONINGRUNNINGSTOPPEDSTARTINGSTOPPINGREBOOTINGRESIZINGREBUILDINGRESTORINGMIGRATINGRESCUESUSPENDEDERRORDESTROYINGDESTROYED

  • statusReason string | null required

    Why it is suspended, or the last error

  • desiredPowerState string required

    RUNNINGSTOPPED

  • ipv4 array<string> required
  • ipv6 array<string> required

    Routed /64 networks

  • hostId string | null required
  • backupsEnabled boolean required
  • activeSnapshotId string | null required
  • deletionProtection boolean required
  • vcpus integer required min -9007199254740991max 9007199254740991
  • memoryMb integer required min -9007199254740991max 9007199254740991
  • diskGb integer required min -9007199254740991max 9007199254740991
  • package object required
  • id string required
  • slug string required
  • name string required
  • image object | null required
  • id string required
  • name string required
  • distribution string required
  • version string required
  • defaultUser string required
  • windows boolean required
  • region object required
  • slug string required
  • name string required
  • city string | null required
  • country string required
  • location string required
  • traffic object required
  • usedBytes number required
  • limitGb integer | null required min -9007199254740991max 9007199254740991

    Monthly allowance; null = unlimited

  • throttleMbps integer | null required min -9007199254740991max 9007199254740991
  • throttled boolean required
  • periodStart string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • measuredAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • operation object | null required

    The action queued or in progress, if any

  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • interfaces array<object> required
  • id string required
  • name string required
  • macAddress string required
  • addresses array<object> required
  • id string required
  • family string required

    V4V6

  • address string required
  • prefixLength integer required min -9007199254740991max 9007199254740991
  • gateway string required
  • ptrRecord string | null required

    Reverse DNS name

  • pricing one of | null required

    What it costs, in minor units; null without `billing:read`

  • Option 1 object
  • mode string required
  • currency string required
  • serverCents integer required min -9007199254740991max 9007199254740991
  • ipv4Cents integer required min -9007199254740991max 9007199254740991
  • backupCents integer required min -9007199254740991max 9007199254740991
  • totalCents integer required min -9007199254740991max 9007199254740991
  • renewsAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • Option 2 object
  • mode string required
  • currency string required
  • hourlyCents number required
  • monthlyEstimateCents integer required min -9007199254740991max 9007199254740991
  • serverCents integer required min -9007199254740991max 9007199254740991
  • ipv4Cents integer required min -9007199254740991max 9007199254740991
  • backupCents integer required min -9007199254740991max 9007199254740991
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
PATCH /servers/{id}

Rename a server or change its deletion protection

Names are unique among the workspace's servers, ignoring case. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • name string max length 200
  • deletionProtection boolean

Responses

200 Updated
  • id string required
  • name string required
  • hostname string required
  • status string required

    PENDINGPROVISIONINGRUNNINGSTOPPEDSTARTINGSTOPPINGREBOOTINGRESIZINGREBUILDINGRESTORINGMIGRATINGRESCUESUSPENDEDERRORDESTROYINGDESTROYED

  • statusReason string | null required

    Why it is suspended, or the last error

  • desiredPowerState string required

    RUNNINGSTOPPED

  • ipv4 array<string> required
  • ipv6 array<string> required

    Routed /64 networks

  • hostId string | null required
  • backupsEnabled boolean required
  • activeSnapshotId string | null required
  • deletionProtection boolean required
  • vcpus integer required min -9007199254740991max 9007199254740991
  • memoryMb integer required min -9007199254740991max 9007199254740991
  • diskGb integer required min -9007199254740991max 9007199254740991
  • package object required
  • id string required
  • slug string required
  • name string required
  • image object | null required
  • id string required
  • name string required
  • distribution string required
  • version string required
  • defaultUser string required
  • windows boolean required
  • region object required
  • slug string required
  • name string required
  • city string | null required
  • country string required
  • location string required
  • traffic object required
  • usedBytes number required
  • limitGb integer | null required min -9007199254740991max 9007199254740991

    Monthly allowance; null = unlimited

  • throttleMbps integer | null required min -9007199254740991max 9007199254740991
  • throttled boolean required
  • periodStart string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • measuredAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • operation object | null required

    The action queued or in progress, if any

  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 Invalid name
  • 403 Not allowed
  • 404 No such server
  • 409 Name taken
POST /servers/{id}/start

Start a server

Queues a start. Refused while the server is suspended, being built or being destroyed. Send an `Idempotency-Key` header to make retries safe: a repeat with the same key returns the first action. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • force boolean

    Stop and reboot only: cut the power instead of asking the OS to shut down

Responses

202 Queued
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 Not possible in its current state, or busy
POST /servers/{id}/stop

Stop a server

Queues a shutdown: graceful unless `force` is true. Refused while the server is suspended, being built or being destroyed. Send an `Idempotency-Key` header to make retries safe: a repeat with the same key returns the first action. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • force boolean

    Stop and reboot only: cut the power instead of asking the OS to shut down

Responses

202 Queued
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 Not possible in its current state, or busy
POST /servers/{id}/reboot

Reboot a server

Queues a restart: graceful unless `force` is true. Refused while the server is suspended, being built or being destroyed. Send an `Idempotency-Key` header to make retries safe: a repeat with the same key returns the first action. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • force boolean

    Stop and reboot only: cut the power instead of asking the OS to shut down

Responses

202 Queued
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 Not possible in its current state, or busy
PATCH /servers/{id}/ip-addresses/{addressId}

Set reverse DNS for an address

The PTR record of one of the server's addresses. Empty or null clears it. Changes take a few minutes to show. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64
  • addressId path · string required min length 1max length 64

Request body

  • ptrRecord string | null required max length 253

    A hostname like mail.example.com; empty or null clears it

Responses

200 Updated
  • id string required
  • address string required
  • ptrRecord string | null required
  • 400 Not a hostname
  • 403 Not allowed
  • 404 No such server or address
GET /servers/{id}/rebuild-options

Images and SSH keys for a rebuild

Operating systems this server's plan and disk allow, and the workspace's SSH keys. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The options
  • currentImageId string | null required
  • images array<object> required
  • id string required
  • name string required
  • group string | null required
  • defaultUser string required
  • windows boolean required
  • sshKeys array<object> required
  • id string required
  • name string required
  • fingerprint string required
  • onServer boolean required

    Already on this server

  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
POST /servers/{id}/rebuild

Rebuild a server

Reinstalls it from an image with the given SSH keys, erasing its disk. Keeps its IP addresses. Refused while a snapshot is in place. Send an `Idempotency-Key` header to make retries safe: a repeat with the same key returns the first action. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • imageId string required min length 1max length 64
  • sshKeyIds array<string> max 50 itemsdefault []

Responses

202 Queued
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 Image or key not available
  • 403 Not allowed
  • 404 No such server
  • 409 Not possible in its current state, or busy
POST /servers/{id}/destroy

Destroy a server

Deletes the server and its disk, and stops billing for it. Its backups are kept. Refused while deletion protection is on. Send an `Idempotency-Key` header to make retries safe: a repeat with the same key returns the first action. Needs `servers:destroy`.

API tokens servers:destroy

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

202 Queued
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 Deletion protection is on, or busy
GET /servers/{id}/operations

A server's activity

Its last 100 actions, newest first, and changes made to it (those need `audit:read`; null without). Needs `servers:read`.

API tokens servers:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The activity
  • operations array<object> required
  • id string required
  • type string required

    CREATESTARTSTOPREBOOTRESIZEREBUILDDESTROYMIGRATESNAPSHOT_CREATESNAPSHOT_COMMITSNAPSHOT_REVERTBACKUP_CREATEBACKUP_RESTOREBACKUP_DELETEPROVISIONRESCUE_ENTERRESCUE_EXITMEDIA_MOUNTMEDIA_UNMOUNTAPPLY_LIMITS

  • status string required

    QUEUEDRUNNINGSUCCEEDEDFAILEDCANCELED

  • error string | null required

    Why it failed, when it did

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • startedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • finishedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • requestedBy string | null required

    A person's name, "API token <name>", or null for the platform itself

  • events array<object> | null required

    Changes to the server, from the activity log; null without `audit:read`

  • id string required
  • action string required
  • actor string | null required
  • metadata object | null required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
GET /servers/{serverId}/snapshots

A server's snapshots

The current snapshot, if any, and the last 50, newest first. Needs `servers:read`.

API tokens servers:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64

Responses

200 The snapshots
  • server object required
  • id string required
  • name string required
  • status string required
  • activeSnapshotId string | null required
  • activeOperation object | null required

    The server's action in progress, if any; other actions wait for it

  • id string required
  • type string required
  • status string required

    QUEUEDRUNNING

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • snapshots array<Snapshot> required
  • id string required
  • name string required
  • status string required

    CREATINGACTIVECOMMITTINGREVERTINGCOMMITTEDREVERTEDFAILED

  • sizeBytes integer | null required min -9007199254740991max 9007199254740991

    How much the layer has grown, when known

  • autoCommitAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    Kept automatically at this time

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • resolvedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    When it was kept or discarded

  • createdBy string | null required
  • active boolean required

    The server's current layer

  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
POST /servers/{serverId}/snapshots

Take a snapshot

Saves the disk as it is now; everything after goes into a separate layer that you then commit (keep) or revert (throw away). One at a time. Optionally commits itself after `autoCommitHours`. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64

Request body

  • name string max length 100

    Defaults to the server name and time

  • autoCommitHours integer | null min 1max 720

    Keep the changes automatically after this many hours

Responses

202 Queued
  • snapshotId string | null required
  • operationId string required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 A snapshot is already in place, or The server is busy with another action, or the request conflicts with its state
POST /servers/{serverId}/snapshots/{id}/commit

Keep the changes since a snapshot

Merges the layer into the disk and ends the snapshot. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64
  • id path · string required min length 1max length 64

Responses

202 Queued
  • operationId string required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server or snapshot
  • 409 Not active, or The server is busy with another action, or the request conflicts with its state
POST /servers/{serverId}/snapshots/{id}/revert

Go back to a snapshot

Throws away everything written since the snapshot. Needs `servers:write`.

API tokens servers:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64
  • id path · string required min length 1max length 64

Responses

202 Queued
  • operationId string required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server or snapshot
  • 409 Not active, or The server is busy with another action, or the request conflicts with its state

Backups

Backups of servers in a workspace.

GET /backups

List backups

Every backup in the workspace, newest first, including those of destroyed servers. Needs `backups:read`.

API tokens backups:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId query · string min length 1max length 64

    Only backups of this server

Responses

200 The backups
  • items array<Backup> required
  • id string required
  • name string required
  • kind string required

    SCHEDULEDMANUAL

  • status string required

    CREATINGAVAILABLEFAILEDDELETINGDELETED

  • sizeBytes integer | null required min -9007199254740991max 9007199254740991

    Known once the backup is AVAILABLE

  • minDiskGb integer required min -9007199254740991max 9007199254740991

    Smallest disk this backup can be restored to

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • image string | null required

    OS image the server was built from

  • server object | null required

    The server it was taken from; null once that server is destroyed

  • id string required
  • name string required
  • formerServerName string | null required

    Name of the destroyed server it came from

  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such workspace
DELETE /backups/{id}

Delete a backup

Marks it DELETING; it is removed from storage shortly after. Needs `backups:write`.

API tokens backups:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 Being deleted
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such backup
  • 409 Still being taken, already deleting, or The server is busy with another action, or the request conflicts with its state
POST /backups/{id}/restore

Restore a backup onto a server

Replaces the server's disk with the backup; anything written since is lost. The server must be in the backup's location, have at least `minDiskGb` of disk, and have no snapshot in place. Needs `backups:write`.

API tokens backups:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • serverId string required min length 1max length 64

    Server to restore onto; its disk is replaced

Responses

202 Queued
  • operationId string required
  • 400 Disk too small or wrong location
  • 403 Not allowed
  • 404 No such backup or server
  • 409 The server is busy with another action, or the request conflicts with its state
GET /servers/{serverId}/backups

A server's backups

Its backups, newest first, and any action in progress. Needs `backups:read`.

API tokens backups:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64

Responses

200 Backups
  • server object required
  • id string required
  • name string required
  • status string required
  • diskGb integer required min -9007199254740991max 9007199254740991
  • hasActiveSnapshot boolean required
  • activeOperation object | null required

    The server's action in progress, if any; other actions wait for it

  • id string required
  • type string required
  • status string required

    QUEUEDRUNNING

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • backups array<Backup> required
  • id string required
  • name string required
  • kind string required

    SCHEDULEDMANUAL

  • status string required

    CREATINGAVAILABLEFAILEDDELETINGDELETED

  • sizeBytes integer | null required min -9007199254740991max 9007199254740991

    Known once the backup is AVAILABLE

  • minDiskGb integer required min -9007199254740991max 9007199254740991

    Smallest disk this backup can be restored to

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • image string | null required

    OS image the server was built from

  • server object | null required

    The server it was taken from; null once that server is destroyed

  • id string required
  • name string required
  • formerServerName string | null required

    Name of the destroyed server it came from

  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
POST /servers/{serverId}/backups

Back up a server now

Takes a manual backup, which counts toward the same retention as automatic ones. Not while a snapshot is in place. Needs `backups:write`.

API tokens backups:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • serverId path · string required min length 1max length 64

Request body

  • name string max length 100

    Defaults to the server name and time

Responses

202 Queued
  • backupId string | null required
  • operationId string required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 The server is busy with another action, or the request conflicts with its state

SSH keys

Public keys added to new servers.

GET /ssh-keys

List SSH keys

Newest first. Needs `ssh_keys:read`.

API tokens ssh_keys:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Responses

200 The keys
  • items array<SshKey> required
  • id string required
  • name string required
  • fingerprint string required

    SHA256 fingerprint, as `ssh-keygen -lf` prints it

  • type string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdBy string | null required
  • serverCount integer required min -9007199254740991max 9007199254740991

    Servers built with this key

  • 403 Not allowed
  • 404 No such workspace
POST /ssh-keys

Add an SSH key

Offered when deploying or rebuilding a server. Needs `ssh_keys:write`.

API tokens ssh_keys:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Request body

  • name string max length 100

    Defaults to the key's comment

  • publicKey string required min length 1max length 16384

    One line from a .pub file

Responses

201 Added
  • id string required
  • name string required
  • fingerprint string required

    SHA256 fingerprint, as `ssh-keygen -lf` prints it

  • type string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdBy string | null required
  • serverCount integer required min -9007199254740991max 9007199254740991

    Servers built with this key

  • 400 Not a public key
  • 403 Not allowed
  • 409 Already added
DELETE /ssh-keys/{id}

Remove an SSH key

Servers already built with it keep it. Needs `ssh_keys:write`.

API tokens ssh_keys:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 Removed
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such key

Billing

Invoices, subscriptions and billing details.

GET /billing

Get the billing overview

Billing mode and status, billing details, credit balance, what is due now, upcoming renewals, and (pay as you go) an estimate of usage so far this cycle. Needs `billing:read`.

API tokens billing:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Responses

200 The overview
  • account object | null required

    Null until the workspace first orders or saves billing details

  • billingEmail string required

    Where invoices and receipts are sent

  • legalName string | null required
  • addressLine1 string | null required
  • addressLine2 string | null required
  • city string | null required
  • region string | null required

    State or province

  • postalCode string | null required
  • country string | null required

    ISO 3166-1 alpha-2

  • taxStatus string required

    TAXABLEEXEMPTREVERSE_CHARGE

  • taxId string | null required
  • taxIdType string | null required
  • taxIdVerifiedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • id string required
  • mode string required

    PREPAID_MONTHLY: each server is charged a month ahead. POSTPAID_USAGE: hours are invoiced monthly in arrears.

    PREPAID_MONTHLYPOSTPAID_USAGE

  • status string required

    ACTIVEPAST_DUESUSPENDEDCLOSED

  • currency string required

    Lowercase ISO 4217 code

  • creditBalanceCents integer required min -9007199254740991max 9007199254740991
  • paymentTermsDays integer required min -9007199254740991max 9007199254740991
  • usageLimitCents integer | null required min -9007199254740991max 9007199254740991
  • paymentsEnabled boolean required

    Whether invoices can be paid online now

  • amountDue array<object> required
  • currency string required

    Lowercase ISO 4217 code

  • cents integer required min -9007199254740991max 9007199254740991
  • count integer required min -9007199254740991max 9007199254740991

    Open invoices

  • overdue integer required min -9007199254740991max 9007199254740991

    Open invoices past their due date

  • subscriptions array<object> required
  • id string required
  • name string | null required
  • status string required

    ACTIVEPAST_DUECANCELED

  • currency string required

    Lowercase ISO 4217 code

  • currentPeriodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • currentPeriodEnd string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    When it renews (or ends, if cancelAtPeriodEnd)

  • cancelAtPeriodEnd boolean required
  • totalCents integer required min -9007199254740991max 9007199254740991

    Each renewal, in the subscription currency

  • items array<object> required
  • id string required
  • server object required
  • id string required
  • name string required
  • packageName string required
  • priceCents integer required min -9007199254740991max 9007199254740991
  • backupPriceCents integer required min -9007199254740991max 9007199254740991
  • ipv4PriceCents integer required min -9007199254740991max 9007199254740991
  • totalCents integer required min -9007199254740991max 9007199254740991
  • usage object | null required

    Pay-as-you-go accounts: an estimate of this cycle so far

  • periodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • currency string required

    Lowercase ISO 4217 code

  • estimatedCents integer required min -9007199254740991max 9007199254740991
  • servers array<object> required
  • server object required
  • id string required
  • name string required
  • hours number required
  • cents integer required min -9007199254740991max 9007199254740991
  • defaultPaymentMethod object | null required
  • id string required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • expMonth integer | null required min -9007199254740991max 9007199254740991
  • expYear integer | null required min -9007199254740991max 9007199254740991
  • expired boolean required
  • isDefault boolean required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 403 Not allowed
  • 404 No such workspace
PATCH /billing/details

Change billing details

Billing email, legal name, address and tax ID. Send only the fields to change; `null` clears one. Applies to invoices issued from now on: issued invoices keep the details they were billed to. Changing the tax ID clears its verification. Needs `billing:write`.

API tokens billing:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Request body

  • billingEmail string emailmax length 254pattern ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
  • legalName string | null max length 200
  • addressLine1 string | null max length 200
  • addressLine2 string | null max length 200
  • city string | null max length 100
  • region string | null max length 100
  • postalCode string | null max length 20
  • country string | null pattern ^[A-Za-z]{2}$

    ISO 3166-1 alpha-2

  • taxId string | null max length 50
  • taxIdType string | null max length 20

Responses

200 The updated overview
  • account object | null required

    Null until the workspace first orders or saves billing details

  • billingEmail string required

    Where invoices and receipts are sent

  • legalName string | null required
  • addressLine1 string | null required
  • addressLine2 string | null required
  • city string | null required
  • region string | null required

    State or province

  • postalCode string | null required
  • country string | null required

    ISO 3166-1 alpha-2

  • taxStatus string required

    TAXABLEEXEMPTREVERSE_CHARGE

  • taxId string | null required
  • taxIdType string | null required
  • taxIdVerifiedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • id string required
  • mode string required

    PREPAID_MONTHLY: each server is charged a month ahead. POSTPAID_USAGE: hours are invoiced monthly in arrears.

    PREPAID_MONTHLYPOSTPAID_USAGE

  • status string required

    ACTIVEPAST_DUESUSPENDEDCLOSED

  • currency string required

    Lowercase ISO 4217 code

  • creditBalanceCents integer required min -9007199254740991max 9007199254740991
  • paymentTermsDays integer required min -9007199254740991max 9007199254740991
  • usageLimitCents integer | null required min -9007199254740991max 9007199254740991
  • paymentsEnabled boolean required

    Whether invoices can be paid online now

  • amountDue array<object> required
  • currency string required

    Lowercase ISO 4217 code

  • cents integer required min -9007199254740991max 9007199254740991
  • count integer required min -9007199254740991max 9007199254740991

    Open invoices

  • overdue integer required min -9007199254740991max 9007199254740991

    Open invoices past their due date

  • subscriptions array<object> required
  • id string required
  • name string | null required
  • status string required

    ACTIVEPAST_DUECANCELED

  • currency string required

    Lowercase ISO 4217 code

  • currentPeriodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • currentPeriodEnd string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

    When it renews (or ends, if cancelAtPeriodEnd)

  • cancelAtPeriodEnd boolean required
  • totalCents integer required min -9007199254740991max 9007199254740991

    Each renewal, in the subscription currency

  • items array<object> required
  • id string required
  • server object required
  • id string required
  • name string required
  • packageName string required
  • priceCents integer required min -9007199254740991max 9007199254740991
  • backupPriceCents integer required min -9007199254740991max 9007199254740991
  • ipv4PriceCents integer required min -9007199254740991max 9007199254740991
  • totalCents integer required min -9007199254740991max 9007199254740991
  • usage object | null required

    Pay-as-you-go accounts: an estimate of this cycle so far

  • periodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • currency string required

    Lowercase ISO 4217 code

  • estimatedCents integer required min -9007199254740991max 9007199254740991
  • servers array<object> required
  • server object required
  • id string required
  • name string required
  • hours number required
  • cents integer required min -9007199254740991max 9007199254740991
  • defaultPaymentMethod object | null required
  • id string required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • expMonth integer | null required min -9007199254740991max 9007199254740991
  • expYear integer | null required min -9007199254740991max 9007199254740991
  • expired boolean required
  • isDefault boolean required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 Invalid details
  • 403 Not allowed
GET /billing/invoices

List invoices

Newest first, 25 to a page. Each is in the currency it was charged in. Needs `billing:read`.

API tokens billing:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • page query · integer min 1max 9007199254740991default 1

    1-based page number

  • status query · string

    OPENPAIDVOIDUNCOLLECTIBLE

Responses

200 A page of invoices
  • items array<Invoice> required
  • id string required
  • number string | null required
  • status string required

    OPENPAIDVOIDUNCOLLECTIBLE

  • currency string required

    The currency it was charged in

  • totalCents integer required min -9007199254740991max 9007199254740991
  • amountDueCents integer required min -9007199254740991max 9007199254740991
  • overdue boolean required
  • periodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • issuedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • dueAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • paidAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • total integer required min -9007199254740991max 9007199254740991
  • page integer required min -9007199254740991max 9007199254740991
  • pageSize integer required min -9007199254740991max 9007199254740991
  • pageCount integer required min -9007199254740991max 9007199254740991
  • 400 The request failed validation
  • 403 Not allowed
GET /billing/invoices/{id}

Get an invoice

With its line items, taxes, credit applied and payments. Needs `billing:read`.

API tokens billing:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The invoice
  • id string required
  • number string | null required
  • status string required

    OPENPAIDVOIDUNCOLLECTIBLE

  • currency string required

    The currency it was charged in

  • totalCents integer required min -9007199254740991max 9007199254740991
  • amountDueCents integer required min -9007199254740991max 9007199254740991
  • overdue boolean required
  • periodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • issuedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • dueAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • paidAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • subtotalCents integer required min -9007199254740991max 9007199254740991
  • taxCents integer required min -9007199254740991max 9007199254740991
  • creditAppliedCents integer required min -9007199254740991max 9007199254740991
  • amountPaidCents integer required min -9007199254740991max 9007199254740991
  • voidedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • billedName string | null required
  • billedEmail string required
  • billedAddress object | null required

    As it was when the invoice was issued

  • line1 string | null required
  • line2 string | null required
  • city string | null required
  • region string | null required
  • postalCode string | null required
  • country string | null required
  • billedTaxId string | null required
  • lineItems array<object> required
  • id string required
  • kind string required

    SUBSCRIPTIONPRORATIONUSAGEADJUSTMENT

  • description string required
  • quantity number required

    Months, hours, or 1

  • unitPriceCents number required

    May have fractional cents

  • amountCents integer required min -9007199254740991max 9007199254740991
  • periodStart string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • serverId string | null required
  • taxes array<object> required
  • id string required
  • displayName string required
  • percentage number required
  • jurisdiction string | null required
  • taxableAmountCents integer required min -9007199254740991max 9007199254740991
  • amountCents integer required min -9007199254740991max 9007199254740991
  • payments array<object> required
  • id string required
  • status string required

    PENDINGSUCCEEDEDFAILEDREFUNDED

  • amountCents integer required min -9007199254740991max 9007199254740991
  • currency string required

    Lowercase ISO 4217 code

  • failureReason string | null required
  • method object | null required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • test boolean required

    Recorded in test mode; nothing was charged

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • credits array<object> required
  • id string required
  • kind string required

    GRANTPROMOREFUNDAPPLIEDEXPIREDADJUSTMENT

  • amountCents integer required min -9007199254740991max 9007199254740991
  • description string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such invoice
POST /billing/invoices/{id}/pay

Pay an open invoice

Charges the amount due. If online payment isn't available, answers 409 and nothing is charged. Paying a new order's invoice builds its server. Needs `billing:write`.

API tokens billing:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 Paid
  • id string required
  • number string | null required
  • status string required

    OPENPAIDVOIDUNCOLLECTIBLE

  • currency string required

    The currency it was charged in

  • totalCents integer required min -9007199254740991max 9007199254740991
  • amountDueCents integer required min -9007199254740991max 9007199254740991
  • overdue boolean required
  • periodStart string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • issuedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • dueAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • paidAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • subtotalCents integer required min -9007199254740991max 9007199254740991
  • taxCents integer required min -9007199254740991max 9007199254740991
  • creditAppliedCents integer required min -9007199254740991max 9007199254740991
  • amountPaidCents integer required min -9007199254740991max 9007199254740991
  • voidedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • billedName string | null required
  • billedEmail string required
  • billedAddress object | null required

    As it was when the invoice was issued

  • line1 string | null required
  • line2 string | null required
  • city string | null required
  • region string | null required
  • postalCode string | null required
  • country string | null required
  • billedTaxId string | null required
  • lineItems array<object> required
  • id string required
  • kind string required

    SUBSCRIPTIONPRORATIONUSAGEADJUSTMENT

  • description string required
  • quantity number required

    Months, hours, or 1

  • unitPriceCents number required

    May have fractional cents

  • amountCents integer required min -9007199254740991max 9007199254740991
  • periodStart string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • periodEnd string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • serverId string | null required
  • taxes array<object> required
  • id string required
  • displayName string required
  • percentage number required
  • jurisdiction string | null required
  • taxableAmountCents integer required min -9007199254740991max 9007199254740991
  • amountCents integer required min -9007199254740991max 9007199254740991
  • payments array<object> required
  • id string required
  • status string required

    PENDINGSUCCEEDEDFAILEDREFUNDED

  • amountCents integer required min -9007199254740991max 9007199254740991
  • currency string required

    Lowercase ISO 4217 code

  • failureReason string | null required
  • method object | null required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • test boolean required

    Recorded in test mode; nothing was charged

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • credits array<object> required
  • id string required
  • kind string required

    GRANTPROMOREFUNDAPPLIEDEXPIREDADJUSTMENT

  • amountCents integer required min -9007199254740991max 9007199254740991
  • description string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such invoice
  • 409 Not open, or online payment unavailable
GET /billing/payment-methods

List payment methods

The default first. Needs `billing:read`.

API tokens billing:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Responses

200 The payment methods
  • items array<PaymentMethod> required
  • id string required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • expMonth integer | null required min -9007199254740991max 9007199254740991
  • expYear integer | null required min -9007199254740991max 9007199254740991
  • expired boolean required
  • isDefault boolean required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 403 Not allowed
POST /billing/payment-methods/{id}/default

Make a payment method the default

Open invoices and renewals are charged to it. Needs `billing:write`.

API tokens billing:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The payment methods
  • items array<PaymentMethod> required
  • id string required
  • type string required

    CARDBANK_ACCOUNTMANUAL

  • brand string | null required
  • last4 string | null required
  • expMonth integer | null required min -9007199254740991max 9007199254740991
  • expYear integer | null required min -9007199254740991max 9007199254740991
  • expired boolean required
  • isDefault boolean required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such payment method
  • 409 Card expired
DELETE /billing/payment-methods/{id}

Remove a payment method

Removing the default makes the newest other method the default. Refused for the only method while servers are still billing. Needs `billing:write`.

API tokens billing:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 Removed
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such payment method
  • 409 Still needed
GET /billing/credits

List credit history

Newest first, 25 to a page, with the current balance. Needs `billing:read`.

API tokens billing:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • page query · integer min 1max 9007199254740991default 1

    1-based page number

Responses

200 A page of credit entries
  • items array<CreditTransaction> required
  • id string required
  • kind string required

    GRANTPROMOREFUNDAPPLIEDEXPIREDADJUSTMENT

  • amountCents integer required min -9007199254740991max 9007199254740991

    Positive adds credit; negative uses it

  • balanceAfterCents integer required min -9007199254740991max 9007199254740991
  • description string required
  • expiresAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • invoice object | null required
  • id string required
  • number string | null required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • total integer required min -9007199254740991max 9007199254740991
  • page integer required min -9007199254740991max 9007199254740991
  • pageSize integer required min -9007199254740991max 9007199254740991
  • pageCount integer required min -9007199254740991max 9007199254740991
  • balanceCents integer required min -9007199254740991max 9007199254740991
  • currency string required

    Lowercase ISO 4217 code

  • 400 The request failed validation
  • 403 Not allowed

Members

People in a team workspace, and invites.

GET /workspaces/{workspaceId}/members

List members and pending invites

Owners first. Team workspaces only. Needs `members:read`.

API tokens members:read

Parameters

  • workspaceId path · string required min length 1max length 64

Responses

200 Members and invites
  • items array<Member> required
  • userId string required
  • name string required
  • email string required
  • avatarUrl string | null required
  • role string required

    OWNERADMINBILLINGMEMBER

  • joinedAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • isYou boolean required
  • invites array<Invite> required

    Invites not yet accepted or revoked (expired ones included)

  • id string required
  • email string required
  • role string required

    OWNERADMINBILLINGMEMBER

  • invitedBy string | null required
  • sentAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expiresAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expired boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such workspace, or a personal one
PATCH /workspaces/{workspaceId}/members/{userId}

Change a member's role

Only an owner can make someone an owner or change an owner's role, and a team always keeps at least one owner. Needs `members:write` and a signed-in user.

Signed-in only members:write

Parameters

  • workspaceId path · string required min length 1max length 64
  • userId path · string required min length 1max length 64

Request body

  • role string required

    OWNERADMINBILLINGMEMBER

Responses

200 Updated
  • userId string required
  • name string required
  • email string required
  • avatarUrl string | null required
  • role string required

    OWNERADMINBILLINGMEMBER

  • joinedAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • isYou boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such member
  • 409 Would leave the team without an owner
DELETE /workspaces/{workspaceId}/members/{userId}

Remove a member

Their API tokens in this workspace are revoked too. Only an owner can remove an owner, and never the last one. Removing yourself is the same as leaving. Needs `members:write` and a signed-in user.

Signed-in only members:write

Parameters

  • workspaceId path · string required min length 1max length 64
  • userId path · string required min length 1max length 64

Responses

200 Removed
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such member
  • 409 The last owner
POST /workspaces/{workspaceId}/leave

Leave a team

Your API tokens in it are revoked. The team's last owner can't leave: make someone else an owner first, or delete the team. Needs a signed-in member.

Signed-in only

Parameters

  • workspaceId path · string required min length 1max length 64

Responses

200 Left
  • ok boolean required
  • 400 The request failed validation
  • 403 An API token
  • 404 No such workspace
  • 409 The last owner
POST /workspaces/{workspaceId}/invites

Invite someone

Emails a link that works for 7 days. If the address already has a pending invite, that one is refreshed (new link, new role). `emailSent` is false if the email could not be sent: pass `url` on yourself. Only an owner can invite an owner. Needs `members:write` and a signed-in user.

Signed-in only members:write

Parameters

  • workspaceId path · string required min length 1max length 64

Request body

  • email string required min length 3max length 254
  • role string

    OWNERADMINBILLINGMEMBER

Responses

201 Invited
  • invite object required
  • id string required
  • email string required
  • role string required

    OWNERADMINBILLINGMEMBER

  • invitedBy string | null required
  • sentAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expiresAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expired boolean required
  • url string required

    The invite link, to pass on yourself if the email could not be sent

  • emailSent boolean required
  • 400 Not an email address
  • 403 Not allowed
  • 409 Already a member, or invited under a minute ago
POST /workspaces/{workspaceId}/invites/{id}/resend

Resend an invite

Emails a fresh link (the old one stops working), good for another 7 days. Needs `members:write` and a signed-in user.

Signed-in only members:write

Parameters

  • workspaceId path · string required min length 1max length 64
  • id path · string required min length 1max length 64

Responses

200 Sent
  • invite object required
  • id string required
  • email string required
  • role string required

    OWNERADMINBILLINGMEMBER

  • invitedBy string | null required
  • sentAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expiresAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • expired boolean required
  • url string required

    The invite link, to pass on yourself if the email could not be sent

  • emailSent boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such invite
  • 409 Sent under a minute ago
DELETE /workspaces/{workspaceId}/invites/{id}

Revoke an invite

Its link stops working. Needs `members:write` and a signed-in user.

Signed-in only members:write

Parameters

  • workspaceId path · string required min length 1max length 64
  • id path · string required min length 1max length 64

Responses

200 Revoked
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such invite
POST /invites/preview

Look up an invite

The team, role and inviter of an emailed invite, and whether you can accept it. Sent as a POST so the token stays out of URLs and logs. Needs a signed-in user.

Signed-in only

Request body

  • token string required min length 1max length 128

Responses

200 The invite
  • status string required

    invalidpendingexpiredrevokedaccepted

  • workspace object
  • name string required
  • slug string required
  • role string

    OWNERADMINBILLINGMEMBER

  • inviter string | null
  • email string
  • emailMatches boolean

    Whether you're signed in with the invited address

  • isMember boolean
  • 400 The request failed validation
  • 401 Not signed in
POST /invites/accept

Accept an invite

Joins the team. You must be signed in with the invited address. If you're already in the team, you keep your role unless the invite's is higher. Needs a signed-in user.

Signed-in only

Request body

  • token string required min length 1max length 128

Responses

200 Joined
  • workspace object required
  • id string required
  • slug string required
  • name string required
  • role string required

    OWNERADMINBILLINGMEMBER

  • 400 The request failed validation
  • 401 Not signed in
  • 403 Signed in with a different address
  • 404 No such invite
  • 409 Expired, revoked or already accepted

API tokens

Tokens for scripts and tools, scoped to one workspace.

GET /workspaces/{workspaceId}/api-tokens

List API tokens

Newest first, revoked and expired ones included. Never includes the tokens themselves. Needs `tokens:manage` and a signed-in user.

Signed-in only tokens:manage

Parameters

  • workspaceId path · string required min length 1max length 64

Responses

200 The tokens
  • items array<ApiToken> required
  • id string required
  • name string required
  • prefix string required

    The start of the token, to tell tokens apart

  • scopes array<string> required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdBy string | null required
  • expiresAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • lastUsedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • lastUsedIp string | null required
  • revokedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • status string required

    activeexpiredrevoked

  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such workspace
POST /workspaces/{workspaceId}/api-tokens

Create an API token

Scopes must be ones your role has, and a token never does more than its creator's current role allows. The full token is in this response only: store it now. Needs `tokens:manage` and a signed-in user.

Signed-in only tokens:manage

Parameters

  • workspaceId path · string required min length 1max length 64

Request body

  • name string required min length 1max length 100
  • scopes array<string> required min 1 itemsmax 32 items

    Permissions from the token scopes your role has

  • expiresInDays one of required

    30, 90 or 365; null for a token that never expires

  • Option 1 number
  • Option 2 number
  • Option 3 number
  • Option 4 null

Responses

201 Created
  • token string required

    The full token. It is shown only this once.

  • item object required
  • id string required
  • name string required
  • prefix string required

    The start of the token, to tell tokens apart

  • scopes array<string> required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdBy string | null required
  • expiresAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • lastUsedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • lastUsedIp string | null required
  • revokedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • status string required

    activeexpiredrevoked

  • 400 Bad name, scopes or expiry
  • 403 Not allowed, or a scope your role lacks
  • 409 Too many tokens
DELETE /workspaces/{workspaceId}/api-tokens/{id}

Revoke an API token

It stops working at once; it stays listed as revoked. Needs `tokens:manage` and a signed-in user.

Signed-in only tokens:manage

Parameters

  • workspaceId path · string required min length 1max length 64
  • id path · string required min length 1max length 64

Responses

200 Revoked
  • ok boolean required
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such token

Activity

What happened in a workspace, and who did it.

GET /activity

List activity

The workspace's audit log, newest first, 50 a page, each entry with a plain-words summary. Filter by who (a member or API token), area (the action's prefix) and dates. Staff actions appear as Support. Needs `audit:read`.

API tokens audit:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • page query · integer min 1max 9007199254740991default 1
  • who query · string pattern ^(user:\S+|token:\S+|staff|system)$

    `user:<userId>`, `token:<apiTokenId>`, `staff` (Support) or `system`

  • area query · string

    serverbackupssh_keymemberinviteapi_tokenticketbillingworkspace

  • from query · string pattern ^\d{4}-\d{2}-\d{2}$

    First day, inclusive (UTC)

  • to query · string pattern ^\d{4}-\d{2}-\d{2}$

    Last day, inclusive (UTC)

Responses

200 One page of entries
  • items array<ActivityEntry> required
  • id string required
  • action string required

    Dotted action, e.g. `server.start`

  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • actor object required
  • type string required

    usertokenstaffsystem

  • name string required

    A member's name, "API token <name>", "Support" or "Automatic"

  • email string | null required
  • summary string required

    What they did, to follow the actor's name

  • targetType string required
  • targetId string required
  • href string | null required

    The dashboard page for what it happened to, when it still exists

  • ipAddress string | null required

    Only for members' and API tokens' actions

  • metadata object | null required
  • page integer required min -9007199254740991max 9007199254740991
  • pageCount integer required min -9007199254740991max 9007199254740991
  • pageSize integer required min -9007199254740991max 9007199254740991
  • total integer required min -9007199254740991max 9007199254740991
  • 400 Bad filter
  • 403 Not allowed
  • 404 No such workspace

Support

Support tickets: conversations with the support team.

GET /tickets

List support tickets

The workspace's tickets, latest message first. Needs `support:read`.

Signed-in only support:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • status query · string

    `open` includes answered tickets

    openclosed

Responses

200 The tickets
  • items array<TicketSummary> required
  • id string required
  • number integer required min -9007199254740991max 9007199254740991

    Short number for people, as in "#1042"

  • subject string required
  • category string required

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string required

    LOWNORMALHIGHURGENT

  • status string required

    `OPEN` is waiting on support, `ANSWERED` on you. Replying to a `CLOSED` ticket opens it again.

    OPENANSWEREDCLOSED

  • server object | null required

    The server it is about

  • id string required
  • name string required
  • openedBy string | null required
  • messageCount integer required min -9007199254740991max 9007199254740991
  • lastMessageAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • closedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
POST /tickets

Open a support ticket

With its first message. Needs `support:write`.

Signed-in only support:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

Request body

  • subject string required min length 1max length 200
  • body string required min length 1max length 20000

    The first message

  • category string

    Defaults to `TECHNICAL`

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string

    Defaults to `NORMAL`

    LOWNORMALHIGHURGENT

  • serverId string | null max length 64

    A server in the workspace it is about

Responses

201 Opened
  • id string required
  • number integer required min -9007199254740991max 9007199254740991

    Short number for people, as in "#1042"

  • subject string required
  • category string required

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string required

    LOWNORMALHIGHURGENT

  • status string required

    `OPEN` is waiting on support, `ANSWERED` on you. Replying to a `CLOSED` ticket opens it again.

    OPENANSWEREDCLOSED

  • server object | null required

    The server it is about

  • id string required
  • name string required
  • openedBy string | null required
  • messageCount integer required min -9007199254740991max 9007199254740991
  • lastMessageAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • closedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • messages array<TicketMessage> required
  • id string required
  • staff boolean required

    Written by the support team

  • author string required
  • mine boolean required

    Written by you

  • body string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such server
  • 409 Too many open tickets
GET /tickets/{id}

Get a support ticket

With its messages, oldest first. Needs `support:read`.

Signed-in only support:read

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The ticket
  • id string required
  • number integer required min -9007199254740991max 9007199254740991

    Short number for people, as in "#1042"

  • subject string required
  • category string required

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string required

    LOWNORMALHIGHURGENT

  • status string required

    `OPEN` is waiting on support, `ANSWERED` on you. Replying to a `CLOSED` ticket opens it again.

    OPENANSWEREDCLOSED

  • server object | null required

    The server it is about

  • id string required
  • name string required
  • openedBy string | null required
  • messageCount integer required min -9007199254740991max 9007199254740991
  • lastMessageAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • closedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • messages array<TicketMessage> required
  • id string required
  • staff boolean required

    Written by the support team

  • author string required
  • mine boolean required

    Written by you

  • body string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such ticket
POST /tickets/{id}/messages

Reply to a support ticket

Replying to a closed ticket opens it again. Needs `support:write`.

Signed-in only support:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Request body

  • body string required min length 1max length 20000

Responses

201 The ticket, with the reply
  • id string required
  • number integer required min -9007199254740991max 9007199254740991

    Short number for people, as in "#1042"

  • subject string required
  • category string required

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string required

    LOWNORMALHIGHURGENT

  • status string required

    `OPEN` is waiting on support, `ANSWERED` on you. Replying to a `CLOSED` ticket opens it again.

    OPENANSWEREDCLOSED

  • server object | null required

    The server it is about

  • id string required
  • name string required
  • openedBy string | null required
  • messageCount integer required min -9007199254740991max 9007199254740991
  • lastMessageAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • closedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • messages array<TicketMessage> required
  • id string required
  • staff boolean required

    Written by the support team

  • author string required
  • mine boolean required

    Written by you

  • body string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such ticket
POST /tickets/{id}/close

Close a support ticket

When the problem is solved. Reply to open it again. Needs `support:write`.

Signed-in only support:write

Parameters

  • Workspace header · string

    The workspace's ID or slug. With an API token, leave it out: the token's own workspace is used. Signed in, it defaults to your personal workspace. `?workspace=` works too.

  • id path · string required min length 1max length 64

Responses

200 The closed ticket
  • id string required
  • number integer required min -9007199254740991max 9007199254740991

    Short number for people, as in "#1042"

  • subject string required
  • category string required

    TECHNICALBILLINGSALESABUSEOTHER

  • priority string required

    LOWNORMALHIGHURGENT

  • status string required

    `OPEN` is waiting on support, `ANSWERED` on you. Replying to a `CLOSED` ticket opens it again.

    OPENANSWEREDCLOSED

  • server object | null required

    The server it is about

  • id string required
  • name string required
  • openedBy string | null required
  • messageCount integer required min -9007199254740991max 9007199254740991
  • lastMessageAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • closedAt string | null date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • messages array<TicketMessage> required
  • id string required
  • staff boolean required

    Written by the support team

  • author string required
  • mine boolean required

    Written by you

  • body string required
  • createdAt string required date-timepattern ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
  • 400 The request failed validation
  • 403 Not allowed
  • 404 No such ticket