API Reference

The Samva API is organized around REST principles with an agent-native architecture. All API requests return JSON responses and use standard HTTP response codes.

Base URL

https://api.samva.app/v1

For development:

https://staging.api.samva.app/v1

Authentication

All API requests require authentication via API key. Include your API key in the X-API-Key header:

curl -H "X-API-Key: your-api-key-here" \
  https://api.samva.app/v1/messages

Getting Your API Key

1. Log in to your Samva account
2. Navigate to Settings → API Keys
3. Click Create API Key
4. Copy the API key (it's only shown once)

Security Best Practices

• Never commit API keys - Use environment variables
• Rotate regularly - Generate new keys periodically
• Use separate keys - Different keys for dev/staging/prod
• Revoke unused keys - Delete keys that are no longer needed

Learn more about authentication →

API Endpoints

Browse all available endpoints organized by service:

Core Messaging

• Messages - Send and manage messages across all channels
• Email - Email messaging, domains, threading, and management
• WhatsApp - WhatsApp Business API integration
• SMS - SMS messaging with carrier-grade delivery

Conversation Management

• Conversations - Cross-channel conversation threading
• Participants - Contact and participant management

Configuration

• Templates - Message template management
• Webhooks - Webhook endpoint configuration
• API Keys - API key management

Analytics & Operations

• Analytics - Usage metrics and insights
• Billing - Subscription and usage tracking
• Organizations - Organization management
• Attachments - File attachment management

Request Format

Headers

Request Body

All POST/PUT/PATCH requests accept JSON:

{
  "to": "+14155552671",
  "message": "Your verification code is 123456"
}

Response Format

Success Response

{
  "id": "msg_abc123",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z",
  "credits_used": 1
}

Error Response

{
  "error": {
    "code": "INVALID_PHONE_NUMBER",
    "message": "The phone number format is invalid",
    "details": {
      "field": "to",
      "value": "9876543210",
      "expected": "+919876543210 or E.164 format"
    }
  }
}

HTTP Status Codes

Rate Limiting

API requests are rate-limited. Check response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Pagination

List endpoints support pagination:

GET /v1/messages?page=2&limit=50

Parameters:

• page - Page number (default: 1)
• limit - Items per page (default: 20, max: 100)

Response:

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 245,
    "pages": 5
  }
}

Filtering & Sorting

# Filter by status
GET /v1/messages?status=delivered

# Sort by created date
GET /v1/messages?sort=-created_at

# Date range
GET /v1/messages?created_after=2024-01-01&created_before=2024-01-31

Idempotency

Prevent duplicate operations with idempotency keys:

curl -X POST https://api.samva.app/v1/messages/send \
  -H "X-Idempotency-Key: unique-request-id-123" \
  -d '{...}'

Webhooks

Receive real-time updates via webhooks:

curl -X POST https://api.samva.app/v1/webhooks \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks",
    "events": ["message.delivered", "message.failed"]
  }'

Learn more about webhooks →

SDK Support

Testing

Use test API keys (sk_test_*) for development:

• No charges applied
• Simulated delivery statuses
• Test phone numbers available

Support

Need help with the API?

• 📧 Support: support@samva.app
• 🐛 Report Issues: github.com/samva