Skip to main content
Open console

API

The API the console and the CLI call, the tokens CI deploys with, and what each can reach.

10 min read

Everything the console does is an HTTP API under /api/vc/v1, and the console and the CLI both call it. How you reach it depends on who is calling:

  • You, at your own machine: vallic login signs the CLI in through your browser. Everything you can do in the console you can do from there.
  • A pipeline: a personal access token. It reaches deploys and what a deploy needs: see What a token can do.

Issuing a token

Your account → Access tokens → Issue a token. It asks three things:

Field Why
What is it for Only you see it. It tells you which token to revoke when something is compromised
Team The token reaches this team and nothing else, whatever else you are a member of
Expires 7, 30 or 90 days

The token is shown once. Only a digest of it is kept, so it cannot be shown again or recovered. If you lose it, revoke it and issue another.

There is no token that never expires. You are emailed from 14 days before one expires, and weekly after that.

Revoke is on the token's row. Revoked and expired tokens stay in the list, so you can see what existed and when it was last used.

What a token can do

A token is for CI. It reaches:

  • deploying, redeploying and rolling back
  • building
  • following the task and its log
  • checking a vallic.yaml
  • the reads that find a project and environment: /me, /teams, /projects, /environments, releases

Nothing else. Variables, domains, backups, environments, keys and tokens need you signed in: the console, or vallic login. A token asked for anything else is refused with a 403, token_not_allowed. A token cannot issue tokens.

Within that, exactly what you can do in that team, and no more. Your role decides what the token may touch. Every rule that applies to you in the console applies to it. If your role changes, so does the token. Leaving the team leaves the token with nothing.

There are no scopes. A token cannot be limited to reading, or to one project. If a pipeline should only ever deploy, give it a token belonging to someone whose role is only Developer. That can be a person, or an account made for the purpose.

A token never restores a backup over production. Restoring over production asks for your password again, signed in.

Calling the API

curl https://console.vallic.com/api/vc/v1/environments \
  -H "Authorization: Bearer vcp_…"

JSON in and out. A token is a bearer credential: whoever holds the string is you. Every token starts vcp_, so one committed by mistake is easy to search for. A request refused for what it sent is a 422 whose error.fields names the reason per field.

Endpoints marked token take a personal access token; the rest need you signed in. Signed in through a browser, send the session's CSRF token from /session/token with every write, in an X-CSRF-Token header. The CLI's sign-in needs none.

Most changes come in two calls:

  1. GET what may be asked: the choices, the values as they are now, or blocked with the reason there is nothing to ask.
  2. POST the change.

Where machines are built or given back, a …/preview says first what would happen and what it would cost. It changes nothing. The console's dialogs are these calls, so anything they do can be scripted the same way.

You and your account

Endpoints under /api/vc/v1
You GET /me, GET /teams (token)
Keys and tokens GET, POST on /me/ssh-keys and /me/tokens; DELETE /me/ssh-keys/{id}, /me/tokens/{id}
Other browsers POST /users/{id}/sessions/end-others signs out every browser but this one
Invitations to you POST /invitations/{id}/accept, for the account whose confirmed address it was sent to

Teams

The team GET /teams/new, POST /teams; GET, POST on /teams/{id}/settings; DELETE /teams/{id} once nothing is left in it
People GET /teams/{id}/people; POST /teams/{id}/invitations; POST /invitations/{id}/renew, DELETE /invitations/{id}; PATCH, DELETE on /memberships/{id}
Who it bills as GET, POST on /teams/{id}/billing; POST /billing/address-format with {country} says how that country writes an address
Subscriptions GET, POST on /teams/{id}/subscriptions/{order}/cancel
Integrations GET /teams/{id}/integrations/new; POST /teams/{id}/integrations/fields with {kind} says what a service asks; POST /teams/{id}/integrations; GET, POST, DELETE on /integrations/{id}
GitLab and Gitea GET /teams/{id}/repository-hosts/new, POST /teams/{id}/repository-hosts; DELETE /repository-hosts/{id}
Backup destinations GET /teams/{id}/backup-destinations/new, POST /teams/{id}/backup-destinations; GET, POST on /backup-destinations/{id}
Notifications GET /teams/{id}/notifications — what is waiting and what finished since you last looked, the bell's two counts and their first rows
What you have seen POST /teams/{id}/activity/seen, POST /teams/{id}/next-steps/hide — yours alone

Projects

Listing GET /projects (token)
New GET /projects/new, POST /projects
Settings GET, POST on /projects/{id}/settings, …/registries (DELETE …/registries/{host} forgets one), …/logs, …/notifications and …/backup-window (hour, timezone and, optionally, security_updates; DELETE goes back to the default hours)
Edge GET, PATCH on /projects/{id}/edge — blocked addresses and user agents, rate limit, HSTS, compression and the pages the edge serves, in one save; nothing is kept if anything is refused
Commercial terms GET, POST on /projects/{id}/terms
Repository GET, POST on /projects/{id}/repository; POST …/repository/reconnect
Releases GET /projects/{id}/releases (?branch= for one branch) (token)
Variables GET, POST on /projects/{id}/variables; DELETE …/variables/{name}; POST …/variables/import, …/variables/apply
Cancelling, deleting GET, POST on /projects/{id}/cancel; DELETE /projects/{id} once it has no environments

Environments

