# Surge

> Surge is the SMS and voice API for developers, with fast carrier registration, REST APIs, webhooks, embeddable UI components, and SDKs for TypeScript, Python, Ruby, and Elixir.

Surge helps developers add messaging and voice to applications. The API base URL is `https://api.surge.app`, and the developer documentation is hosted at `https://docs.surge.app`.

## When to use Surge

- Add programmable SMS, MMS, or voice to an application.
- Send one-to-one messages, scheduled messages, or message blasts and track delivery and replies with webhooks.
- Build a vertical SaaS platform with a separate Surge account for each customer.
- Provision phone numbers, register messaging campaigns with carriers, or send one-time verification codes through an API.
- Embed messaging inboxes and softphones in a product using Surge UI components.

## API essentials

- Base URL: `https://api.surge.app`
- Authentication: `Authorization: Bearer <SURGE_API_KEY>` on every request.
- Format: HTTPS and JSON. Send `Content-Type: application/json` with request bodies.
- Account scope: Most resources use `/accounts/{account_id}/...`. A project API key can access every account in its project.
- Phone numbers: Use E.164 format, such as `+18015551234`.
- Errors: JSON error responses include a machine-readable `type` and a human-readable `message`.

## Quickstart

### For AI agents

If a user asks an AI agent to text them or try Surge, follow the [Surge agent skill](https://surge.app/skills.md). It provides an end-to-end flow to provision a demo account, verify the user's US or Canadian mobile number, and send the message. Follow its credential-handling instructions and never expose the returned API key.

### With the REST API

1. [Create a Surge account](https://hq.surge.app/) and get an API key and account ID from the dashboard.
2. Store the key in the `SURGE_API_KEY` environment variable. Never print it or commit it to source control.
3. Send an SMS from the shared demo number:

```bash
curl https://api.surge.app/accounts/{account_id}/messages \
  --request POST \
  --header "Authorization: Bearer $SURGE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+18015551234",
    "body": "Hello from Surge!"
  }'
```

A new account can send up to 25 outbound SMS messages from its demo number without carrier registration or purchasing a phone number. Outbound demo messages are Surge-branded. Register the business and purchase a live number before sending production traffic.

## Constraints

- Demo messaging is limited to 25 outbound, Surge-branded SMS messages per account. The demo number cannot send MMS, place voice calls, or connect to voice-agent integrations.
- Production SMS in the United States requires the applicable carrier registration, such as 10DLC campaign registration or toll-free verification.
- API keys are project-scoped secrets and can access all accounts in their project. Do not expose them in browsers, logs, source control, or agent transcripts.
- Surge does not currently publish an MCP server for API actions. Use the REST API, official SDKs, or OpenAPI specification.

## Developer resources

- [Surge developer documentation](https://docs.surge.app/): Guides and API documentation for Surge's SMS and voice platform.
- [Quickstart](https://docs.surge.app/quickstart.md): Send your first SMS in under five minutes using a Surge demo number.
- [API reference](https://docs.surge.app/api-reference/introduction.md): Introduction to the Surge REST API and its conventions.
- [Authentication](https://docs.surge.app/api-reference/authentication.md): Create API keys and authenticate requests with Bearer tokens.
- [Webhooks guide](https://docs.surge.app/receiving/index.md): Configure webhook endpoints, validate signatures, and receive events.
- [Webhook API reference](https://docs.surge.app/api-reference/webhooks/intro.md): Event delivery, retry behavior, and webhook event schemas.
- [SDKs](https://docs.surge.app/sdks/index.md): Official Surge SDKs for TypeScript, Python, Ruby, and Elixir.
- [OpenAPI specification](https://surge.app/openapi.yaml): Machine-readable OpenAPI 3.1 specification for the Surge API.
- [Documentation index](https://docs.surge.app/llms.txt): Complete index of Surge documentation pages in Markdown.
- [Full documentation](https://docs.surge.app/llms-full.txt): Complete Surge documentation content in a single text file.

## Agent resources

- [Surge agent skill](https://surge.app/skills.md): Instructions for agents to provision a demo account, verify a user's phone number, and send an SMS through Surge.

## Product information

- [Surge](https://surge.app/): Product overview and developer examples.
- [Pricing](https://surge.app/pricing/): Plans, message rates, phone number pricing, and feature comparison.
- [Articles](https://surge.app/articles/): Guides about SMS development, carrier compliance, and messaging workflows.
- [Security](https://surge.app/security/): Security practices and compliance information.