API Reference

Base URL: https://www.smsforai.com/api/v1

Authentication

All authenticated endpoints require a Bearer token in the Authorization header.

Authorization: Bearer smsai_<your-token>
GET /api/v1 Public

API Info

Returns API version, status, and available endpoints.

Response

{ "api": "SMS for AI", "version": "1.0", "status": "ok" }
GET /api/v1/me 🔑 Auth required

Token Info

Get details about the current API token and authenticated user.

Response

{
  "token": { "id": 1, "name": "My Agent", "permissions": ["sms:send"] },
  "user": { "name": "Alice", "email": "alice@example.com", "credits": 12.345678 }
}
GET /api/v1/balance 🔑 Auth required

Account Balance

Get the current credit balance of the authenticated account.

Response

{ "credits_usd": 12.345678 }
GET /api/v1/countries 🔑 Auth required

Country Prices

Get a list of all active countries and their per-SMS prices in USD.

Response

[
  { "country_code": "US", "country_name": "United States", "dial_code": "+1", "price_usd": 0.01 },
  ...
]
POST /api/v1/sms/send 🔑 Auth required

Send SMS

Send an SMS message. Your token must have the 'sms:send' permission.

Request Body

{
  "to": "+12025551234",       // E.164 format, required
  "body": "Hello!",          // message text, max 1600 chars
  "sender_id": "MyApp"       // optional alphanumeric sender ID
}

Response

{
  "id": 42,
  "status": "sent",
  "to": "+12025551234",
  "price_usd": 0.01,
  "nvia_message_id": "abc123"
}
GET /api/v1/sms 🔑 Auth required

List SMS

List sent messages. Supports ?status=sent|delivered|failed and pagination.

Response

{ "data": [...], "links": { ... }, "meta": { ... } }
GET /api/v1/sms/{id} 🔑 Auth required

Get SMS

Get a specific SMS by ID.

Response

{ "id": 42, "status": "delivered", "to": "+12025551234", ... }

Error Codes

HTTP Meaning
401 Missing or invalid Bearer token
403 Token lacks the required permission, IP not whitelisted, or spending limit reached
402 Insufficient credits to send SMS
422 Validation error — check request body
429 Rate limit exceeded (per-minute or per-day)
500 Internal server error or SMS gateway failure

Code Examples

Python

import requests

TOKEN = "smsai_YourTokenHere"
BASE  = "https://www.smsforai.com/api/v1"

resp = requests.post(
    f"{BASE}/sms/send",
    headers={"Authorization": f"Bearer {TOKEN}", "Accept": "application/json"},
    json={
        "to": "+12025551234",
        "body": "Your OTP is 482910. Reply STOP to opt out.",
        "sender_id": "MYAPP"
    }
)
data = resp.json()
print(data["sms"]["status"], data["sms"]["id"], data["sms"]["price_usd"])

JavaScript / Node.js

const res = await fetch("https://www.smsforai.com/api/v1/sms/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer smsai_YourTokenHere",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    to: "+12025551234",
    body: "Your OTP is 482910.",
    sender_id: "MYAPP"
  })
});
const data = await res.json();
console.log(data.sms.status, data.sms.id, data.balance);

cURL

curl -X POST https://www.smsforai.com/api/v1/sms/send \
  -H "Authorization: Bearer smsai_YourTokenHere" \
  -H "Content-Type: application/json" \
  -d '{"to":"+12025551234","body":"Your OTP is 482910.","sender_id":"MYAPP"}'

MCP (Model Context Protocol) Setup

SMS for AI exposes a native MCP server at https://www.smsforai.com/api/mcp. Add it to claude_desktop_config.json and Claude will discover send_sms, get_balance, and list_sms automatically.

claude_desktop_config.json

{
  "mcpServers": {
    "smsforai": {
      "url": "https://www.smsforai.com/api/mcp",
      "headers": {
        "Authorization": "Bearer smsai_YourTokenHere"
      }
    }
  }
}

Restart Claude Desktop after saving. The SMS tools appear in the tools panel automatically.