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.

curl https://api.acaas.example.com/v1/health

A healthy response returns status and version:

{
  "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.

cURL

curl https://api.acaas.example.com/v1/shout \
  -H "X-API-Key: demo" \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}'

Step 3: Inspect the response

Every capitalization endpoint returns the same envelope:

{
  "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.

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

Response

{
  "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.

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.

Check your rate limits

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

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.

Next steps

Cookbook

Build a complete Python release-notes amplifier end-to-end.

Experimental emphasis

Tune the model that picks which words to bold.

Errors

Every status code and recommended recovery pattern.

Rate limiting

Quota mechanics, the status ladder, and graceful backoff.