# Set up with an AI agent

Hand these docs to a coding agent and let it integrate Sandchest unaided — with llms.txt, raw Markdown URLs, an OpenAPI document, and a rules snippet for your repo.

Every page of these docs is plain Markdown behind the scenes, and every page is
served as Markdown as well as HTML. An agent never has to scrape rendered pages or
guess at an API. This page gives you the prompt, the URLs, and a snippet to drop
into your repository so future agent sessions already know about Sandchest.

## The prompt

Paste this into Claude Code, Cursor, Codex, or any agent that can fetch a URL.
Replace `<file>` with the audio you want transcribed.

```text
Add Sandchest speech-to-text to this project.
Docs: https://sandchest.com/llms.txt (index) — fetch https://sandchest.com/llms-full.txt for everything.
API key: read it from the SANDCHEST_API_KEY environment variable (never hardcode it).
Base URL: https://stt-api.sandchest.com
Use the official assemblyai package if it is already installed (change apiKey + baseUrl), otherwise @sandchest/sdk.
Transcribe <file>, print each word with its start/end in milliseconds, and add a small test.
```

If your agent can only fetch one page, give it
`https://sandchest.com/docs/quickstart.md`. It is self-contained.

## What is machine-readable

| URL | Content type | What it is |
| --- | --- | --- |
| [`/llms.txt`](/llms.txt) | `text/plain` | The [llmstxt.org](https://llmstxt.org) index: one line per page with its title, Markdown URL and description |
| [`/llms-full.txt`](/llms-full.txt) | `text/plain` | Every page's Markdown, concatenated in navigation order |
| [`/openapi.json`](/openapi.json) | `application/json` | OpenAPI 3.1 generated from the live API contract, not written by hand |
| `/docs/<slug>.md` | `text/markdown` | One page as Markdown, with its title and description at the top |
| `/docs.md` | `text/markdown` | This site's index page as Markdown |

Start with `/llms.txt`, then fetch only the pages you need. Reach for
`/llms-full.txt` when you want the whole thing in one request.

```bash
curl -sS https://sandchest.com/llms.txt
curl -sS https://sandchest.com/docs/transcripts.md
curl -sS https://sandchest.com/openapi.json | jq '.paths | keys'
```

## Content negotiation

Any `/docs/*` URL returns Markdown when you ask for it. Send an `Accept` header that
includes `text/markdown` (or `text/plain`) and does not include `text/html`:

```bash
curl -sS https://sandchest.com/docs/quickstart -H "Accept: text/markdown"
```

That returns the same bytes as `https://sandchest.com/docs/quickstart.md`. Browsers
send `Accept: text/html,...` and keep getting the rendered page, so a single link
works for both a person and an agent.

> [!TIP]
> Every rendered page also has a **Copy as Markdown** button and an **Open .md** link
> in its header, plus **Copy for agent**, which copies a one-line prompt pointing at
> that page's Markdown URL.

## Add it to your repository

Drop this into `CLAUDE.md`, `AGENTS.md`, or `.cursorrules` so every future agent
session already knows the shape of the integration.

```text title="CLAUDE.md"
## Speech-to-text: Sandchest

- API base URL: https://stt-api.sandchest.com
- Auth: `Authorization: $SANDCHEST_API_KEY` (a `Bearer ` prefix is also accepted).
  The key lives in the SANDCHEST_API_KEY environment variable. Never hardcode or log it.
- Docs index: https://sandchest.com/llms.txt — fetch the page you need as Markdown,
  e.g. https://sandchest.com/docs/api.md. OpenAPI: https://sandchest.com/openapi.json
- The API is AssemblyAI-compatible at /v2/*. If `assemblyai` is already a dependency,
  keep it and set `baseUrl`. Otherwise use `@sandchest/sdk`.
- Word timings (`start`, `end`) are milliseconds. `audio_duration` is seconds.
- GET /v2/transcript/:id returns the current state immediately. Poll it; do not
  expect the request to block until the transcript is ready.
- Unknown request options are rejected with HTTP 400, not ignored. Speaker
  diarization (`speaker_labels`, `speakers_expected`) and word boosting
  (`word_boost`, `boost_param`) are not supported.
- Errors are `{ "error": "..." }` with a meaningful status code. 402 means the
  workspace is out of credits; 429 means the per-minute rate limit was hit.
```

## What an agent needs to know first

If you are an agent reading this page, these are the five facts that prevent almost
every mistake:

1. **Timings are milliseconds.** `word.start` and `word.end` are integer milliseconds.
   `audio_duration` on the transcript is in seconds. Do not mix them.
2. **`GET` does not block.** Creating a transcript returns immediately with
   `status: "queued"`. Poll `GET /v2/transcript/:id` until `status` is `completed` or
   `error`. Both SDKs already do this for you.
3. **Unknown options are a 400, not a no-op.** Sandchest refuses to acknowledge a
   request it has silently dropped fields from. Send only the options in
   [Transcript options](/docs/transcripts).
4. **The upload endpoint takes raw bytes.** `POST /v2/upload` with
   `Content-Type: application/octet-stream` and the file as the body. It is not a
   multipart form. It returns `{ "upload_url": "..." }`, which you pass as `audio_url`.
5. **Retries need `Idempotency-Key`.** Sending the same creation request twice without
   one creates two transcripts and bills twice. See
   [Errors and limits](/docs/errors#retrying-safely).

## Verify

Confirm both representations of a page agree, and that the OpenAPI document is live:

```bash
curl -sS https://sandchest.com/docs/quickstart.md | head -3
curl -sS https://sandchest.com/docs/quickstart -H "Accept: text/markdown" | head -3
curl -sS https://sandchest.com/openapi.json | jq -r '.info.title, (.paths | keys | length)'
```

```text title="expected output"
# Quickstart

Get an API key, set one environment variable, and turn a local audio file into word-level timestamps — with the AssemblyAI SDK, the native SDK, or curl.
# Quickstart

Get an API key, set one environment variable, and turn a local audio file into word-level timestamps — with the AssemblyAI SDK, the native SDK, or curl.
Sandchest API
10
```

## Next

[Authentication](/docs/authentication) — where keys come from, and who in a workspace
can create them.