# Documentation

Description: Bootstrap route for agents implementing against Surge.
Related: /docs/overview/what-is-surge, /docs/quickstart, /docs/registration/api-walkthrough, /docs/receiving, /docs/receiving/events, /docs/verifications/send-and-verify, /sdks/typescript, /api-reference/introduction

Use this page as the machine-first index for the Surge docs site.

## Bootstrap

1. Fetch `/.well-known/agent.json`.
2. Read `/skill.md`.
3. Use `/api/docs?query=...` to find the right workflow page inside `/docs`.
4. Read `/docs/<slug>.md` for task pages instead of scraping HTML.
5. Use the public OpenAPI spec for exact endpoint and webhook schemas.

## What This Site Optimizes

- The public machine-readable contract is strongest for the `/docs` section.
- `/docs.md` and `/docs/<slug>.md` are the primary machine routes.
- MCP and search are currently scoped to the Documentation section.
- SDK pages and API reference pages are still useful, but treat them as companion routes unless the agent spec advertises broader markdown coverage.

## Platform Model

- Surge uses a `Platform -> Account -> User` hierarchy.
- Most API resources are account-scoped and include `{account_id}` in the path.
- Verifications, attachments, and some by-id reads are not account-scoped.
- If you are building a multi-tenant SaaS product, default to one Surge account per customer.

## Best Next Page By Task

- First successful SMS send: `/docs/quickstart.md`
- Production registration and number readiness: `/docs/registration/api-walkthrough.md`
- Webhook endpoint setup and signature verification: `/docs/receiving.md`
- Event taxonomy and production state transitions: `/docs/receiving/events.md`
- OTP / verification flow: `/docs/verifications/send-and-verify.md`
- TypeScript implementation details: `/sdks/typescript`
- Exact HTTP schemas: `https://api.surge.app/openapi.json` and the human API reference pages under `/api-reference`

## Integration Gotchas

- New accounts send from a shared demo number first; the cap is 25 outbound messages per account.
- `campaign.approved` alone does not make a number production-ready. Wait for `phone_number.attached_to_campaign` for each number.
- Webhooks use the Standard Webhooks header set: `webhook-id`, `webhook-timestamp`, and `webhook-signature`.
- The old `surge-signature` header is deprecated.
- Phone numbers should be E.164 with a leading `+`.

## Verification Expectations

- A quickstart send should return a message ID with `msg_` and deliver to the recipient within about 60 seconds.
- A registration flow should produce `acct_`, `cpn_`, and `pn_` IDs and eventually both approval and attachment webhook signals.
- A webhook handler should verify the signature against the raw request body and return `2xx` quickly.