> ## Documentation Index
> Fetch the complete documentation index at: https://acaas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From whisper to thunder in under a minute. Make your first ACAAS request, then explore the louder parts of the API.

This guide walks you through your first ACAAS request, then introduces the
endpoints you are most likely to reach for next. Total time: about sixty
seconds, plus however long it takes to find your terminal.

## Before you begin

You need:

* An API key. For the demo, any non-empty string works — except
  `acaas_banned_demo_key`, whose bullhorn has been revoked. In production,
  generate a key from the dashboard.
* A terminal with `curl`, or a Python or Node environment.
* Lowercase text that deserves to be louder.

The base URL is `https://api.acaas.example.com`. Every authenticated request
sends your key in the `X-API-Key` header.

## Step 1: Confirm the service is up

The `/v1/health` endpoint requires no authentication. Use it to verify
connectivity before you spend a request.

```bash theme={"dark"}
curl https://api.acaas.example.com/v1/health
```

A healthy response returns `status` and `version`:

```json theme={"dark"}
{
  "status": "ok",
  "version": "0.1.0"
}
```

## Step 2: Make your first shout

Send `POST /v1/shout` with the text you want amplified. The body is a single
JSON object with a `text` field.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.acaas.example.com/v1/shout \
    -H "X-API-Key: demo" \
    -H "Content-Type: application/json" \
    -d '{"text": "hello world"}'
  ```

  ```python Python theme={"dark"}
  import requests

  resp = requests.post(
      "https://api.acaas.example.com/v1/shout",
      headers={"X-API-Key": "demo"},
      json={"text": "hello world"},
  )
  resp.raise_for_status()
  print(resp.json()["result"])  # HELLO WORLD
  ```

  ```javascript Node theme={"dark"}
  const resp = await fetch("https://api.acaas.example.com/v1/shout", {
    method: "POST",
    headers: {
      "X-API-Key": "demo",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ text: "hello world" }),
  });

  if (!resp.ok) {
    throw new Error(`ACAAS request failed: ${resp.status}`);
  }

  const { result } = await resp.json();
  console.log(result); // "HELLO WORLD"
  ```
</CodeGroup>

## Step 3: Inspect the response

Every capitalization endpoint returns the same envelope:

```json theme={"dark"}
{
  "original": "hello world",
  "result": "HELLO WORLD",
  "characters_amplified": 11
}
```

* `original` — the text you sent in, returned verbatim.
* `result` — the text, but louder.
* `characters_amplified` — the count of characters that changed case.

## Add intensity with scream

When `/v1/shout` is not loud enough, reach for `/v1/scream`. It uppercases the
text and appends exclamation marks. Set `intensity` between `1` and `10` to
control how many.

```bash theme={"dark"}
curl https://api.acaas.example.com/v1/scream \
  -H "X-API-Key: demo" \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world", "intensity": 5}'
```

```json Response theme={"dark"}
{
  "original": "hello world",
  "result": "HELLO WORLD!!!!!",
  "characters_amplified": 11
}
```

## Try the experimental emphasis model

`/v1/emphasize` lets a model pick which words to bold instead of uppercasing
everything. Behavior is non-deterministic and tunable.

For request shape, the `emphasis_ratio` parameter, response fields, and
guidance on when to use it, see
[Experimental emphasis](/experimental-emphasis).

## Handle errors

Validation errors return HTTP `422` with a `detail` array. Other common
statuses are `401` (bad key), `413` (text too long), and `429` (rate limit).

For full status code coverage and copy-paste retry patterns, see
[Errors](/errors).

## Check your rate limits

`/v1/rate-limits` reports your remaining quota without consuming a request.

```bash theme={"dark"}
curl https://api.acaas.example.com/v1/rate-limits \
  -H "X-API-Key: demo"
```

The response includes `requests_remaining`, `resets_in_seconds`, and a
categorical `status` (`ok`, `approaching_limit`, `at_limit`). For proactive
pacing and the full `status` ladder, see [Rate limiting](/rate-limiting).

## Next steps

<CardGroup cols={2}>
  <Card title="Cookbook" icon="utensils" href="/cookbook/release-notes">
    Build a complete Python release-notes amplifier end-to-end.
  </Card>

  <Card title="Experimental emphasis" icon="wand-magic-sparkles" href="/experimental-emphasis">
    Tune the model that picks which words to bold.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/errors">
    Every status code and recommended recovery pattern.
  </Card>

  <Card title="Rate limiting" icon="gauge-high" href="/rate-limiting">
    Quota mechanics, the `status` ladder, and graceful backoff.
  </Card>
</CardGroup>