canonical: https://jentic.com/apis/clearstream.io/clearstream-api

# Clearstream API

Jentic publishes the only available OpenAPI specification for Clearstream API, keeping it validated and agent-ready. Clearstream is a church text messaging platform that lets organisations communicate with their communities via SMS and MMS. This expanded API surface covers subscriber and list management, tag-based segmentation, keyword automation, multi-step workflows, MMS media uploads, message and thread access, and account-level statistics. Authentication is by API key sent in the X-API-Key header.

## For AI agents

Manage SMS and MMS subscribers, lists, tags, keywords, workflows, media, and account statistics on the Clearstream messaging platform via 48 endpoints.

## Scope

Does not handle email delivery, voice calls, or push notifications - use for SMS and MMS subscriber management, segmentation, and broadcast messaging only.

## Capabilities

- Manage subscribers individually or in batches and segment them by tag
- Maintain lists and add or remove subscribers from list memberships
- Send and schedule SMS or MMS broadcasts to lists
- Configure inbound keywords that trigger automated SMS responses
- Build multi-step workflows that respond to subscriber actions over time
- Upload MMS media assets and reuse them across messages
- Read account-level statistics on sends, deliveries, and engagement

## Use cases

### Tag-Based SMS Segmentation

Segment subscribers using tags so that broadcasts can target a specific subset of the audience without maintaining duplicate lists. Tags are first-class resources with bulk apply endpoints, so an agent can apply a tag to many subscribers at once and then send a broadcast targeted at that tag. Useful for event reminders, age-group ministries, or volunteer cohorts.

Example prompt: Call POST `/tags/{id}/subscribers` with the list of subscriber numbers to apply a tag, then send a broadcast targeted at that tag via POST /messages.

### Keyword-Driven Inbound Automation

Configure inbound keywords so that subscribers texting a defined word in trigger an automatic SMS response, opt them into a list, or kick off a workflow. The keywords endpoint manages the catalog of active keywords and the workflows endpoint runs the multi-step automation behind them. This supports event signup flows, prayer request capture, and giving prompts.

Example prompt: Call POST /keywords with the keyword text and trigger configuration, then verify it via GET `/keywords/{id}.`

### MMS Media Broadcast

Send picture messages by first uploading the image to Clearstream's media endpoint and then referencing the resulting media ID in a message broadcast. This works for event posters, sermon graphics, or daily encouragement images. Media assets persist on the account so the same image can be reused across multiple sends.

Example prompt: Upload an image via the media endpoint, then call POST /messages with the returned media ID and the target list to broadcast the picture message.

### Bulk Subscriber Import from a CRM

Import or update large numbers of subscribers at once using the batch subscriber endpoint, avoiding rate-limit problems associated with one-at-a-time creation. Existing subscribers are upserted and new ones created in a single call. This makes it practical to keep Clearstream subscribers in sync with a church management system or CRM.

Example prompt: Call POST `/subscribers/batch` with an array of subscriber records exported from the CRM to upsert all of them in one request.

### AI Agent SMS Engagement Pipeline

Allow an AI agent to run end-to-end SMS engagement: pull statistics, segment by tag, schedule a broadcast, and read back inbound threads, all through Jentic. The agent searches Jentic by intent and Clearstream credentials stay in your Jentic One instance throughout the pipeline.

Example prompt: Search Jentic for 'segment subscribers by tag and send broadcast', then chain the tag-apply, message-create, and statistics operations to send and report on the broadcast.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/messages` | Send or schedule a broadcast SMS or MMS |
| POST | `/subscribers/batch` | Bulk create or update subscribers |
| POST | `/lists` | Create a new list |
| POST | `/lists/{id}/subscribers` | Add a subscriber to a list |
| POST | `/tags` | Create a segmentation tag |
| POST | `/tags/{id}/subscribers` | Apply a tag to subscribers in bulk |
| POST | `/keywords` | Create an inbound keyword automation |
| GET | `/account/headers` | List recently used message headers |

## Key resources

- **Subscribers** — Subscriber records with batch upsert
- **Lists** — Audience lists and list-subscriber memberships
- **Tags** — Tag-based segmentation across subscribers
- **Keywords** — Inbound keyword automations
- **Workflows** — Multi-step automated SMS workflows
- **Messages** — Outbound SMS and MMS broadcasts
- **Media** — MMS media asset uploads
- **Statistics** — Account-level send and engagement statistics

## 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 and mapping calls across its messaging and list operations yourself. Through Jentic you install once, import Clearstream from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Clearstream puts the list id and tag id in the URL path (`/lists/{id}/subscribers`), so a rule can pin your agent to one list: it can add subscribers to that list and nothing else. You choose the operations it may call, so sending messages is not included 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 text message' or 'add a subscriber to a list 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 and MMS platform with global carrier reach.
- **Clickatell Platform API** — SMS and WhatsApp messaging through a unified platform.
- **Plivo API** — Developer-focused SMS and voice platform with low per-message pricing.
- **Sinch API** — Carrier-grade messaging across SMS, MMS, and rich messaging formats.

## 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 via the X-API-Key header. The key is generated in the Clearstream account settings. Through Jentic, the key is stored encrypted in your Jentic One instance and is never visible to the agent's prompt context.

### Can I send MMS picture messages with the Clearstream API?

Yes. Upload the image through the media endpoint to obtain a media ID, then reference that ID in POST /messages alongside the target list. Clearstream delivers the image as an MMS to subscribers on supported carriers.

### How do I bulk import subscribers from another system?

Use POST `/subscribers/batch` with an array of subscriber records. The endpoint upserts existing subscribers by phone number and creates new ones in the same call, which avoids hitting rate limits when syncing thousands of records.

### What are the rate limits for the Clearstream API?

Rate limits are not declared in the public OpenAPI spec. For large operations such as subscriber sync use POST `/subscribers/batch` and POST `/tags/{id}/subscribers` rather than per-record calls so the server handles batching efficiently.

### How do I segment and send through Jentic?

Search Jentic for 'apply a tag to subscribers and send broadcast'. Jentic returns the POST `/tags/{id}/subscribers` and POST /messages operations with their input schemas. Run pip install jentic, then await client.search, await client.load, await client.execute to chain the operations.

### 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 and credentials the agent may use. Clearstream puts the list id and tag id in the URL path, such as `/lists/{id}/subscribers`, so a rule can pin the agent to a single list and let it only add subscribers there. You choose the operations it can call, so broadcast sends via POST /messages stay out of reach unless you explicitly allow them.