https://tinetech.org/v1

curl https://tinetech.org/v1/balance \
  -H "Authorization: Bearer tine_live_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

// Single-resource
{
  "data": { ... }
}

// List
{
  "data": [ ... ],
  "next_cursor": "2026-09-18T12:00:00.000Z"  // null when no further pages exist
}

{
  "error": {
    "code": "insufficient_funds",
    "message": "Insufficient credit balance to cover the per-request API fee ...",
    "request_id": "req_a1b2c3d4e5f6g7h8i9j0"
  }
}

# Page 1
curl "https://tinetech.org/v1/calls?limit=25" \
  -H "Authorization: Bearer tine_live_..."

# Page 2 — pass next_cursor from the page 1 response as before=
curl "https://tinetech.org/v1/calls?limit=25&before=2026-09-15T08:30:00.000Z" \
  -H "Authorization: Bearer tine_live_..."

curl https://tinetech.org/v1/messages \
  -H "Authorization: Bearer tine_live_..." \
  -H "Idempotency-Key: 6f1c2d0e-7b9a-4c55-9a3e-2f0d8c1b7a41" \
  -H "Content-Type: application/json" \
  -d '{"from": "+12125550100", "to": "+12125550199", "body": "Your code is 4821"}'

{
  "data": {
    "balance": 52.07,
    "currency": "USD",
    "plan_credit": 12.07,
    "plan_credit_expires_at": "2026-11-18T00:00:00.000Z"
  }
}

curl https://tinetech.org/v1/balance \
  -H "Authorization: Bearer tine_live_..."

curl https://tinetech.org/v1/numbers \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "phone_number": "+12125551234",
      "country_code": "US",
      "is_primary": true,
      "subscription_status": "active",
      "twilio_sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "purchased_at": "2026-08-01T09:30:00.000Z"
    },
    {
      "phone_number": "+12125559876",
      "country_code": "US",
      "is_primary": false,
      "subscription_status": "active",
      "twilio_sid": "PNyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
      "purchased_at": "2026-09-12T10:00:00.000Z"
    }
  ]
}

curl "https://tinetech.org/v1/numbers/available?country=US&area_code=212&limit=5" \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "phone_number": "+12125550001",
      "friendly_name": "(212) 555-0001",
      "country_code": "US",
      "region": "NY",
      "capabilities": {
        "sms": true,
        "voice": true,
        "mms": true
      }
    }
  ]
}

curl -X POST https://tinetech.org/v1/numbers/purchase \
  -H "Authorization: Bearer tine_live_..." \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+12125550001"}'

{
  "data": {
    "phone_number": "+12125550001",
    "country_code": "US",
    "twilio_sid": "PNxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "purchased_at": "2026-09-19T04:50:00.000Z"
  }
}

curl "https://tinetech.org/v1/messages?number=%2B12125551234&limit=20" \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "id": "msg_abc123",
      "direction": "outbound",
      "from": "+12125551234",
      "to": "+19175550000",
      "body": "Hello from TINE!",
      "media_url": [],
      "status": "delivered",
      "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "is_read": true,
      "created_at": "2026-09-18T10:00:00.000Z"
    }
  ],
  "next_cursor": null
}

curl -X POST https://tinetech.org/v1/messages \
  -H "Authorization: Bearer tine_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12125551234",
    "to": "+19175550000",
    "body": "Hello from TINE!"
  }'

{
  "data": {
    "id": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "direction": "outbound",
    "from": "+12125551234",
    "to": "+19175550000",
    "body": "Hello from TINE!",
    "media_url": [],
    "status": "queued",
    "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "segments": 1,
    "price": 0.05,
    "created_at": "2026-09-19T04:50:00.000Z"
  }
}

curl -X POST https://tinetech.org/v1/messages \
  -H "Authorization: Bearer tine_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+12125551234",
    "to": "+19175550000",
    "body": "Check this out",
    "media_url": ["https://example.com/photo.jpg"]
  }'

curl "https://tinetech.org/v1/calls?direction=outbound&limit=10" \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "id": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "from": "+12125551234",
      "to": "+19175550000",
      "direction": "outbound",
      "status": "completed",
      "duration_seconds": 93,
      "created_at": "2026-09-18T09:00:00.000Z"
    }
  ],
  "next_cursor": null
}

curl https://tinetech.org/v1/calls/CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/recording \
  -H "Authorization: Bearer tine_live_..."

{
  "data": {
    "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "recording_url": "https://api.twilio.com/2010-04-01/Accounts/.../Recordings/RE....mp3",
    "recording_duration": 93,
    "has_voicemail": false
  }
}

