Skip to main content
vibld
Sign up for the beta
Menu

← All guides

Using vibld

The builder API

Checked against the product on

The builder at app.vibld.com is a page that talks to an HTTP API, and that API is the same one a script or an agent can call. Everything the builder does, from a conversation to a published site, goes through it.

Where it is described

The routes, their parameters, bodies and answers are described in an OpenAPI 3.1 document: app.vibld.com/api/openapi.json. It is the contract, and this page is a summary of it. The routes live under https://app.vibld.com/api/.

vibld.com lists the API in an API catalog at vibld.com/.well-known/api-catalog (RFC 9727), and the home page points at the catalog and the description in its Link header, so a tool that knows only the site’s name can find both.

Signing in

A request is signed in by the session token Clerk issues to somebody signed in at app.vibld.com, sent as Authorization: Bearer <token>. The token is issued by https://clerk.vibld.com and checked against its published keys. It is short-lived, so a script asks Clerk for a fresh one rather than storing it. There are no API keys.

Routes that build, preview, publish or spend also need an invitation to the beta. Without one they answer 403 with "reason": "access-refused", which is a different answer from the 401 a request with no valid token gets. Reading what an account already has, such as its projects, runs and balance, stays open to it.

Answers

  • Bodies are JSON, except the routes that stream a build’s progress, which answer with server-sent events, and GET /api/media/file, which answers with the stored image or video bytes.
  • A refusal is { "error": "..." }. The sentence is for a person and may change. Where a refusal has a stable name to branch on, it is in reason or code.
  • Requests are limited per account and per address, and a request over the limit is answered 429.

Checking it is up

app.vibld.com/api/health answers { "status": "ok" } without signing in. It only says the API is answering, not that every service behind it is.

What it leaves out

Administration, the payment and GitHub webhooks, and GitHub’s sign-in redirect are routes the builder has but nobody else calls, and the description does not include them.