Skip to main content
The Chirp API is a REST API that allows you to send and receive SMS and MMS messages programmatically.

​
Base URL

All API requests use the following base URL: 
https://api.buildwithchirp.com

​
Authentication

The Chirp API uses API keys for authentication. Include your API key in the Authorization header as a Bearer token: 
curl https://api.buildwithchirp.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY"
See Authentication for more details.

​
API Key Types

Chirp provides two types of API keys: App Keys (sk_live_app_* / sk_test_app_*) Used for application-level operations:
  • Sending messages
  • Managing webhooks
  • Viewing message logs
Admin Keys (sk_admin_*) Used for organization-level operations:
  • Creating and managing applications
  • Managing phone numbers
  • Team and billing administration
See App Keys and Admin Keys for details.

​
Request Format

All POST and PUT requests must include a Content-Type: application/json header and a JSON body: 
curl -X POST https://api.buildwithchirp.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+15551234567",
    "to": ["+15559876543"],
    "text": "Hello from Chirp!"
  }'

​
Response Format

All responses are returned as JSON: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "from": "+15551234567",
  "to": ["+15559876543"],
  "text": "Hello from Chirp!",
  "type": "SMS",
  "status": "QUEUED",
  "createdAt": "2024-01-15T12:00:00.000Z"
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

​
Error Responses

Error responses include an error field with a description: 
{
  "error": "Invalid phone number format"
}

​
Rate Limits

The API enforces rate limits to ensure fair usage. See Rate Limits for details.

​
Test Mode

Use test API keys (sk_test_app_*) to test your integration without sending real messages or incurring charges. Test mode works with the Playground for simulated messaging.

​
Versioning

The current API version is v1. The version is included in the URL path: 
https://api.buildwithchirp.com/v1/sms

​
OpenAPI Specification

The complete API specification is available in OpenAPI format. You can use this to generate client libraries or explore the API interactively.
⌘I