Skip to main content
Webentor Studio

Help · The API

The API: first steps

Everything you do in the dashboard goes through this API, and a script, a CI job or another service can call it too. It is plain HTTPS and JSON, from a server: browsers on other sites cannot call it.

Start

The address

Every route is under one address.

This Studio’s API answers at https://api.studio.webikon.eu. Routes start with /api/v1, and token routes with /auth. The examples read the address from STUDIO_API:

export STUDIO_API=https://api.studio.webikon.eu

The whole API is described in one file, the reference is rendered from it, and a client generator can read it: https://api.studio.webikon.eu/api/v1/openapi.json (text to copy, not a link: it is fetched by a program).

Start

Make a token

A token is how a script says who it is.

  1. Open Account → Security in the dashboard and confirm it is you when asked.
  2. Make a token. Choose read for a script that only reads, and write for one that changes things. It lives 90 days unless you choose another lifetime, at most a year.
  3. Copy it once: it is shown when it is made and never again. Keep it in your CI’s secret store, as STUDIO_TOKEN.

A token acts as you, and no more

A write token can do what your role allows, except what a person must do at a screen: confirming it is you, deleting a project or a team, storing a hosting credential. Those answer 403 to any token. Tokens and conventions lists what each kind may do.

Start

Your first call

Ask who you are.

Ask who you are. The answer names you and lists your teams with your role in each.

curl -sS -X GET "$STUDIO_API/api/v1/me" \
  -H "Authorization: Bearer $STUDIO_TOKEN"

The same with Node, without packages:

// Node 18 or later, no packages: node me.mjs
const { STUDIO_API, STUDIO_TOKEN } = process.env;
const res = await fetch(`${STUDIO_API}/api/v1/me`, {
  headers: { authorization: `Bearer ${STUDIO_TOKEN}` },
});
const me = await res.json();
if (!res.ok) throw new Error(`${res.status}: ${me.detail}`);
for (const team of me.accounts) console.log(team.slug, team.role);

List a team’s projects. Each has an id, which every project route takes. A team is called an account in paths; use its slug.

curl -sS -X GET "$STUDIO_API/api/v1/accounts/$TEAM/projects" \
  -H "Authorization: Bearer $STUDIO_TOKEN"

Next

Where to go from here

Three pages cover the rest.

  • Tokens and conventions: errors, paging, limits, retries, and what may change in the API.
  • Recipes: publishing from CI, rebuilding the live site, changing content, inviting a member, each as curl commands and one Node script.
  • The reference: every operation, what it needs and what it answers.