Listing GET /environments, /environments/{id} (token)
New, changed, deleted GET /projects/{id}/environments/choices, POST /projects/{id}/environments; PATCH /environments/{id} (git_ref, auto_deploy, protected), DELETE /environments/{id}
Deploying GET /environments/{id}/deploy and …/source say what may be deployed and from where; POST …/deploy, …/redeploy, …/rollback, …/build (token)
Variables GET, POST on /environments/{id}/variables; GET, DELETE …/variables/{name}; POST …/variables/import, …/variables/apply; POST /variables/parse reads a pasted .env back and saves nothing
Service settings GET, POST on /environments/{id}/service-settings ({service, name, value}, for this environment over vallic.yaml); DELETE …/service-settings/{service}/{name}
Domains GET, POST on /environments/{id}/domains; PATCH, DELETE on /domains/{id}; POST /domains/{id}/verify
CDN and edge GET, PATCH on /environments/{id}/cdn and …/edge (the environment's own: allowed addresses, password, stickiness); POST …/cdn/clear
Maintenance POST /environments/{id}/maintenance with {maintenance, note?}
Logs GET /environments/{id}/logs: where the environment's request and error logs go — the project's destination by kind and name, whether it can send, how many days each machine keeps its own copy. Vallic Cloud does not keep the logs, so there is nothing to tail here
Resources GET /environments/{id}/resources?window= 1h, 24h, 7d, 30d or 90d: CPU, memory and disk, oldest first, averaged into at most 500 points; step says how many seconds each covers. Kept three months
Services GET /environments/{id}/services; GET …/services/choices, POST …/services/preview, POST …/services
Shape and scale GET, POST on /environments/{id}/reshape and …/scale; POST …/reshape/preview; POST …/discard-old-database
Storage GET, POST on /environments/{id}/storage/split, …/storage/allowance and …/storage/{disk}/disk; POST …/storage/{disk}/move, …/storage/discard; GET, POST on /volumes/{id}/grow
Machines for it GET, POST on /environments/{id}/build-machines; POST …/build-machines/options for one provider's sizes
Backups GET, POST on /environments/{id}/backups; POST …/backups/{snapshot}/download, …/restore; DELETE …/backups/{snapshot}; GET, POST on …/sync; POST …/reset-database; GET, POST on …/backup-key
Checking a manifest POST /validate, POST /environments/{id}/validate (token)

Machines, tasks and support

Machines GET /servers; GET, POST on /servers/{id}/resize; POST /servers/{id}/reboot
Following GET /tasks, /tasks/{id}, /tasks/{id}/log (token); POST /tasks/{id}/cancel while nothing has started it
Activity GET /tasks narrows with team, project, environment, kind (deployments, backups, machines, configuration, maintenance) and type, newest first, limit up to 100 and before for the next page; GET /tasks/{id} carries the task's account — what the console's dialog shows — and ?include=log adds the end of a log you may read
Support GET /teams/{id}/tickets/new; POST /teams/{id}/tickets, as multipart/form-data with screenshots as attachments[], or JSON without; POST /tickets/{id}/replies with {body, resolved}

Before you script against it

  • Deploys are refused, not queued, while another is running on the same environment: you get a 409. Wait for the task and try again. See Deployments.
  • Deploy, redeploy and rollback return the deployment, and its task. Poll /tasks/{id} with the task's id to learn how it ended, and read /tasks/{id}/log for what it printed. Do not use the deployment's own id, which is numbered apart. task is null when nothing was queued.
  • The activity list is the console's. The console's Activity page, its task dialog and its bell read /tasks, /tasks/{id} and /teams/{id}/notifications. Page with next_before: pass it back as before.
  • Poll with the ETag. /tasks and /teams/{id}/notifications answer with an ETag. Send it back as If-None-Match and an answer that has not changed is a 304 with no body. It still counts towards how often you can call it.
  • deploy and redeploy take {"skip_steps": true} to put the release live without running the deploy steps from vallic.yaml. See the first deploy.
  • rollback deploys the release that was running before the last successful deployment. It is code only; see going back.
  • A domain past the project's allowance is refused with a 409, domain_allowance_spent. See how many domains.
  • protected keeps a staging or development environment when its branch is deleted. POST /projects/{id}/environments and PATCH /environments/{id} take "protected": true or false; left out on POST, staging is protected and development is not. Turning it off needs the Admin role. Production is always protected, and asking to change it is refused. See Protected environments.
  • Adding a domain takes the hostname and nothing else. Once it is verified, PATCH makes it primary (primary: true) or canonical (canonical: true, and false for primary only). Declare a CDN in front of it in the console. See Domains.
  • Verification is throttled to twelve checks an hour per domain; past that you get a 429.
  • What cannot be taken back asks to be confirmed. Cancelling a project or a subscription and copying another environment's data in want "confirm": true in the body. Resetting a database wants the environment's name as confirm. Without it you get a 422 on confirm and nothing happens.
  • Some changes want a recent sign-in. They answer a 403 reauthentication_required when you last confirmed who you are more than five minutes ago. See Confirming it is you. Confirm and repeat the request: the console sends you through it and back, and vallic opens the browser. The changes are issuing a token, adding an SSH key, inviting somebody, changing a membership, showing a backup key, making a secret readable, deleting an environment or a backup, cancelling, changing single sign-on, and restoring over production.
  • Revealing a backup key is its own POST. GET …/backup-key says what the key opens. The key itself comes only from the POST, and every reveal is written in the activity log.

How often you can call it

Six hundred requests a minute per token. Past that you get a 429: wait and repeat the request unchanged. The count is per token, not per person or per team. A runaway script cannot lock your colleagues out, and whoever has to revoke it can still sign in.

When you poll a task to see how a deploy ended, poll it every few seconds.

Repeatedly presenting a credential that does not work gets your address refused with a 429 for a while, whatever token you try next. A call with no Authorization header does not count against this: that is a 401 and nothing more. Presenting a token that works clears the count.

Next

Need a hand?

Open a ticket from Support in the console. We answer on the ticket.

Open the console How support works