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

# Hany REST API Reference: Endpoints and Integration

> The Hany REST API lets you send SMS, manage Sender IDs, retrieve delivery reports, and integrate communication flows into your applications.

The Hany REST API gives you programmatic access to Hany's business communication platform. You can send single or bulk SMS messages, manage your Sender IDs, pull delivery reports, and build end-to-end communication workflows — all over standard HTTPS using JSON. Whether you're building a transactional notification system or a large-scale marketing campaign, the API is designed to be predictable, well-structured, and easy to integrate.

## Base URL

All API requests are made to the following base URL:

```text theme={null}
https://api.hany.tools/v1
```

Every endpoint path in this reference is appended to this base URL. For example, to send an SMS you call `POST https://api.hany.tools/v1/sms/send`.

## Request Format

* Set the `Content-Type` header to `application/json` on all requests that include a body.
* Send request bodies as raw JSON.
* All responses are returned as JSON, including errors.

```bash theme={null}
# Example request shape
curl -X POST https://api.hany.tools/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{ "to": "+233XXXXXXXXX", "from": "YourBrand", "message": "Hello!" }'
```

## Authentication

Every request to the Hany API must include a valid API key as a Bearer token in the `Authorization` header. You can generate your key from the Hany dashboard.

See the [Authentication](/api-reference/authentication) page for full details on obtaining your key, using it in requests, and security best practices.

## Rate Limits

<Info>
  API rate limits are enforced to ensure fair usage and platform stability. If your integration requires a higher throughput, reach out to [support@hany.tools](mailto:support@hany.tools) to discuss a plan that fits your volume needs.
</Info>

When you exceed the rate limit, the API returns a `429 Too Many Requests` response. Implement exponential backoff in your retry logic to handle these gracefully. See the [Errors](/api-reference/errors) page for more detail.

## Versioning

The API version is embedded in the URL path (e.g., `/v1`). This ensures that breaking changes never affect your existing integration without warning.

When a new version is released, the previous version will continue to be supported for a defined sunset period. You will receive advance notice of any deprecation timeline so you have ample time to migrate.

## Available Endpoints

The following endpoints are currently live and available to all Hany accounts:

| Endpoint                    | Description                                        |
| --------------------------- | -------------------------------------------------- |
| `POST /sms/send`            | Send a single SMS to one recipient                 |
| `POST /sms/bulk`            | Send a bulk SMS campaign to multiple recipients    |
| `GET /sms/sender-ids`       | List all Sender IDs registered on your account     |
| `POST /sms/sender-ids`      | Register a new Sender ID for approval              |
| `GET /sms/delivery-reports` | Retrieve delivery status reports for sent messages |

<Note>
  IVR, USSD, Email, and Payments endpoints are coming soon. Watch the changelog for announcements.
</Note>

## Quick Links

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to generate your API key and authenticate every request.
  </Card>

  <Card title="Send SMS" icon="message" href="/api-reference/sms/send">
    Send a single SMS message to any phone number.
  </Card>

  <Card title="Bulk Send" icon="paper-plane" href="/api-reference/sms/bulk-send">
    Launch a bulk SMS campaign to multiple recipients at once.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Receive real-time delivery and event notifications via webhooks.
  </Card>
</CardGroup>