# Introduction

> Build on Beam's API.

## Base URL

Base URLCopy
```
https://beam.aisync.link
```

## Authentication

Every request carries your workspace key in the x-api-key header. Keep it server-side. Never ship it in a web page or a mobile app.
curlCopy
```
curl https://beam.aisync.link/v1/messages/41 \
  -H "x-api-key: YOUR_WORKSPACE_KEY"
```

## Requests and responses

  - The API accepts JSON. Set Content-Type: application/json on every POST.
  - Responses are JSON. Success returns the resource; errors return { "error": "what went wrong" } with a matching HTTP status.
  - Phone numbers are accepted as US 10-digit, 11-digit, or full international format, and normalized automatically.

## Endpoints

  
| Endpoint | What it does | 
  
| POST /v1/messages | Send a message | 
  
| GET /v1/messages/:id | Get a message and its status | 
  
| DELETE /v1/messages/:id | Cancel a queued message | 
  
| GET /v1/messages/list | List recent messages | 
  
| GET /v1/conversations/:phone | Full history with a contact | 
  
| POST /v1/reactions | React to a contact's message | 
  
| POST /v1/typing | Show the typing indicator | 
  
| POST /v1/read | Send a read receipt | 
  
| GET /v1/contacts/:phone | Contact details and opt-out state | 
  
| GET /v1/availability/:phone | Blue-bubble support check | 
  
| GET /v1/numbers | The workspace's lines | 
  
| POST /t/:workspace/optin | New-lead webhook for CRM workflows | 

## Real-time events

Beam also pushes signed event webhooks to your endpoint the moment replies, bookings, handoffs, and opt-outs happen. Verify them with webhook signing.

## Be a good citizen

Do not poll GET /v1/messages/:id in a tight loop; once every few seconds is plenty. Sends you queue are paced for deliverability, so a burst of API calls never turns into a burst of texts.