canonical: https://jentic.com/apis/clearstream.io/clearstream-core # Clearstream API Jentic publishes the only available OpenAPI specification for Clearstream API, keeping it validated and agent-ready. Clearstream is an SMS marketing platform aimed at organisations managing subscriber lists, broadcast campaigns, and inbound keyword-driven flows. The API exposes endpoints for managing the account, subscribers, lists, scheduled and immediate messages, keyword automations, ad-hoc texts, and conversation threads. Authentication is by API key sent in the X-API-Key header. ## For AI agents Send SMS messages, manage subscribers and lists, configure keyword automations, and read conversation threads on the Clearstream SMS marketing platform. ## Scope Does not handle email delivery, voice calls, or push notifications - use for SMS subscriber management and broadcast messaging only. ## Capabilities - Send or schedule an SMS broadcast to a subscriber list - Manage subscriber records including create, update, and remove operations - Maintain segmented lists used as targets for messages - Send a one-off text message to a specific recipient - Read inbound and outbound conversation threads for a subscriber - List active keywords that trigger automated SMS responses ## Use cases ### Scheduled SMS Broadcast Campaign Schedule an SMS broadcast to a targeted subscriber list for delivery at a future time, for example a Sunday morning service reminder or an event announcement. The API accepts the message body, sender number, target list, and send time, then returns a record that can be retrieved later for delivery confirmation. Lists are managed as first-class resources so the same audience can be reused across campaigns. Example prompt: Call POST /messages with the list ID, message body, and send_at timestamp to schedule a broadcast SMS to all subscribers on that list. ### Subscriber Lifecycle Management Manage SMS subscribers across signup, list assignment, profile updates, and opt-out. New subscribers are created via POST /subscribers, moved between lists, updated when their phone number or attributes change, and removed when they opt out. This is the backbone of any compliant SMS programme that needs a clean record of who consented to what. Example prompt: On a webhook unsubscribe event, call DELETE `/subscribers/{id}` with the subscriber ID to remove them from future broadcasts. ### Two-Way SMS Conversations Read inbound and outbound message threads to follow up on conversations subscribers initiate by replying to broadcasts or texting in keywords. The threads endpoint returns the full message history for review, and POST /texts sends a one-off reply outside of a scheduled campaign. This supports lightweight customer support and pastoral follow-up flows on top of the broadcast model. Example prompt: Call GET /threads to find unread conversations, then send a personal reply via POST /texts with the recipient number and body. ### AI Agent SMS Outreach Allow an AI agent to run SMS outreach end-to-end through Jentic: sync subscribers from a CRM, create or update lists, schedule a broadcast, and check the resulting threads for replies. The agent searches Jentic by intent rather than browsing Clearstream docs, and the API key remains in your Jentic One instance throughout. Example prompt: Search Jentic for 'send SMS to a list', execute POST /messages to schedule the broadcast, then poll GET /threads for replies and feed them back into the CRM as activities. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/messages` | Send or schedule a broadcast SMS | | POST | `/texts` | Send a one-off text message | | GET | `/subscribers` | List all subscribers | | POST | `/subscribers` | Create a subscriber | | GET | `/lists` | List all subscriber lists | | POST | `/lists` | Create a new list | | GET | `/threads` | Read conversation threads | ## Key resources - **Subscribers** — Manage subscriber records and contact details - **Lists** — Maintain audience lists for broadcast targeting - **Messages** — Schedule and send broadcast SMS to lists - **Texts** — Send one-off SMS to individual recipients - **Threads** — Read inbound and outbound conversation history - **Keywords** — Inbound keyword automations - **Account** — View and update account settings ## Why Jentic - **Setup:** Wiring this Clearstream API by hand means sending your key in the API-key request header on every call to api.getclearstream.com/v1 across its message, subscriber, and list operations. Through Jentic you install once, import Clearstream from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** You choose which Clearstream operations the agent may call, so you can limit it to the operations it needs, such as reading subscribers or listing threads, and leave message sending out of the allowed set unless you add it. - **Credential handling:** Your Clearstream API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'send a message' or 'list subscribers in Clearstream', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Twilio API** — General-purpose SMS, voice, and messaging platform with global carrier coverage. - **Clickatell Platform API** — Unified SMS and WhatsApp messaging platform for transactional sends. - **Plivo API** — Programmable SMS and voice with a developer-focused pricing model. - **MessageBird API** — Multichannel messaging across SMS, WhatsApp, and voice. ## FAQ ### Why is there no official OpenAPI spec for Clearstream API? Clearstream does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Clearstream API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Clearstream API use? Clearstream uses API key authentication. The key is passed in the X-API-Key header on every request. When called via Jentic, the key is stored encrypted in your Jentic One instance and never enters the agent's context window. ### Can I schedule an SMS broadcast with the Clearstream API? Yes. POST /messages accepts a list ID, a message body, and a send time. The platform queues the broadcast and delivers it at the scheduled moment. Use GET /messages to retrieve the resulting message records. ### How do I send a one-off text message versus a broadcast? POST /texts sends a single SMS to one recipient and is intended for replies and ad-hoc messages. POST /messages schedules a broadcast to a list and is intended for campaigns. Both produce records that can be read back via the corresponding GET endpoints. ### What are the rate limits for the Clearstream API? The OpenAPI spec does not declare rate limits explicitly. Practical throughput is governed by your Clearstream plan and SMS carrier delivery rates. For high-volume sends, schedule broadcasts via POST /messages so the platform handles delivery queuing. ### How do I send an SMS broadcast through Jentic? Search Jentic for 'send SMS to a subscriber list' and Jentic returns the POST /messages operation with its input schema. Run pip install jentic, then await client.search, await client.load, await client.execute to schedule the broadcast. ### Can I limit what my agent is allowed to do with the Clearstream API? Yes. Because you run Jentic One yourself, your own rules decide which Clearstream operations the agent may call. You can allow read-only actions such as GET /subscribers or GET /threads while leaving broadcast sending via POST /messages and one-off texts via POST /texts out of the permitted set unless you explicitly add them. The API key is stored encrypted in your own instance and injected only for the operations you approve.