Skip to content
BuildBase
HTTP API menu

Make your first API call

From nothing to a working BuildBase API request - get a key in the console, call the API with curl, Postman or the SDK, and read the answer.

In short

An API call is a message your computer sends to BuildBase, asking for something. To be allowed in, the message carries a key, like a password for programs. You make the key in the console, swap it for a session, then ask BuildBase for your workspaces. It takes about five minutes, and every command below can be copied as it is.

Before you start

A BuildBase organization, and a console role that may create API keys: owners and admins can. You also need a terminal with curl (built in on macOS, Linux and Windows 10 or later), or Postman.

1. Copy your Organization ID

Open Organization settings in the console

(opens the console in a new tab)

Your Organization ID sits beside General. Press it to copy it, then keep it in your terminal:

export BUILDBASE_ORG_ID="paste-your-organization-id"

The General card's title with the Organization ID, highlighted as step 4

2. Create an API key

Open API keys in the console (opens the console in a new tab)
  1. In the left rail choose Settings, then API keys under Organization.
  2. Press Create API key at the top right.
  3. Give it a Name such as First API call, leave Role empty or pick a narrow API role, keep Key type on App-server key, and press Create.
  4. Copy your API key shows the whole key, orgId:secret, this once. Press Copy key.

The Create API key dialog: Name Marketing site, Description Reads blog posts and FAQs to build the marketing site, Expires at empty, Role (optional) set to content-reader and highlighted as step 3, Key type App-server key, and the Create button highlighted

export BUILDBASE_API_TOKEN="paste-the-key-you-copied"

The key is a secret. Keep it in an environment variable on a server or your own machine, never in browser code or a chat. Make an API key for your server covers roles and retiring a key.

3. Call the API with curl

BuildBase's cloud API is at https://api.console.buildbase.app. The app API acts for one person, so it takes a session. Swap the key for one:

curl -s -X POST "https://api.console.buildbase.app/api/v1/public/token/exchange" \
  -H "Content-Type: application/json" \
  -d "{\"token\":\"$BUILDBASE_API_TOKEN\",\"expiresIn\":3600}"
{
  "sessionId": "example-session-id-a-long-random-string",
  "expiresIn": 3600,
  "userId": "665f1c2e9b1d4a0012ab34ce",
  "orgId": "665f1c2e9b1d4a0012ab34cf"
}

The session is for the key's own user, for one hour. Copy sessionId, then ask for that user's workspaces:

export BUILDBASE_SESSION_ID="paste-the-sessionId"

curl -s "https://api.console.buildbase.app/api/v1/public/workspaces" \
  -H "x-session-id: $BUILDBASE_SESSION_ID"

A list comes back: the workspaces that user belongs to, or [] when there are none. Both mean the call worked.

4. Or call it with Postman

  1. In Postman choose Import, paste https://docs.buildbase.app/openapi/public-v1.json, and import it as a collection. Every operation becomes a request, filed by tag.
  2. Open the collection's Variables and check baseUrl is https://api.console.buildbase.app (or your own server).
  3. In the Token folder open POST /api/v1/public/token/exchange, put {"token": "<your key>"} in Body as raw JSON, and press Send.
  4. In the Workspaces folder open GET /api/v1/public/workspaces, add the header x-session-id with the sessionId from step 3, and press Send.

Postman stores what you type in its own workspace: use a Postman environment variable marked secret for the key, not the request body of a shared collection.

5. Or call it with the SDK

In JavaScript or TypeScript, the server SDK sends the same requests:

first-call.ts
import BuildBase from '@buildbase/sdk';

const bb = BuildBase({
  serverUrl: 'https://api.console.buildbase.app',
  orgId: process.env.BUILDBASE_ORG_ID!,
});

const workspaces = await bb
  .withSession(process.env.BUILDBASE_SESSION_ID!)
  .workspace.list();

console.log(workspaces);

6. Read the answer

Every answer has a status (a number) and a body (JSON). curl -i shows the status and headers above the body.

StatusMeansWhat to do
200It workedRead the body
400Something in the request is wrong; path names the fieldFix the field the message names
401The key or session is missing, mistyped, expired or revokedCheck the header name and value; exchange the key again
429Too many requestsWait the seconds in Retry-After, then send it again

HTTP API errors lists every status and body shape.

Screens on this page

The screenshots are the console's own, from Your organization and API keys, with example data only.

Next steps