Module 09 · API
StellarFirm API example requests
Copyable example requests for the StellarFirm API with curl, the answers you get back, and what a failure looks like.
On this page
Each example uses curl. Replace <session token> with the token of the signed-in account you act for. See Authentication.
Check that the site is up#
bash curl -s https://stellarfirm.ai/api/health
The answer has "ok": true.
Read the site notice#
bash curl -s https://stellarfirm.ai/api/site-banner
When there is no notice:
json { "banner": null }
Ask whether an account may run#
bash curl -s https://stellarfirm.ai/api/entitlement \ -H "Authorization: Bearer <session token>"
An account on a trial:
json { "ok": true, "status": "trial", "trialEndsAt": "2026-10-15T09:00:00.000Z", "recheckAfterSeconds": 60 }
Read the credit balance#
bash curl -s https://stellarfirm.ai/api/credits/balance \ -H "Authorization: Bearer <session token>"
json { "credits": 120 }
What a failure looks like#
The same request with no session:
bash curl -s -i https://stellarfirm.ai/api/credits/balance
The answer is 401 Unauthorized:
json { "error": { "code": "signed_out", "message": "This route needs a signed-in StellarFirm account.", "hint": "Send the account's session token as a Bearer token in the Authorization header. See /docs/api/authentication.", "docs": "https://stellarfirm.ai/docs/api/errors" } }
An address that is not a route:
bash curl -s -i https://stellarfirm.ai/api/nothing-here
The answer is 404 Not Found with error.code set to not_found, in JSON.
Load the whole API into a tool#
bash curl -s https://stellarfirm.ai/openapi.json
The file is OpenAPI 3.1. Every route has a unique operationId, so a tool that turns an API into functions can use it as it is.