Set up with an AI agent

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`	`text/plain`	The llmstxt.org index: one line per page with its title, Markdown URL and description
`/llms-full.txt`	`text/plain`	Every page's Markdown, concatenated in navigation order
`/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.

shell

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:

shell

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.

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.

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:

Timings are milliseconds. word.start and word.end are integer milliseconds. audio_duration on the transcript is in seconds. Do not mix them.
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.
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.
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.
Retries need Idempotency-Key. Sending the same creation request twice without one creates two transcripts and bills twice. See Errors and limits.

Verify#

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

shell

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)'

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 — where keys come from, and who in a workspace can create them.