curl https://tinetech.org/v1/voicemails \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "id": "vm_abc123",
      "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "from": "+19175550000",
      "to": "+12125551234",
      "recording_url": "https://api.twilio.com/2010-04-01/Accounts/.../Recordings/RE....mp3",
      "recording_duration": 24,
      "listened": false,
      "created_at": "2026-09-17T14:30:00.000Z"
    }
  ],
  "next_cursor": null
}

curl https://tinetech.org/v1/billing/history \
  -H "Authorization: Bearer tine_live_..."

{
  "data": [
    {
      "id": "txn_abc123",
      "type": "sms_outbound",
      "type_label": "Outbound SMS",
      "amount": -0.05,
      "balance_after": 20.02,
      "description": "SMS to +19175550000",
      "created_at": "2026-09-18T10:00:00.000Z"
    },
    {
      "id": "txn_abc124",
      "type": "topup",
      "type_label": "Credit Top-Up",
      "amount": 50.00,
      "balance_after": 70.07,
      "description": "Auto-recharge",
      "created_at": "2026-09-17T08:00:00.000Z"
    }
  ],
  "next_cursor": null
}

curl -X POST https://tinetech.org/v1/voice/token \
  -H "Authorization: Bearer tine_live_..."

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "identity": "dev:uid_abc123",
  "ttl": 3600
}

import { Device } from '@twilio/voice-sdk';

// 1. Get a token from your backend (don't expose your API key client-side)
const res = await fetch('/your-backend/voice-token', { method: 'POST' });
const { token } = await res.json();

// 2. Initialise the Device
const device = new Device(token, { logLevel: 1 });
await device.register();

// 3. Make an outbound call
const call = await device.connect({
  params: { To: '+19175550000' },
});

// 4. Refresh before expiry (3600 s)
device.updateToken(await fetchNewToken());

{
  "id": "evt_6f1c0a9e2b7d4c3a1e5f0b8d",
  "event": "message.received",
  "created_at": "2026-10-03T10:00:00.000Z",
  "data": {
    "id": "-OaB3xYz12AbCdEfGhIj",
    "message_sid": "SM0123456789abcdef0123456789abcdef",
    "direction": "inbound",
    "from": "+14155550123",
    "to": "+12025550188",
    "body": "Hi, is this still available?",
    "media_url": [],
    "segments": 1,
    "status": "received",
    "created_at": "2026-10-03T10:00:00.000Z"
  }
}

"data": {
  "id": "SM0123456789abcdef0123456789abcdef",
  "message_sid": "SM0123456789abcdef0123456789abcdef",
  "direction": "outbound",
  "from": "+12025550188",
  "to": "+14155550123",
  "status": "undelivered",        // "delivered" for message.delivered
  "error_code": 30003             // carrier error code, null when delivered
}

"data": {
  "id": "CA0123456789abcdef0123456789abcdef",
  "direction": "inbound",
  "from": "+14155550123",
  "to": "+12025550188",
  "status": "completed",          // or no-answer, busy, failed, canceled
  "duration_seconds": 74,
  "created_at": "2026-10-03T09:58:41.000Z",
  "ended_at": "2026-10-03T10:00:02.000Z"
}

import crypto from 'crypto';

export function verifyWebhook(signingSecret, req) {
  const timestamp = req.headers['x-tine-timestamp'];
  const sigHeader = req.headers['x-tine-signature'];  // "v1=<hex>"
  const rawBody   = req.rawBody;                       // unparsed request body string

  // 1. Reject stale deliveries (> 5 min)
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
  if (age > 300) throw new Error('Webhook timestamp too old');

  // 2. Compute expected signature
  const payload  = `${timestamp}.${rawBody}`;
  const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(payload)
    .digest('hex');

  // 3. Constant-time comparison
  const received = (sigHeader ?? '').replace('v1=', '');
  const valid = crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(received.padEnd(expected.length, '0'), 'hex'),
  );

  if (!valid) throw new Error('Invalid webhook signature');
}

import hmac, hashlib, time

def verify_webhook(signing_secret: str, timestamp: str, raw_body: str, sig_header: str) -> bool:
    # Reject stale deliveries (> 5 min)
    age = int(time.time()) - int(timestamp)
    if age > 300:
        raise ValueError("Webhook timestamp too old")

    payload  = f"{timestamp}.{raw_body}"
    expected = hmac.new(signing_secret.encode(), payload.encode(), hashlib.sha256).hexdigest()
    received = sig_header.replace("v1=", "")

    if not hmac.compare_digest(expected, received):
        raise ValueError("Invalid webhook signature")
    return True