StellarFirm API endpoints

The routes below are the whole public StellarFirm API. Each one is also in the OpenAPI file, with its parameters and answer schemas. A route answers 405 with an Allow header for any method not listed here.

At a glance#

GET /api/health#

Answers 200 with ok: true while the web app is running. Use it for an uptime check.

{ "ok": true, "service": "...", "surface": "ui", "agent": "not-hosted-here" }

GET /api/site-banner#

The notice shown at the top of the site, or null when there is none. It is the same for everyone and may be cached for half a minute.

GET /api/entitlement#

Says whether the signed-in account may run: an active trial, a licence, or free Hobby after the trial. Only a 200 with ok: true means the account may run. It is never cached.

A 200 answer for an account that has the premium models also carries premiumModels: true and codingSubscription: true. The premium models are open to an account on its trial, with a licence, in a university, or on a paid plan. An account on the free plan after its trial gets neither field, and a client reads a missing field as no. The free plan keeps running on the open models.

A 200 answer also carries assistantLimit, how many named assistants the account's plan lets it hire, and teamLimit, how many teams of assistants it lets it have. A missing teamLimit means the plan puts no limit on teams, so a client must never read it as zero. Neither limit removes anything: an account that already has more keeps all of it and can still rename, move and delete, and only a new assistant or team is held back.

Every answer except 200 also carries the standard error object. See Errors.

GET /api/credits/balance#

The account's balance as a number of StellarFirm credits, never money. Answers { "credits": 120 } for example. It answers 503 with the code balance_unavailable when the balance cannot be read.

POST /api/email/unsubscribe#

One-click unsubscribe from the later onboarding emails. Send the token from the link in the email as the query parameter. It answers 200 with a plain text line, 400 with invalid_token for a token that is not valid, and 502 with upstream_failed when the later emails are still scheduled and you should try again.

GET /api/try/status#

The free trial on the landing page gives a visitor with no account a few free prompts with three assistants: the Coder, Marketing and the Product owner. This route says whether the trial is open and how many prompts the visitor has left. The visitor is told apart by network address, with no sign-in and no cookie. It counts nothing and is never cached. It answers 404 with the code not_found while the trial is switched off.

{ "open": true, "promptsLeft": 3, "promptsPerVisitor": 3 }

POST /api/try/prompt#

Sends one free prompt. The body is JSON, and the request must come from a person in a browser on the site: a script is refused with try_refused.

{ "assistant": "coder", "content": "Make a one page site for a bakery." }

A visitor may run one prompt at a time. The assistants work on their own computers, so a prompt can take several minutes, and it stops after about twelve. A step that would need an Approve never runs: the answer stops there and says so.

Send Accept: text/event-stream to read the work as it happens. Each event is one JSON object on a data: line, and a comment line now and then keeps the connection open.

Without that header, the final done event comes back as JSON, with the artifacts in one list.

A prompt that is refused before it starts answers the shared error shape with a status and code: 429 try_used_up when the visitor used every free prompt, 429 try_busy while a prompt is running or too many run at once, 503 try_ended when this month's trial is used up (with reopensOn), 403 try_refused when the check that a person sent it fails, and 404 not_found while the trial is switched off.

Unknown routes#

Any other address under /api answers 404 with the error code not_found, in JSON, never an HTML page.

Related#

• Authentication
• Example requests
• Errors