Back to Dashboard

Developer API Reference

Welcome to the CurlSMS developer documentation. CurlSMS provides a highly optimized, developer-first HTTP API designed to send SMS instantly via your own decentralized physical hardware gateway. Our platform requires no complex enterprise agreements, contracts, or high volume minimums. Simply register via Discord, synthesize your API key, and begin transmitting messages in seconds.

Base API Gateway URL: All API requests documented below should be transmitted directly to the host: https://curl-sms.com.

Authentication

All endpoints on the CurlSMS API are securely authenticated using a private API credential key. Keys are generated instantly inside your Discord-connected web dashboard and start with the prefix cs_live_.

You can authenticate your HTTP requests in any of the following three ways (we highly recommend utilizing the Authorization header):

1. Authorization Bearer Header (Recommended)

Pass your token inside the standard HTTP headers:

Authorization: Bearer cs_live_YOUR_API_KEY

2. Query Parameters

Append your key directly to the URL as a query string parameter:

https://curl-sms.com/api/sms/send?api_key=cs_live_YOUR_API_KEY

3. Request Body Parameter

Include the key directly inside the JSON request body matching the payload property "api_key".

Send Live SMS

Transmit an outbound SMS immediately. The gateway will validate your account parameters, allocate mapping logs, and securely queue the message to be picked up and transmitted by your physical gateway device.

POST /api/sms/send

JSON Request Body Parameters

Parameter Type Requirement Description
to / recipient string Required The recipient's phone number including the country code (e.g. +491639650125).
body / message / text string Required The SMS text content (UTF-8 formatted). Multi-part message segments are supported automatically.

Sample JSON Request Payload

{
  "to": "+491639650125",
  "message": "Hello, this is a live transmission test from my custom script!"
}

Sample JSON Response (200 OK)

{
  "success": true,
  "message_id": 218,
  "status": "pending",
  "recipient": "+491639650125",
  "message": "Hello, this is a live transmission test from my custom script!",
  "cost": 0.00,
  "remaining_german_allowance": 298
}

Sample Error Response (403 Forbidden)

{
  "error": "Monthly SMS transmission limit exceeded. Upgrade your subscription plan in the dashboard to increase allowance."
}

Multi-Language Code Snippets

cURL

curl -X POST https://curl-sms.com/api/sms/send \
  -H "Authorization: Bearer cs_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+491639650125",
    "message": "Triggered via terminal cURL script."
  }'

Node.js

const fetch = require('node-fetch');

fetch('https://curl-sms.com/api/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer cs_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    to: '+491639650125',
    message: 'Triggered via Node.js fetch.'
  })
}).then(res => res.json()).then(console.log);

Python

import requests

payload = {
    "to": "+491639650125",
    "message": "Triggered via Python requests library."
}
headers = {
    "Authorization": "Bearer cs_live_YOUR_API_KEY"
}
response = requests.post(
    "https://curl-sms.com/api/sms/send", 
    json=payload, 
    headers=headers
)
print(response.json())

Go

package main

import (
    "bytes"
    "net/http"
)

func main() {
    jsonPayload := []byte(\`{"to":"+491639650125","message":"Triggered via Go SDK."}\`)
    req, _ := http.NewRequest("POST", "https://curl-sms.com/api/sms/send", bytes.NewBuffer(jsonPayload))
    req.Header.Set("Authorization", "Bearer cs_live_YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Query Message State

Verify the real-time transmission and delivery status of any sent SMS. Our database architecture isolates message states securely to ensure developers can only query and audit message IDs that are mapped directly to their own account credentials.

GET /api/sms/status/:message_id

Path Parameters

Parameter Type Requirement Description
message_id integer Required The unique integer message identifier returned by the sending API (e.g. 218).

Sample JSON Response (200 OK)

{
  "success": true,
  "message_id": 218,
  "recipient": "+491639650125",
  "message": "Hello, this is a live transmission test from my custom script!",
  "status": "sent",
  "error": null,
  "created_at": "2026-05-26T13:05:55.000Z",
  "updated_at": "2026-05-26T13:05:56.000Z"
}

cURL Code Example

curl -X GET https://curl-sms.com/api/sms/status/218 \
  -H "Authorization: Bearer cs_live_YOUR_API_KEY"

List Sent SMS

Retrieve a full, paginated history of all SMS messages sent by your account. This returns complete status codes, target country allocations, error receipts, and physical device update timestamps.

GET /api/sms/list

Sample JSON Response (200 OK)

{
  "success": true,
  "count": 1,
  "messages": [
    {
      "message_id": 218,
      "recipient": "+491639650125",
      "message": "Hello, this is a live transmission test from my custom script!",
      "status": "sent",
      "error": null,
      "created_at": "2026-05-26T13:05:55.000Z",
      "updated_at": "2026-05-26T13:05:56.000Z"
    }
  ]
}

cURL Code Example

curl -X GET https://curl-sms.com/api/sms/list \
  -H "Authorization: Bearer cs_live_YOUR_API_KEY"

Decentralized Gateway Architecture

CurlSMS uses a highly resilient hybrid architecture to bypass the high maintenance costs and limits of commercial cellular carriers. When you call our API, the payload is mapped to a secure relational database record on a centralized, redundant host.

Your physical gateway device (connected locally via synology infrastructure) continuously scans the centralized queue for pending messages, handles the direct hardware cellular transmission, and commits status updates and error details back to the master database. The API background poller captures this feedback, logs the audit trail, and clears the active transaction pipeline instantly.

Cost Metrics & Spend Limits

To support high scalability without risk of unexpected overages, all accounts enjoy a robust cost and spending system: