Build on the AthenaText platform
A REST API over HTTPS with JSON everywhere. Push leads, read conversations, send messages, and subscribe to events. Versioned, scoped, and sandboxed from day one.
Authentication
All requests authenticate with a Bearer token. Create API keys in your dashboard under Settings → API keys. Each key is scoped to a workspace and can be restricted to specific resources (read-only, messaging, leads, or full access).
# Send a message with curl curl https://api.athenatext.com/v1/messages \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{ "to": "+15551234567", "body": "Hey — this is Athena." }'
Every request returns standard HTTP status codes. Errors come back as JSON with a code, message, and optional param.
Quickstart
The fastest way to get a conversation running: create a lead, then send the opening message. The AI takes over from there.
import Athena from 'athenatext'; const client = new Athena({ apiKey: process.env.ATHENA_KEY }); const lead = await client.leads.create({ phone: '+15551234567', source: 'website', attributes: { listing: 'elm-st', budget: 450000 } }); await client.messages.send({ leadId: lead.id, body: 'Hey! Saw you were interested in the Elm St listing — want to see it this week?' });
curl https://api.athenatext.com/v1/leads \ -H "Authorization: Bearer sk_live_…" \ -H "Content-Type: application/json" \ -d '{ "phone": "+15551234567", "source": "website", "attributes": { "listing": "elm-st", "budget": 450000 } }'
from athenatext import Athena client = Athena(api_key=os.environ['ATHENA_KEY']) lead = client.leads.create( phone='+15551234567', source='website', attributes={'listing': 'elm-st', 'budget': 450000} ) client.messages.send( lead_id=lead.id, body='Hey! Saw you were interested in the Elm St listing — want to see it this week?' )
Conversations
A conversation is the full SMS thread with a single lead, including qualification state, message history, and handoff status. Conversations are created automatically when a lead first engages.
Retrieve a conversation by ID, including qualification state and the full message history.
{
"id": "conv_7f3a91b2",
"lead_id": "lead_4c88e100",
"status": "qualified",
"qualification": {
"score": 0.87,
"signals": ["budget", "timeline", "decision_maker"]
},
"messages": 8,
"created_at": "2026-04-14T16:22:01Z",
"handoff_at": "2026-04-14T16:29:48Z"
}
List conversations with filters for status, campaign_id, or date range. Cursor-based pagination.
Leads
Leads are the people you're trying to reach. Push them in from forms, CRMs, ad platforms, or CSV uploads.
Create a lead. If a lead with the same phone already exists in this workspace, the new attributes are merged into the existing record.
{
"id": "lead_4c88e100",
"phone": "+15551234567",
"source": "website",
"status": "new",
"attributes": { "listing": "elm-st", "budget": 450000 },
"created_at": "2026-04-14T16:21:58Z"
}
Messaging
Send outbound messages through your registered AthenaText numbers. Inbound messages are delivered via webhooks; see the Webhooks section.
Send an SMS. AthenaText respects opt-outs, quiet hours, and per-campaign frequency caps automatically.
{
"id": "msg_90de2431",
"lead_id": "lead_4c88e100",
"direction": "outbound",
"status": "delivered",
"body": "Hey! Saw you were interested in the Elm St listing — want to see it this week?",
"sent_at": "2026-04-14T16:22:03Z"
}
Webhooks
Subscribe to platform events. AthenaText POSTs a JSON payload to any HTTPS URL you register, with HMAC signatures for verification and automatic retry on non-2xx responses.
Register a new webhook endpoint subscribed to one or more event types.