Skip to main content
The ShingleAI API provides programmatic access to your business communication data, including messages, contacts, customers, and businesses. Use it to build integrations, automate workflows, and extend ShingleAI’s capabilities.

​
Base URL

All API requests should be made to: 
https://api.shingleai.com/v1
Do not include a trailing slash in the base URL. Endpoints are appended directly, e.g., https://api.shingleai.com/v1/contacts.
The API is versioned, with v1 being the current stable version. When breaking changes are introduced, a new version will be released.

​
Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. 
curl -X POST https://api.shingleai.com/v1/messages \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"to": "user@example.com", "subject": "Hello"}'

​
Required Headers

HeaderValueDescription
AuthorizationBearer <api-key>Your API key for authentication
Content-Typeapplication/jsonRequired for POST, PUT, and PATCH requests

​
Response Headers

Every API response includes these headers:
HeaderDescription
X-Request-IDUnique identifier for the request. Include this when contacting support for debugging
X-RateLimit-LimitMaximum requests allowed per minute
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp (in seconds) when the rate limit resets
Rate limits include burst allowances for temporary traffic spikes. See Rate Limits for details.

​
Response Format

All successful responses follow a consistent structure: 
{
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "subject": "Hello",
        "status": "sent",
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
    },
    "meta": {
        "requestId": "req_abc123"
    }
}
For list endpoints, the response includes pagination metadata: 
{
    "data": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "subject": "Hello",
            "status": "sent"
        },
        {
            "id": "550e8400-e29b-41d4-a716-446655440001",
            "subject": "Follow-up",
            "status": "draft"
        }
    ],
    "meta": {
        "pagination": {
            "limit": 10,
            "offset": 0,
            "total": 42,
            "hasMore": true
        }
    }
}

​
Pagination

List endpoints support pagination using limit and offset query parameters:
ParameterDefaultMaxDescription
limit10100Number of items to return
offset0-Number of items to skip
curl "https://api.shingleai.com/v1/contacts?limit=20&offset=40" \
  -H "Authorization: Bearer sk_live_abc123..."

​
SDKs

Official SDKs for TypeScript and Python are coming soon. In the meantime, you can use the REST API directly with any HTTP client.

​
OpenAPI Specification

The ShingleAI API is documented using OpenAPI 3.1. You can access the specification at: 
https://api.shingleai.com/v1/openapi.json
Use this to generate client libraries, import into API tools like Postman, or explore the API programmatically.

​
Next Steps

Authentication

Learn how to create and use API keys

Error Handling

Understand error responses and codes