# StellarFirm API example requests

> Copyable example requests for the StellarFirm API with curl, the answers you get back, and what a failure looks like.

Each example uses `curl`. Replace `<session token>` with the token of the signed-in account you act for. See [Authentication](/docs/api/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.

## Related

- [Endpoints](/docs/api/endpoints)
- [Errors](/docs/api/errors)

---

Source: https://stellarfirm.ai/docs/api/examples