SMS API documentation

API surface	Docs
OpenAPI / Swagger	Interactive docs · OpenAPI schema

REST API for sending SMS, managing SIMs and devices, and HTTP webhooks. Canonical prefix: /api/ (no version in the path).

Interactive OpenAPI: /api/docs/ · schema: /api/schema/.

Before you can use the API, sign in and create an access token, then replace YOUR_ACCESS_TOKEN.

Optional: omit sim_card to use your primary SIM; if it is unavailable, the next SIM by route priority is used as fallback. MCP agent

Responses & errors

Successful JSON responses use 200/201. Errors use a DRF-style body:

{
  "detail": "Error message"
}
/* or field errors: */
{
  "to_number": ["This field is required."]
}

Status	When
`400`	Validation error
`401`	Missing or invalid access token / JWT
`403`	Authenticated but not allowed
`404`	Unknown id
`429`	Rate limit / quota
`502`	Webhook test delivery failed (remote target)

Auth failure (curl)

curl -i \
    --header 'Accept: application/json' \
    --request GET https://www.tincansmartphone.com/api/sim-cards/
# → 401 {"detail":"Authentication credentials were not provided."}

List SIM cards

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request GET https://www.tincansmartphone.com/api/sim-cards/

Send SMS

curl \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --data '{"sim_card":"SIM_CARD_ID", "to_number":"<RECEIVER_PHONE_NUMBER>", "text": "Hello!"}' \
    --request POST https://www.tincansmartphone.com/api/messages/outbound/

List inbound SMS

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request GET https://www.tincansmartphone.com/api/messages/inbound/

Device telemetry

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request GET https://www.tincansmartphone.com/api/devices/<DEVICE_ID>/telemetry/

Webhooks

Create HTTP callbacks for SMS/SIM events. You can also manage webhooks via MCP tools create_webhook, list_webhooks, delete_webhook, test_webhook.

Event	Description
`sms.out.created`	Sms was sent to the Api for dispatch
`sms.out.sent`	The sms was marked as sent
`sms.in.received`	A sms was received
`simcard.added`	A sim card was added
`simcard.changed`	A sim card was changed
`simcard.removed`	A sim card was removed

Create webhook

curl \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --data '{"target": "https://example.com/hook", "event": "sms.in.received"}' \
    --request POST https://www.tincansmartphone.com/api/webhooks/

List webhooks

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request GET https://www.tincansmartphone.com/api/webhooks/

Test webhook

Sends a sample JSON body with "test": true to the hook URL and returns the remote status.

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request POST https://www.tincansmartphone.com/api/webhooks/<WEBHOOK_ID>/test/

Delete webhook

curl \
    --header 'Accept: application/json; indent=4' \
    --header 'Authorization: Token YOUR_ACCESS_TOKEN' \
    --request DELETE https://www.tincansmartphone.com/api/webhooks/<WEBHOOK_ID>/

Validation error example (missing fields) → 400 with field errors. Unknown id → 404 {"detail":"Not found."}.

MCP JSON-RPC: POST /mcp/ (public docs tools need no auth; phone tools use the same Token header). Open MCP console