> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Getting started with the Chirp API

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:

```bash theme={null}
curl https://api.buildwithchirp.com/v1/sms \
  -H "Authorization: Bearer YOUR_API_KEY"
```

See [Authentication](/api_reference/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](/api_reference/app-keys) and [Admin Keys](/administration_apis/admin-keys) for details.

## Request Format

All POST and PUT requests must include a `Content-Type: application/json` header and a JSON body:

```bash theme={null}
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:

```json theme={null}
{
  "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 a structured `error` object with a `type`, `message`, and optional fields for programmatic handling:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "message": "The phone number \"+1abc\" is not in E.164 format.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number",
    "param": "from"
  }
}
```

See [Errors](/api_reference/errors) for a full description of the error format, [Error Codes](/api_reference/error-codes) for a complete reference, and [Handling Errors](/api_reference/handling-errors) for integration guidance.

## Rate Limits

The API enforces rate limits to ensure fair usage. See [Rate Limits](/api_reference/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](/concepts/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.