# iris iris is the ai messenger. it runs multi-channel outreach campaigns: create campaigns with AI-generated personalized content, discover leads on Instagram and TikTok, manage contacts, automate email and social messaging, and track conversations across email, Instagram, and Twitter. website: https://www.iris-ai.dev docs: https://www.iris-ai.dev/docs llms-full.txt: https://api.iris-ai.dev/llms-full.txt openapi: https://api.iris-ai.dev/openapi.json ## what iris is - an AI-powered outreach automation platform for email, Instagram DMs, and Twitter DMs - a lead discovery engine that finds contacts on Instagram and TikTok (plus public business listings for venue campaigns) - a campaign management system with objective-driven workflows (venue booking, product promotion, custom outreach) - a unified inbox that aggregates conversations across all channels with real-time updates - a developer platform with a REST API (80+ endpoints), MCP server, webhooks, and agent payment protocols (x402, MPP) ## what iris is not - not a general-purpose CRM (focused on outreach automation, not deal pipelines) - not an email client or ESP (uses SendGrid for delivery) - not a social media scheduler (sends direct messages, not public posts) ## key features - multi-channel outreach (email, Instagram, Twitter) - AI content generation and personalization via Claude - automated contact discovery on Instagram and TikTok - objective-driven campaigns (venue booking, product promotion, custom) - AI-analyzed target profiles for product promotion campaigns - message approval workflow with AI feedback - unified inbox across all channels with real-time updates - responder: answers inbound Instagram DMs for you, shares your booking link, hands the conversation to you when a person is needed, and can DM people who comment a keyword (off by default) - real-time analytics and engagement tracking - developer REST API with scoped API keys and webhooks - MCP server for AI agent integration (99 tools; npm package or hosted endpoint) - agent payments (x402 crypto and MPP Stripe) for autonomous agent workflows; discoverable on agentic.market and the CDP x402 bazaar ## discoverable on - agentic.market: https://agentic.market/?service=www-iris-ai-dev - CDP x402 bazaar: https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources (resource: https://api.iris-ai.dev/campaigns) - /.well-known/x402: https://api.iris-ai.dev/.well-known/x402 ## quick start 1. create a campaign - choose objective type (venue booking, product promotion, or custom outreach) 2. add target profiles - define who you want to reach (AI generates profiles for product promotion) 3. discover contacts - search Instagram and TikTok, or import a CSV 4. review AI drafts - iris generates personalized messages for each contact using Claude 5. activate - approve drafts and iris sends them across your chosen channels note for agents: every API response carries an X-Iris-Notice header with a one-line summary of the latest contract change - surface it when it changes. deprecated operations additionally carry Deprecation and Sunset headers. ## changelog machine-readable history at `GET /changelog` (public, no key). recent releases: - 2.28.3 (2026-11-12, fix): GET /analytics/response-time starts the clock at the first message you sent as outreach. the responder's automatic replies, its comment-trigger DMs, and messages typed in the Instagram app no longer start it, which matches what GET /recap counts as sent. the analytics page in the app counts sent messages the same way. the response shape is unchanged. - 2.28.2 (2026-11-11, fix): GET /analytics/performance places a message that was sent on the day it was sent. it used to place every message on the day its row was created, which for a sent message is the day the draft was written, often days earlier. a message with no send time (a draft, or one queued or failed) is still counted on the day it was created. the response shape is unchanged. - 2.28.1 (2026-11-11, fix): GET /analytics/response-time measures from when the first message was sent to the first reply after it. it used to start at the first message row's creation, which is when the draft was written (often days before it was sent) and included drafts that were never sent, so response times read too long. an email whose headers mark it as an automatic reply (an out-of-office notice) is no longer a reply here, does not mark the contact as responded, and does not queue a reply draft. the response shape is unchanged. - 2.28.0 (2026-11-11, feature): GET /recap returns your last 30 days of outreach as counts: messages sent, conversations (one contact in one campaign), how many wrote back, the reply rate, and messages per channel. the responder's automatic replies, comment-trigger DMs, and messages typed in the Instagram app are left out. a message is dated by when it was sent, so a draft approved weeks after it was written counts in the month it went out (messages sent before this release carry the send time only where one was recorded); an email received from this release on whose headers mark it as an automatic reply, such as an out-of-office notice, is not a reply. the /recap page in the app shows the same numbers. read-only: a public share link is created in the app. @jclvsh/iris 0.25.0 adds the get_recap tool (npm package only) and the iris recap command. - 2.27.0 (2026-11-11, feature): GET /affiliate returns your affiliate program status (none, pending, approved, or rejected), your code and link, how many people signed up through it, your commission totals in US cents (in the 30-day hold, payable, paid out), and the program terms. read-only: apply in the app at settings > affiliate; each application is reviewed and payouts are sent by hand. @jclvsh/iris 0.24.0 adds the get_affiliate tool (npm package only) and the iris affiliate command. - 2.26.0 (2026-11-09, feature): the hosted MCP endpoint (https://api.iris-ai.dev/mcp) answers initialize and tools/list without a key, so an MCP client or a directory can read the server info and the tool list before signing up. calling a tool still needs Authorization: Bearer with an API key, and the key's scopes apply as before. keyless requests are rate limited per IP; any other keyless request gets the same 401. - 2.25.1 (2026-10-24, fix): POST /campaigns/chat (the SSE endpoint) answers its pre-stream errors with the standard envelope, { success: false, error: { code, message } }, like every other endpoint: a bad body is SERVER_VALIDATION_FAILED (400), a finalized chat or a turn still in flight is SERVER_CONFLICT (409), and a setup failure is SERVER_INTERNAL_ERROR (500). the bodies used to be { error: "" }, which a client decoding the envelope could not read (the iOS app showed "request failed (409)" when a reply was still streaming). - 2.25.0 (2026-10-14, feature): the MCP server is now also served over HTTPS at https://api.iris-ai.dev/mcp: MCP streamable HTTP, POST only, Authorization: Bearer is_live_... (the key's scopes apply). it serves a subset of the npm package's tools, each annotated read, write, or sensitive; credits, API key, and webhook tools stay npm-only. the class of every hosted tool is listed at https://www.iris-ai.dev/docs#mcp-hosted. @jclvsh/iris 0.23.0: create_campaign sends a content-derived Idempotency-Key, so a retry after a timeout returns the campaign already created instead of creating a second one. ## channels ### email personalized outbound and reply tracking from your verified sender email. iris drafts a one-to-one email for each contact, sends from your verified sender email, and routes every reply back into a unified inbox alongside Instagram and Twitter conversations. **features:** - AI-drafted per contact: every email starts from the contact's profile and the campaign brief. no merge tokens, no template blast. - reply, open, and click tracking: iris records delivery, opens, clicks, replies, bounces, and unsubscribes so you can see who engaged and who didn't. - inbound reply threading: replies attach to the originating conversation automatically, so the inbox stays threaded across long exchanges. - approval workflow: every drafted message lands in a review queue. approve as-is, edit inline, or regenerate before anything leaves your inbox. - unsubscribe-compliant: a per-contact unsubscribe link is embedded in every send. one click stops all future outreach automatically. **tips:** - keep subject lines under 50 characters: short subjects survive mobile preview clipping - personalize beyond the name field. referencing recent activity or specific work outperforms generic openers - space out sends rather than queueing them all at once. randomized delays between messages keep the cadence from looking automated - cap follow-ups so you don't burn the relationship. two well-spaced touches beat five rapid-fire ones ### Instagram DM outreach with reply threading and conservative pacing. iris connects to your Instagram account and sends DMs that match the platform's tone: short, conversational, lowercase. delivery and read receipts come back automatically, and replies land in the same inbox as your email and Twitter conversations. **features:** - AI-drafted DMs in Instagram voice: the same campaign brief gets a different treatment for Instagram: shorter, more conversational, no formal openers. - delivery and read receipts: iris flags when a DM is delivered and seen, so you know if a quiet thread was ignored or just unread. - conservative pacing: sends are paced well below platform thresholds and spread across the day to keep your account safe. - reply threading by handle: inbound DMs match the contact by Instagram handle and append to the existing conversation rather than starting a new thread. - automatic replies (optional): turn on the responder and iris answers inbound DMs for you, shares your booking link, and hands the conversation to you when a person is needed. off by default. replies go only to people who wrote first, within 24 hours of their last message. - secure account connection: connection tokens are encrypted at rest and refreshed automatically. revoke access from your Instagram settings at any time. **tips:** - keep the first DM short. long openers read as automated - open with a specific reference to recent posts rather than a generic compliment - don't send to accounts that have never followed you back if you want to avoid the message-request folder - give 24+ hours between follow-ups. same-day reminders look spammy on Instagram ### Twitter DMs to founders, creators, and prospects with full conversation history. iris uses your Twitter account to send direct messages with full conversation context. inbound DMs get matched to the campaign contact and surface in the same inbox as your other channels. **features:** - DM-first outreach: iris reaches out via DM rather than public reply, keeping the conversation private and out of the algorithmic feed. - longer messages when context calls for it: Twitter DMs aren't capped at 280 characters. iris uses more room when needed but keeps drafts tight by default. - near-real-time reply ingestion: inbound DMs trigger updates in your inbox quickly, so the back-and-forth feels native to Twitter. - automatic session refresh: iris keeps your connection alive in the background, so you don't get logged out mid-campaign. - rate-limit aware: sends are paced conservatively and respect platform limits to keep your account in good standing. **tips:** - lead with the value, not the ask. Twitter DMs that open with 'quick question' get muted - reference a specific tweet to prove you actually read their feed - keep DMs short even when the platform allows longer. short messages get replies - the message-request inbox catches DMs from accounts you don't follow. start a real conversation before pitching ## how-to guides ### bring your own discovery (agent + tool imports) pipe creators or leads found by ANY external tool - content-analysis engines like Lightreel, scrapers, spreadsheets, your own agent - into iris as the outreach system of record. difficulty: intermediate | estimated time: 15 minutes **steps:** 1. **import your roster in one call** - POST /contacts/bulk with up to 500 contacts. email is optional - handle-only creators are first-class: set instagram_handle, twitter_handle, or tiktok_handle per contact. pass campaign_id at the top level to attach every import to a campaign, or per-contact campaign_ids for mixed targeting. set source to your tool's name (e.g. 'lightreel', 'api') for per-source attribution. tip: imports are idempotent: duplicates merge by email or social handle (case-insensitive, @ stripped), including within one request - safe to retry. 2. **store your tool's intel on the contact** - put per-contact research (content niche, standout posts, why they fit) in enrichment_data (up to 50KB JSON) and tags. /ai/generate reads both automatically when drafting - your tool's judgment personalizes every message without prompt-smuggling. 3. **verify what landed** - GET /contacts/:id/handles echoes the saved social handles; GET /usage shows contact-slot headroom before your next batch. 4. **draft and deliver** - activate the campaign (or add contacts to an active one) and iris drafts per contact - format:'dm' produces platform-native DMs. email/instagram/twitter deliver via the API; tiktok drafts use the manual flow: copy, send on-platform, then POST /messages/:id/mark-sent so the CRM records it. tip: record inbound replies with POST /conversations/:id/messages (direction 'inbound') to keep the thread complete. ### getting started with iris create an account, verify a sender email, and run your first campaign in under ten minutes. difficulty: beginner | estimated time: 10 minutes **steps:** 1. **create your account** - sign up at iris-ai.dev with email or Google. the free tier includes two campaigns per month so you can run real outreach end-to-end before deciding on a plan. 2. **verify a sender email** - if you plan to send email, head to settings → channels and add the address you want emails to come from (e.g. you@yourcompany.com). SendGrid sends a verification link to that inbox; click it to confirm ownership. follow the verify-sender-email guide for a non-technical walkthrough. tip: you can skip this step if you're only running social DM campaigns. 3. **connect a social account (optional)** - connect Instagram or Twitter from settings → connected accounts to enable DM outreach. iris uses the same account you sign in with on each platform. 4. **create your first campaign** - hit 'new campaign' and pick an objective: book DJ gigs, host events, promote a product, or custom outreach. fill in the campaign brief - iris uses it to generate target profiles and write drafts. 5. **run discovery and review drafts** - iris finds matching contacts, scores them by fit, and drafts a personalized message for each. open the review queue, edit anything that doesn't sound like you, approve, and send. tip: you don't have to send every draft. select the ones you want; the rest stay in the queue or get discarded. ### build your first campaign a step-by-step walkthrough of the campaign wizard from objective to first reply. difficulty: beginner | estimated time: 10 minutes **steps:** 1. **pick an objective** - the wizard's first screen asks what you're trying to do. pick one of: book DJ gigs, host events, promote a product, or custom outreach. the choice changes which discovery sources iris searches, what tone the drafts take, and which channels are recommended. 2. **fill in the campaign brief** - the second screen depends on the objective. for product promotion, you paste the product URL or write a description and iris analyzes it to generate target profiles. for venue objectives, you pick the city and venue type. you can adjust everything before discovery runs. 3. **run discovery** - iris searches Instagram and TikTok (plus public business listings for venue campaigns) for contacts matching the target profile. each result gets enriched with a name, role, niche, social handles, an email if one's listed publicly, and a fit score from 0-100. tip: filter by fit score or hand-select rows. iris only sends to contacts you mark as 'in the campaign'. 4. **configure outreach settings** - choose which channels to use (email + Instagram, Twitter only, etc.), how many follow-ups to send, and how long to wait between them. defaults are conservative on purpose. 5. **review the campaign and activate** - the review screen shows everything: contact count, channel mix, expected message volume, and your usage against plan limits. hit activate and iris drafts a message for every contact in the background. 6. **approve drafts in the review queue** - once drafts are ready (usually a few minutes for small campaigns), open the review queue. read each draft, edit anything that's off, approve to send, or regenerate to get a different angle. 7. **track replies in the inbox** - approved messages send with humanized pacing. replies land in the inbox within seconds for email, slightly longer for social DMs. iris drafts the next message; you approve. ### verify a sender email verify the address you want emails to come from so iris can send on your behalf. difficulty: beginner | estimated time: 2 minutes **steps:** 1. **open settings → channels** - scroll to the 'sender email' card. enter the address you want emails to come from (e.g. you@yourcompany.com) and the display name recipients will see. tip: use a custom-domain address rather than gmail, yahoo, or outlook. free providers fail DMARC checks and degrade deliverability. 2. **click the verification link in your inbox** - SendGrid emails the address you entered with a verification link. click it once to confirm you own the address. if the address is already verified at the SendGrid account level, iris will skip the email step and mark it verified immediately. 3. **confirm the badge flips to verified** - return to settings → channels. the sender card should show a green 'verified' badge. if it still says 'pending', press 'check status' or click the email link again. 4. **you're ready to send** - every email iris sends will now use your verified address as the from-name and reply-to. activate a campaign and drafts will populate and send from your address as soon as you approve them. ### connect your Instagram account enable Instagram DM outreach by connecting your account from settings. difficulty: beginner | estimated time: 5 minutes **steps:** 1. **open settings → connected accounts** - the connected accounts page lists every channel iris supports and the connection state for each. 2. **click connect Instagram** - iris redirects you to Instagram to sign in. you're signing in with your own Instagram account - iris doesn't ask for your password and never sees it. 3. **approve the messaging permission** - Instagram shows you what permission iris is requesting (the ability to send and receive DMs on your behalf) and asks you to approve. you can revoke this at any time from your Instagram settings. tip: if you have multiple Instagram accounts, make sure you're signed in to the right one before clicking connect. 4. **confirm the connection** - iris redirects you back. the connected accounts page should now show Instagram as 'connected' with your handle. 5. **send a test DM** - before running a campaign, send a DM to a friend's account or your own alt to confirm it works. you'll see the test message arrive on Instagram and the read receipt come back into the iris inbox. ### connect your Twitter account enable Twitter DM outreach by connecting your account from settings. difficulty: beginner | estimated time: 5 minutes **steps:** 1. **open settings → connected accounts** - the same page that handles Instagram - find the Twitter row and click connect. 2. **sign in to Twitter** - iris redirects to Twitter. sign in with the account you want iris to send DMs from. iris doesn't see your Twitter password. 3. **approve the messaging permission** - Twitter shows you what iris is asking for: the ability to send and receive DMs on your account. approve to continue. 4. **confirm the connection** - after redirecting back, the connected accounts page shows Twitter as 'connected' with your handle. 5. **send a test DM** - send a test DM to a second account you control. confirm the send goes through, the message appears in the recipient's inbox, and any reply lands back in the iris inbox. tip: Twitter has a 'message request' folder for DMs from accounts you don't follow. test against an account that follows yours so you don't fight the message-request UX. ### run a product promotion campaign let iris analyze your product, generate target profiles, and discover the right contacts to pitch. difficulty: intermediate | estimated time: 15 minutes **steps:** 1. **create a campaign and pick 'promote a product'** - this objective triggers the AI product analyzer. you don't need to know your target audience up front - iris will propose one based on the product itself. 2. **paste your product URL or write a description** - the more iris can read, the better the target profiles will be. a public product page works best; a one-paragraph description works fine if the product isn't public yet. 3. **review the generated target profiles** - iris generates 2-4 target profiles, each with a name, profile type (creator, B2B professional, agency, etc.), job titles, industries, pain points, and recommended channels. read them critically - they're starting points, not final. tip: if a profile feels off, edit the keywords or job titles directly. small changes make a big difference at discovery time. 4. **select the profiles to discover against** - you can run discovery against one profile at a time or all of them. start with the highest-fit profile and add more if the first batch is too small. 5. **review and refine the contact list** - discovery returns enriched contacts scored by fit. filter by score, hand-deselect anyone who doesn't fit, and confirm the channels each contact is reachable on. 6. **review drafts and send** - iris drafts a message per contact that leads with how the product fits the recipient's work, not with a feature dump. approve in the review queue and send. ### use the review queue the four things you can do with a drafted message: approve, edit, regenerate, or skip. difficulty: beginner | estimated time: 5 minutes **steps:** 1. **open the review queue** - every active campaign has a queue of drafts waiting for approval. find it in the campaign detail page or in the global 'pending review' tab. 2. **approve as-is** - if a draft reads well, hit approve. iris schedules the send with humanized pacing and updates the conversation status. tip: you can bulk-approve - select multiple drafts and hit approve all. iris paces the actual sends regardless of how fast you approve. 3. **edit inline** - if a draft is mostly right but needs a tweak, click edit. you can change the subject, the body, or both. iris remembers your edits when drafting future messages in the same campaign. 4. **regenerate** - if the angle is off, hit regenerate. iris re-drafts from scratch with the same brief but a different opener, structure, or angle. you can regenerate up to your plan's per-campaign limit. 5. **skip** - if a contact slipped through discovery and they shouldn't be in the campaign, hit skip. they stay on the contact list but no message ever goes out. ### call iris from an AI agent run iris campaigns programmatically using x402 USDC payments or MPP credit packs. difficulty: advanced | estimated time: 20 minutes **steps:** 1. **decide on a payment rail** - x402 (USDC on Base) charges per-use - good for autonomous agents that don't have a Stripe account. MPP (Stripe credits) buys credits in packs of 5 campaigns - good for agents owned by a human or company with billing already set up. 2. **send a request without a payment header** - call any paid endpoint (e.g. POST /campaigns) without payment. iris responds with HTTP 402 and a JSON body that lists every payment option, the price for each, and the URL to acquire credits. the response is the spec - your agent reads it and picks a rail. tip: this is the standard 402 discovery flow. you don't need to bake pricing into the agent at build time. 3. **settle the payment** - for x402, attach a USDC payment header on the next request. for MPP, buy credits via the URL in the 402 response, then call the endpoint with the API key from the credit purchase. 4. **run the campaign** - once payment settles, the original request runs. you'll get back a campaign ID, contact count, and a status URL. poll the status URL to track discovery and drafting progress. 5. **approve drafts via the API** - the agent endpoints expose the same draft approval flow as the UI: list pending drafts, approve, edit, regenerate, or skip. the inbox endpoints expose replies threaded by contact. ## comparisons ### iris vs Apollo.io iris focuses on quality conversations; Apollo focuses on database scale. **differentiators:** - drafted per contact, not templated: iris reads each contact's profile and writes a fresh message against your campaign brief. Apollo sequences run on liquid templates with merge tokens - faster to set up, but readers can usually tell. - multi-channel from one inbox: iris sends across email, Instagram, and Twitter, threading every reply back into one conversation per contact. Apollo is email-first; social channels are not the core flow. - discovery is fit-scored, not unbounded: iris discovery returns 20-200 enriched contacts with a fit score. Apollo returns thousands and asks you to filter. opposite philosophies. - no contact-data resale model: iris uses public data sources (public Instagram and TikTok profiles, plus public business listings). it doesn't ship with a proprietary B2B database, so there's no list-buying step before you can send. **verdict:** pick Apollo if you want a giant database to mine and you're running templated sequences at high volume. pick iris if your sales motion depends on the message being right, not just the list being big - and if you want social channels in the same inbox as email. ### iris vs Lemlist iris drafts from scratch; Lemlist personalizes a template. **differentiators:** - AI-drafted bodies, not just personalized variables: Lemlist's variables (first name, company, custom images) sit inside a static template body. iris generates the entire body per contact - structure, opener, and angle vary, not just the merge fields. - Instagram and Twitter DMs, not just email: Lemlist added LinkedIn over time but stayed primarily email. iris treats Instagram and Twitter DMs as first-class channels with their own drafting tone. - discovery + sending in one tool: Lemlist focuses on the sequencer; you bring the contact list. iris discovers contacts, enriches them, and drafts messages in one campaign flow. - approval queue by default: iris drafts then waits for your approval. Lemlist's typical flow auto-sends once the sequence is activated. **verdict:** pick Lemlist if image personalization and LinkedIn are central to your motion and you already have a list. pick iris if your channels are email + Instagram + Twitter, you want messages drafted from scratch rather than templated, and you want discovery in the same tool. ### iris vs Instantly iris is built around quality; Instantly is built around volume. **differentiators:** - one verified sender, not inbox rotation: iris sends from your verified sender email only. Instantly's model rotates across many sender mailboxes to spread volume - effective at scale, but a different deliverability strategy than iris is set up for. - AI-drafted per contact, not high-volume sequences: Instantly is optimized for sending the same sequence to many contacts. iris is optimized for drafting different messages for each contact, then sending fewer of them. - social DMs in the same inbox: Instantly is email-only. iris threads email, Instagram, and Twitter conversations together per contact. - no warm-up tooling: iris doesn't ship inbox warm-up because the volumes iris sends don't require it. if you need warm-up, you probably need a different tool. **verdict:** pick Instantly if your motion is high-volume cold email and deliverability tooling is what you came for. pick iris if you'd rather send 50 hand-edited drafts than 5,000 templated emails, and want social channels in the same inbox. ### iris vs Hunter iris combines discovery, drafting, and sending; Hunter is mostly the finder. **differentiators:** - discovery is multi-source, not domain-based: Hunter searches for emails associated with a domain. iris discovers contacts by who they are (creator, founder, venue manager) across Instagram and TikTok (plus public business listings for venues), then enriches with whatever public data exists. - drafting and sending built in: Hunter's campaigns feature is functional but minimal. iris drafts each message per contact and runs the approval-and-send queue as a first-class flow. - social DMs, not just email: Hunter is an email tool. iris reaches the same contact on email, Instagram, or Twitter depending on which channel they're most reachable on. - fit-scored, not lookup-based: Hunter is built for known-domain lookups. iris is built for 'I know who I want to reach but not who they are yet' discovery, scored by fit against a target profile. **verdict:** pick Hunter if you primarily need email addresses for a known list of domains and you'll send from somewhere else. pick iris if you want discovery + drafting + sending across email + social in one tool, with messages written per contact instead of templated. ### iris vs the DIY stack iris vs Apollo + ChatGPT + Mailchimp + your social tab. **differentiators:** - one tool, one inbox: the DIY stack lives across at least four tools. iris keeps discovery, drafting, sending, and reply tracking in one place, with conversations threaded per contact regardless of channel. - drafting wired to discovery: in the DIY stack, ChatGPT doesn't know who's on your Apollo list. iris drafts each message with the discovery context already attached - role, recent activity, fit signals - so the message reads like you actually looked at the contact. - no copy-paste between tools: every handoff in the DIY stack is a place data goes missing - export to CSV, paste into prompt, copy back, push to mailer, click around to find the reply. iris removes the handoffs. - social DMs natively: the DIY stack treats Instagram and Twitter as 'the social tab' you check between emails. iris treats them as channels with the same drafting and reply-tracking as email. **verdict:** the DIY stack gives you flexibility and low upfront cost - if you're sending small volumes and don't mind the context-switching, it works. iris is for when the handoffs become the bottleneck: you're losing track of replies, your drafts are generic because ChatGPT doesn't have the contact context, and your inbox is three browser tabs deep. ## agent payment protocols AI agents can use iris without an API key via credits purchased with x402 (crypto) or MPP (fiat). 1 credit = 1 campaign with 30 contacts and 240 messages; AI drafting and response analysis are bundled in. ### how it works 1. pay per-campaign (x402 only): read the PAYMENT-REQUIRED header from the 402, sign it, and replay `POST /campaigns` with a PAYMENT-SIGNATURE header (x402 v2; $2.25 per campaign) 2. create campaigns - each campaign costs 1 credit 3. discovery, AI drafting, and message sends run automatically inside the campaign workflow as internal QStash jobs - agents do not call /discovery/search, /ai/generate, or /channels/send directly (those endpoints require an API key) 4. check balance: `GET /agent/credits` 5. credits never expire. refunded if campaign creation fails. ### pricing x402: $2.25 per-campaign (pay inline with a PAYMENT-SIGNATURE header, x402 v2). MPP: credit packs only (5 for $12.00 via POST /agent/credits). when no credits are available, iris returns 402 with purchase info. ## responder the responder answers inbound Instagram DMs for the account owner. it is off by default and has two switches: `enabled` threads DMs from anyone into the inbox (a sender iris has never seen becomes a contact), and `auto_reply` lets iris send replies itself, with no review. - replies are written from your `instructions` and your profile background. iris states nothing about you that is not there, and says it will follow up when asked something they do not cover - set `booking_url` and iris shares that link when someone asks to talk or book, after your `qualifying_questions` (up to 5, asked one per message). iris never writes a link itself - a reply that carries a link, email address, or phone number is not sent unless that detail is your booking link or appears in your instructions or profile background. the conversation is handed to you instead (reason `unsafe_reply`) - the first automatic reply in a conversation says it is automated. set `disclosure` to change the wording - several DMs sent in a row get one reply: iris waits 20 seconds and answers the newest state of the conversation - when you reply yourself from iris, iris stops replying in that conversation until you resume it. the same holds for a reply typed in the Instagram app when `status.sees_instagram_app_replies` is true - after 8 automatic replies in one conversation (configurable, 1-30) it is handed to you - each automatic reply counts as a message against your plan, the same as a reply sent from the inbox - you get no notification for a message iris is answering; it stays unread in the inbox. you get one when iris hands a conversation to you, with the reason, and when iris does not answer a message it was going to. if a message is never processed at all, the usual new-message notification arrives within 90 minutes limits: - Instagram only: the responder does not answer email or Twitter - it cannot start a conversation. Instagram allows a message only to someone who wrote first - a reply goes out only within 24 hours of the person's last message. after that the conversation is handed to you - it cannot read a photo, a video, or a story reply. those are stored as `[attachment]` and handed to you - it cannot see whether someone booked. `booking_links_sent` counts links shared - replies share your Instagram account's send pacing with every other DM iris sends for you. when the hourly or daily pace is reached, iris waits and tries again, 3 tries in all, then hands the conversation to you - it works on at most 300 inbound messages per account per day, then pauses until you turn it back on comment triggers: - a comment trigger sends one DM to a person who comments a keyword on your Instagram post. the DM is your message as written, followed by the automated-message notice. no model writes it - Instagram allows one DM per comment, within 7 days of the comment. nothing more can be sent to that person unless they reply. when they do, their DM is handled like any other inbound DM - the keyword is matched as a whole word, case-insensitive. a trigger applies to every post, or to one post named by `media_id` (listed by GET /responder/posts) - comment triggers are not offered on every account yet. `status.comment_triggers` on GET /responder is `unavailable` until they are, `needs_permission` until the owner allows comments on the Instagram connection from the responder settings page, and `ready` after that - they send only while the responder is `enabled` and not paused, and the subscription is active. a reply written under another comment is a comment too. each DM counts as a message against your plan and shares the account's send pacing. a comment gets no DM when it arrives while that pace or the plan's message allowance is reached, when iris cannot check the allowance at that moment (recorded as usage_unavailable), or when Instagram refuses or fails the send. iris does not try the same comment again - an account holds up to 20 comment triggers the responder needs an API key and a connected Instagram account. x402 and MPP identities cannot connect Instagram, so they cannot use it, and it is not listed in x402 discovery. ## affiliate program - affiliate program (https://www.iris-ai.dev/affiliates): earn 30% of each subscription payment a person you referred makes in their first 12 months. apply in the app at settings > affiliate; each application is reviewed. your numbers are at GET /affiliate. ## FAQ Q: how do I create my first campaign? A: open the campaigns page and click 'create campaign'. choose your objective type (venue booking, product promotion, or custom outreach), fill in the details, discover contacts, and activate. iris drafts personalized messages for each contact using AI. Q: how does contact discovery work? A: iris finds leads on Instagram and TikTok, plus public business listings for venue and location-based campaigns. specify your target profile, location, and filters, and iris finds relevant contacts with emails and social handles for your campaigns. Q: how do I connect my social accounts? A: go to settings and click 'connected accounts'. you can link Twitter and Instagram via OAuth. once connected, iris can send DMs and track conversations across all channels. Q: do I need any technical skills to use iris? A: no. the entire app is point-and-click - you describe who you want to reach, iris finds them, drafts messages, and routes replies. the API and MCP server are available if you want to script things, but they're optional. if you can use Gmail you can use iris. Q: how is iris different from Apollo, Lemlist, or Instantly? A: iris drafts every message from scratch per contact instead of personalizing a shared template, treats Instagram and Twitter DMs as first-class channels alongside email, and threads every reply into one inbox per contact. see the comparison pages at /compare for side-by-side breakdowns. Q: what are objective types? A: campaigns are driven by objectives: 'book DJ gigs' and 'host events' for venue outreach, 'promote a product' for AI-analyzed product marketing with auto-generated target profiles, and 'custom outreach' for your own criteria. iris infers the right objective from your goal description in chat - you don't pick it manually. Q: how does AI message generation work? A: when you activate a campaign, iris uses Claude to draft personalized emails for each contact. it considers the contact's business, your campaign objective, and any product analysis to write relevant outreach. you review and approve drafts before they're sent. Q: can I customize email templates? A: yes. use variables like {{business_name}} and {{contact_name}} to personalize. you can also let the AI generate templates based on your campaign objective and target audience. Q: how many contacts can I target per campaign? A: campaign size scales with your plan. starter campaigns hold 30 contacts, pro hold 40, premium hold 60. each contact gets about 8 message slots (initial outreach plus follow-ups across email, Instagram, and Twitter), which is why a 30-contact campaign carries 240 messages. Q: can I pause or cancel a campaign mid-send? A: yes. open the campaign, hit pause, and iris stops queueing new drafts immediately. anything already in the review queue stays there - you can approve, edit, or discard. resume the campaign anytime; it picks up where it left off. Q: how do I duplicate a successful campaign? A: from the campaign detail page, click 'duplicate'. iris copies the objective, brand voice, target profile, and channel settings into a fresh campaign with no contacts attached, so you can run discovery against a new region or audience without rebuilding the brief. Q: how do I import existing contacts? A: go to contacts and click 'import'. upload a CSV with columns for business name, email, phone, website, Instagram, and address. download the template first to get the correct format. Q: what data sources does discovery use? A: iris discovers contacts on Instagram and TikTok, plus public business listings for venue and location-based campaigns. social sources give handles and follower counts; business listings give addresses and phone numbers. Q: how does fit scoring work? A: every discovered contact gets a 0-100 fit score against your campaign brief. iris weighs the match between the contact's profile (business type, location, social signals, listed services) and your objective + target profile. you can sort or filter the discovery results by fit score before adding contacts to a campaign. Q: can I exclude contacts I've already messaged? A: yes. iris dedupes against your contact history so a contact already reached in a prior campaign isn't silently re-added to a new one. you can also unselect contacts in the discovery review step before activating a campaign. Q: is the contact data legal to use? A: iris pulls from public sources (public Instagram and TikTok profiles, public business listings, company websites). every outreach email includes a per-contact unsubscribe link as required by CAN-SPAM, and one click flips the contact's status to opted_out across email, Instagram, and Twitter so iris stops sending on every channel. for GDPR jurisdictions you remain the data controller; keep your campaign briefs compliant with local rules. Q: what channels does iris support? A: email (via SendGrid), Instagram DMs, and Twitter DMs. each channel has its own adapter for formatting, rate limits, and delivery tracking. the orchestrator picks the best channel per contact based on available handles. Q: what happens when someone replies? A: replies are tracked in the unified inbox. email replies come through SendGrid inbound webhooks, Twitter and Instagram DMs come through platform webhooks. AI can help draft responses, which you review before sending. on Instagram you can also turn on the responder, which answers for you without review - it is off unless you turn it on. Q: what is the email sending limit? A: message limits are per campaign, not global. starter: 240 messages per campaign, pro: 320, premium: 480. each campaign's cap scales with its contact size (8× contacts) to cover initial outreach plus follow-ups across email, instagram, and twitter. the number of campaigns you can create per billing period determines total capacity. Q: what is humanized pacing? A: iris staggers sends with a randomized delay between each message instead of blasting an entire campaign at once. delays are tuned per channel: email is the fastest, Instagram and Twitter DMs are slower to stay well under platform thresholds. the goal is a cadence that doesn't trip platform anti-spam. Q: do you support LinkedIn? A: not currently. iris sends across email, Instagram DMs, and Twitter DMs. LinkedIn outreach isn't supported yet because LinkedIn's API restricts third-party messaging to specific partner programs. Q: how do I tune the tone of AI drafts? A: the campaign brief drives the tone. when you describe the campaign objective and target audience, iris uses that context (alongside the contact's profile) when prompting Claude. there is no separate per-contact 'persona' field - the campaign brief is the lever. Q: what happens to bounced emails? A: iris records hard and soft bounces from SendGrid webhooks. hard bounces (invalid address) mark the contact as undeliverable so iris stops sending to that address. soft bounces (full inbox, temporary delivery failure) are recorded but don't block future sends. bounce status shows next to each contact in the conversation view. Q: what is the responder? A: the responder answers your inbound Instagram DMs for you. it has two switches, both off by default. the first threads DMs from anyone into your inbox, so a message from someone new becomes a contact. the second lets iris send replies itself, written from what you told it about your business. manage it at settings > responder. Q: does iris send replies without me reviewing them? A: only if you turn on "let iris reply for you". with it on, replies go out with no review. iris states nothing about you that is not in your responder instructions or your profile background, and says it is automated in the first reply of each conversation. a reply that carries a link, email address, or phone number you never gave iris is not sent: the conversation is handed to you instead. everything else iris drafts, including campaign outreach, still waits for your approval. Q: when does iris stop and hand the conversation to me? A: when someone asks for a person, asks something your instructions do not cover, raises a complaint or a refund, sends a photo, video, or story reply, or says stop. it also hands off after 8 automatic replies in one conversation (you can change the number), and when your plan's message allowance is used up. you get a notification with the reason each time. Q: can iris DM people who comment on my posts? A: yes, with a comment trigger, on accounts where they are available. you pick a word, and when someone comments it on your instagram post iris sends them one DM with the message you wrote, followed by the notice that it is automated. instagram allows one DM per comment, within 7 days of it, and nothing more unless the person replies. comment triggers are not on every account yet: when they are on yours, a comment triggers card shows up at settings > responder. Q: do I still get notified about new DMs? A: not for a message iris is answering: it stays unread in your inbox with no notification. you get a notification when iris hands a conversation to you, and whenever iris does not answer a message it was going to. if something keeps iris from processing a message at all, the usual new-message notification arrives within 90 minutes. Q: what happens when I reply myself? A: iris steps back. a reply you send from iris pauses automatic replies in that conversation until you resume it from the inbox. a reply typed in the Instagram app does the same once Instagram reports those to iris - the responder settings page says whether it does for your account. if it does not, pause the conversation in iris before you answer from Instagram. Q: can the responder message people first, or follow up days later? A: no. Instagram only allows a message to someone who wrote to you first, and only within 24 hours of their last message. the responder cannot start a conversation and cannot reply after that window closes. Q: can iris book calls? A: iris shares your booking link (Calendly, Cal.com, or any https link) when someone asks to talk or book, after any qualifying questions you set. the booking itself happens on your booking page, so iris cannot see whether they booked. Q: does the responder cost extra? A: no. it is part of every plan. each reply iris sends counts as a message on your plan, the same as a reply you send from the inbox. iris works on at most 300 inbound messages per account per day. Q: how does iris handle email deliverability? A: iris sends from your verified sender email through SendGrid and paces sends with randomized delays between messages. you keep ownership of your sender reputation: iris doesn't pool many users' sends through one shared address. Q: what stops my emails from landing in spam? A: the biggest factors are sender authentication (SPF/DKIM/DMARC on your domain), the content itself (spam-trigger words, excessive links, large images), and engagement signals (opens, replies, low spam complaints). iris drafts plain conversational text by default and embeds a single unsubscribe link, both of which help. set up SPF/DKIM through the verify-sender-email guide before running a real campaign. Q: what is the unsubscribe flow? A: every iris outreach email contains a per-contact unsubscribe link in the footer. one click flips the contact's status to 'opted_out' and stops every future send across all channels - email, Instagram DM, and Twitter DM - automatically. the contact stays in your database for audit purposes but is excluded from all campaign send queues. Q: what plans are available? A: iris offers starter, pro, and premium plans with monthly and yearly billing. each plan caps the number of campaigns and the size of each campaign (contacts and messages); AI drafting and response analysis are bundled in. see the pricing page for current rates. Q: is there a free plan? A: yes. the free tier includes two campaigns per month so you can run real outreach end-to-end before paying. AI drafting, discovery, and the unified inbox all work on free - the cap is on campaign volume, not on the features you can try. Q: what counts as a campaign for billing? A: a campaign is a single outreach project with one objective and one target audience. activating a campaign consumes one of your monthly campaign credits. duplicating a campaign without activating it is free; only activation counts. saved drafts and paused campaigns don't consume additional credits. Q: do unused campaigns roll over? A: no. campaign credits reset at the start of each billing period and don't accumulate. if you need more campaigns in a given month, upgrade temporarily - changes take effect immediately and prorate against the period. Q: how do I upgrade or cancel? A: go to settings > billing to manage your subscription. you can upgrade, downgrade, or cancel anytime. cancellations take effect at the end of your current billing period. Q: can I share my results? A: yes. open analytics and choose 'share a 30-day recap'. it shows your last 30 days of outreach: messages sent, conversations, how many replied, your reply rate, and messages per channel. automatic replies from the responder are left out. sharing creates a public link with those numbers only. your name, your contacts, and your messages are not shown, and anyone with the link can see it until you delete it. Q: does iris have an affiliate program? A: yes. the terms are at iris-ai.dev/affiliates. apply from settings > affiliate by picking the code for your link; we review each application before the link starts working. you earn 30% of each subscription payment a person you referred makes in their first 12 months. a referral counts when someone signs up within 30 days of first clicking your link. a commission becomes payable 30 days after the payment and is cancelled if that payment is refunded or disputed. card subscriptions on the web count; App Store purchases and pay-per-campaign agent payments don't. your own accounts don't count, and commissions are in US dollars. Q: does iris have an API? A: yes. iris has a REST API at api.iris-ai.dev with 80+ endpoints covering campaigns, contacts, conversations, messages, discovery, AI, analytics, billing, and webhooks. authenticate with API keys (is_live_...) or agent payment protocols (x402, MPP). Q: how do I get an API key? A: go to settings > API keys and click 'generate key'. choose the scopes you need (read, write, generate, send, delete, admin) and set an expiration. the raw key is only shown once, so save it securely. Q: what are x402 and MPP? A: x402 and MPP are agent payment protocols that let AI agents use the iris API without an API key. x402 agents pay per-campaign ($2.25). MPP agents buy credit packs (5 for $12.00). each campaign credit covers the starter envelope: 30 contacts and 240 messages, with AI drafting bundled in. credits never expire and are refunded if campaign creation fails. Q: is there an MCP server for AI agents? A: yes. the iris MCP server exposes campaigns, contacts, discovery, drafting, and analytics as MCP tools that Claude Code, Cursor, and other MCP clients can call directly, as an npm package or as a hosted endpoint at https://api.iris-ai.dev/mcp. installation and tool reference live at /docs in the iris app. Q: where is the full API documented? A: /docs in the iris app has the full reference - resources, endpoints, parameters, request/response schemas, error codes, code examples, and rate limits. agent-readable formats are available at /llms.txt, /llms-full.txt, and /openapi.json. the .well-known/x402 endpoint advertises pricing for x402 agents. Q: can I receive webhooks for inbound replies? A: yes. configure a webhook subscription at /api/v1/webhooks and iris pushes events for inbound messages, campaign state changes, message status updates, and discovery completions to your endpoint. each delivery is signed with HMAC so you can verify it's from iris. Q: how do I track campaign performance via API? A: the analytics endpoints provide open rates, click rates, response rates, and conversions. filter by date range and campaign. webhook subscriptions can push events to your server in real-time. Q: my campaign drafts aren't generating, what's wrong? A: drafts run through QStash as a background job after activation, so there can be a short delay. if drafts haven't appeared after 5 minutes, check (1) the campaign has at least one selected contact, (2) your AI generation usage hasn't hit the plan limit, and (3) the activity feed on the campaign page for any error messages. if the issue persists, contact support with the campaign ID. Q: a contact replied but I can't see it in the inbox A: for email, check that the verified sender's reply-to domain is configured to forward to iris's inbound webhook (the verify-sender-email guide covers this). for Instagram and Twitter DMs, the inbound webhook needs the platform's app review approval, which iris handles - if a known-good reply is missing, contact support and include the platform handle and approximate timestamp. Q: email sender verification is stuck on 'pending' A: SendGrid emails the verification link to the address you added, not to your iris account. check that mailbox (and spam folder) and click the link. if the link expired, return to settings > channels and click 'resend verification'. verification is a one-time step per sender address. Q: a connected social account is showing as disconnected A: OAuth tokens expire when the platform rotates them or you revoke iris from your platform settings. go to settings > connected accounts, click 'reconnect' on the affected platform, and complete the OAuth flow again. iris re-encrypts and stores the new token automatically. ## blog ### introducing iris - the AI messenger for outbound published: 2026-04-15 | 4 min read iris finds the right contacts, drafts a personal message for every one, and routes replies across email, Instagram, and Twitter into a single inbox. read more: https://www.iris-ai.dev/blog/introducing-iris ### why personalization beats templates - even when the template is good published: 2026-04-08 | 5 min read merge tokens fool no one. the math on why one-to-one drafts outperform variant templates, and how iris closes the gap. read more: https://www.iris-ai.dev/blog/personalization-vs-templates ### the unified inbox - email, Instagram, and Twitter in one thread published: 2026-04-01 | 4 min read why running outreach across three channels falls apart without conversation threading, and how iris keeps everything in one view. read more: https://www.iris-ai.dev/blog/unified-inbox ### how iris finds the right contacts published: 2026-03-22 | 5 min read discovery isn't a list - it's a search. how iris turns a campaign objective into target profiles, search queries, and enriched contact rows. read more: https://www.iris-ai.dev/blog/contact-discovery ### what actually makes a cold email get a reply published: 2026-03-12 | 6 min read five things that move reply rate, ranked by how much. and three things people obsess over that don't. read more: https://www.iris-ai.dev/blog/what-makes-a-cold-email-reply ### agent payments - per-campaign pricing for AI agents published: 2026-03-01 | 4 min read iris is callable as an API. AI agents pay per campaign with USDC (x402) or Stripe credits (MPP), so they only pay for what they use. read more: https://www.iris-ai.dev/blog/agent-payments ### objective-driven campaigns - what the wizard actually does published: 2026-02-20 | 5 min read book DJ gigs, host events, promote a product, or define custom outreach. each objective changes how iris discovers, drafts, and paces. read more: https://www.iris-ai.dev/blog/objective-driven-campaigns --- # API documentation ## base URL ``` https://api.iris-ai.dev ``` ## authentication all requests require a bearer token: ``` Authorization: Bearer is_live_... ``` create API keys at https://www.iris-ai.dev/settings under the API section. ## scopes API keys support scoped permissions. assign only the scopes your integration needs. | scope | description | |-------|-------------| | read | view all resources (campaigns, contacts, conversations, messages, analytics, billing) | | write | create, update, and soft-delete business data (campaigns, contacts, conversations, notifications) | | generate | costly external API calls (Claude AI generation, discovery searches) | | send | send and approve outbound messages (email, Instagram DM, Twitter DM) | | admin | manage API keys and webhooks | default scopes (if none specified, or `["*"]`): all scopes: `read`, `write`, `generate`, `send`, `admin`. UI default for new keys is `read, write, generate, send` (no `admin`). ## endpoints ### authentication verify your API key and view its metadata. #### GET /keys/me get information about the currently authenticated API key **response (200):** ```json { "success": true, "data": { "id": "uuid", "user_id": "uuid", "name": "production", "key_prefix": "is_live_a1b2c3d4", "scopes": ["*"], "last_used_at": "2024-01-15T10:30:00Z", "expires_at": null, "revoked_at": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } } ``` ### API keys programmatically manage API keys. all routes in this group (except `/keys/me`) require an API key with the `admin` scope. `/keys/me` returns metadata for the currently-authenticated key and works without any scope. #### GET /keys list all API keys for your account **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "user_id": "uuid", "name": "production", "key_prefix": "is_live_a1b2c3d4", "scopes": ["*"], "last_used_at": "2024-01-15T10:30:00Z", "expires_at": null, "revoked_at": null, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } ``` #### POST /keys create a new API key. the raw key is only returned once. **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | yes | key name (1-100 characters) | | scopes | string[] | no | permission scopes (any of: read, write, generate, send, admin). defaults to ["*"] for full access. DELETE routes gate on write (soft-deletes) - there is no delete scope | | expires_at | ISO 8601 | no | optional expiration date | **response (200):** ```json { "success": true, "data": { "id": "uuid", "user_id": "uuid", "name": "staging", "key_prefix": "is_live_e5f6g7h8", "key": "is_live_e5f6g7h8a9b0c1d2e3f4g5h6i7j8k9l0m1n2o3p4", "scopes": ["read"], "last_used_at": null, "expires_at": null, "revoked_at": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } ``` **notes:** - the raw key value is only returned on creation - store it securely #### PATCH /keys/:id rename an API key. only the display label is updated; the secret, scopes, and expiry are untouched. **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | yes | new display name (1-100 chars) | **response (200):** ```json { "success": true, "data": { "id": "uuid", "name": "renamed key", "key_prefix": "is_live_abcd", "scopes": ["read", "write"], "last_used_at": "2026-04-29T12:00:00Z", "expires_at": null, "revoked_at": null, "created_at": "2026-04-01T12:00:00Z", "updated_at": "2026-04-29T13:00:00Z" } } ``` **errors:** - 404 APIKEY_006: API key not found #### DELETE /keys/:id revoke an API key. this action is irreversible. **response:** 204 no content **errors:** - 404 APIKEY_006: API key not found #### POST /keys/:id/rotate rotate an API key: revokes the old key and creates a new one with the same name and scopes. the new raw key is returned exactly once. update stored credentials immediately. the old key stops authenticating as soon as this returns. cannot rotate the key being used for the request itself (would lock the caller out mid-rotation). **response (200):** ```json { "success": true, "data": { "id": "uuid", "name": "my integration", "key_prefix": "is_live_xyz...", "scopes": ["read", "write", "generate", "send"], "last_used_at": null, "expires_at": null, "revoked_at": null, "created_at": "2026-05-07T12:00:00Z", "updated_at": "2026-05-07T12:00:00Z", "key": "is_live_xyz...thefullnewkeyshownonceonly" } } ``` **errors:** - 404 APIKEY_006: API key not found - 422 SERVER_005: cannot rotate the API key currently being used **notes:** - the new key's `id` is different from the old `id`. update any stored references. - the underlying service makes the usage counter net-zero, so rotation never trips MAX_ACTIVE_KEYS_PER_USER even when the user is at the limit. ### campaigns create and manage outreach campaigns. #### GET /campaigns list all campaigns **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | status | string | no | filter by status (draft, active, paused, completed, deleted) | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "user_id": "uuid", "name": "Q1 outreach", "status": "active", "objective_type": "product_promotion", "product_name": "Acme Widget", "product_url": "https://acme.example.com", "product_description": null, "follow_up_enabled": true, "follow_up_max_count": 2, "follow_up_delay_days": 3, "keywords": ["coffee shop", "cafe"], "venue_types": [], "outreach_channels": ["email"], "location": "Brooklyn, NY", "radius_miles": 25, "min_budget": null, "max_budget": null, "dynamic_fields": {}, "goal_description": null, "analysis_status": "completed", "analysis_error": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } ``` #### POST /campaigns create a new campaign **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | yes | campaign name (1-200 chars) | | objective_type | string (1-100 chars) | yes | free-text 2-5 word goal summary (e.g. 'venue_host', 'promote my coffee shop'). discovery routing uses target_profile_type, not this field. | | goal_description | string | no | what the campaign should achieve (max 2000 chars) - counts as sender context | | product_name | string | no | product name (max 200 chars) - counts as sender context | | product_url | string | no | product URL for AI analysis (max 2000 chars) | | product_description | string | no | product description for AI context (max 5000 chars) - counts as sender context | | dynamic_fields | object | no | freeform context key-values. sender keys (sender_company, sender_role, goal_description, product_description, product_name, product_url, target_audience) count as sender context | | location | string | no | location to target | | location_lat | number | no | location latitude | | location_lng | number | no | location longitude | | radius_miles | integer (1-100) | no | search radius in miles (default: 10) | | keywords | string[] | no | discovery keywords | | venue_types | string[] | no | venue types for venue objectives (e.g. bar, club) | | max_results | integer (1-500) | no | maximum contacts to discover (default: 50) | | followup_days | integer[] | no | days after initial outreach to send follow-ups (e.g. [3, 7, 14]) | | outreach_channels | ("email" | "instagram" | "twitter")[] | no | channels to send outreach on (default: ["email"]) | | status | "draft" | "active" | "paused" | "completed" | no | initial campaign status (default: "draft") | | selected_venues | object[] | no | discovered venue/contact objects to import into the campaign at creation | | min_budget | number | no | minimum budget (must not exceed max_budget) | | max_budget | number | no | maximum budget | | event_date | string | no | event date (venue/event objectives) | | expected_attendees | integer | no | expected attendee count | | time_slot_start | string | no | event time slot start | | time_slot_end | string | no | event time slot end | **response (200):** ```json { "success": true, "data": { "id": "uuid", "name": "spring outreach", "objective_type": "product_promotion", "status": "draft", "created_at": "2024-01-15T10:30:00Z" } } ``` **errors:** - 400 SERVER_002: campaign needs goal, product, or sender context before drafts can be generated (non-venue campaign missing sender context) - 402 PAYMENT_005: insufficient credits (1 credit required) - purchase credits at POST /agent/credits - 429 CAMP_009: campaign limit reached for billing period **notes:** - sender context is required for non-venue campaigns: set at least one of goal_description, product_name, product_description, or a sender key inside dynamic_fields (sender_company, sender_role, target_audience, ...). objective_type values starting with 'venue_' are exempt - they carry structured venue fields instead. - agent payments: this is the only paid operation in the public API for agents. x402 agents pay $2.25 USDC per campaign. read the PAYMENT-REQUIRED header from the 402, sign it, and replay with a PAYMENT-SIGNATURE header (x402 v2). MPP agents deduct 1 credit from a credit pack ($2.40 effective). discovery, AI drafting, and message sends run automatically inside the campaign workflow as internal QStash jobs. agents never call /discovery/search, /ai/generate, or /channels/send directly (those endpoints require an API key). - iris does not offer an x402 free tier - every agent campaign requires payment. - see the agent-payments and credit-packs sections for the full 402 challenge flow. #### GET /campaigns/:id get a specific campaign with full details **scope:** `read` **errors:** - 404 CAMP_001: campaign not found #### PATCH /campaigns/:id update a campaign **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | no | campaign name (1-200 chars) | | objective_type | string (1-100 chars) | no | free-text goal summary | | status | "draft" | "scheduled" | "active" | "paused" | "completed" | "deleted" | no | campaign status. transitions are validated: draft → active, active → paused/completed, paused → active/completed, completed → active (reactivation). activating a campaign requires at least one contact | | product_name | string | no | product name (max 200 chars) | | product_url | string | no | product URL (max 2000 chars) | | product_description | string | no | product description (max 5000 chars) | | goal_description | string | no | what the campaign should achieve (max 2000 chars) | | dynamic_fields | object | no | freeform context key-values (sender_company, sender_role, target_audience, ...) | | min_budget | number | no | minimum budget (must not exceed max_budget) | | max_budget | number | no | maximum budget | | location | string | no | location to target | | location_lat | number | no | location latitude | | location_lng | number | no | location longitude | | radius_miles | integer (1-100) | no | search radius in miles | | keywords | string[] | no | discovery keywords | | venue_types | string[] | no | venue types | | max_results | integer (1-500) | no | maximum contacts to discover | | followup_days | integer[] | no | days after initial outreach to send follow-ups | | outreach_channels | ("email" | "instagram" | "twitter")[] | no | channels to send outreach on | | event_date | string | no | event date (venue/event objectives) | | expected_attendees | integer | no | expected attendee count | | time_slot_start | string | no | event time slot start | | time_slot_end | string | no | event time slot end | | start_date | string | no | campaign start date (must not be after end_date) | | end_date | string | no | campaign end date | **errors:** - 404 CAMP_001: campaign not found - 400 CAMP_008: invalid status transition, including activating a campaign that has no contacts #### DELETE /campaigns/:id soft-delete a campaign (sets status to 'deleted') **scope:** `write` **response:** 204 no content **errors:** - 404 CAMP_001: campaign not found #### GET /campaigns/:id/contacts list contacts in a campaign **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | status | string | no | filter by contact status | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "user_id": "uuid", "email": "jane@example.com", "first_name": "Jane", "last_name": "Smith", "company_name": "Acme Inc", "job_title": "Head of Marketing", "phone": null, "website": null, "tags": ["lead", "enterprise"], "enrichment_data": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "deleted_at": null, "campaign_contact_id": "uuid", "campaign_contact_status": "active", "added_at": "2024-01-15T10:30:00Z" } ], "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } ``` **errors:** - 404 CAMP_001: campaign not found #### POST /campaigns/:id/contacts add contacts to a campaign, by id or by creating them inline **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | contact_ids | array | no | ids of existing contacts to link to this campaign | | contacts | array | no | new contacts to create and link (same shape as POST /contacts) | | deduplicate | boolean | no | skip contacts already linked to this campaign (default: true) | **response (201):** ```json { "success": true, "data": { "added_count": 7, "duplicates_count": 0, "total_contacts": 7 } } ``` **errors:** - 422 SERVER_005: contacts or contact_ids is required - 404 CAMP_001: campaign not found - 429 CONTACT_009: contact limit reached **notes:** - pass `contact_ids` to link contacts that already exist, `contacts` to create and link new ones, or both - a campaign needs at least one contact before it can be activated - new contacts count against the plan's contact quota; already-linked contacts are counted as duplicates and skipped #### GET /campaigns/chats list your iris chat sessions, most recently updated first (max 100) **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "campaign_id": "uuid", "title": "creator outreach for the spring drop", "status": "active", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T11:02:00Z" } ] } ``` **notes:** - chats are the conversational campaign builder; `POST /campaigns/chat` streams a turn as server-sent events and is not part of this JSON contract #### PATCH /campaigns/chats/:id rename a chat session **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | title | string | yes | new title (trimmed, max 200 chars) | **errors:** - 422 SERVER_005: title is required - 404 SERVER_003: chat not found #### DELETE /campaigns/chats/:id soft-delete a chat session **scope:** `write` **response (200):** ```json { "success": true, "data": { "id": "uuid" } } ``` **errors:** - 404 SERVER_003: chat not found #### GET /campaigns/chats/:id/messages list the messages in a chat session, oldest first **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "chat_id": "uuid", "role": "assistant", "content": [{ "type": "text", "text": "here's a campaign for that." }], "created_at": "2024-01-15T10:30:00Z" } ] } ``` **errors:** - 404 SERVER_003: chat not found **notes:** - `content` is an array of opaque blocks (text / tool_use / tool_result) #### GET /campaigns/:id/usage get campaign usage statistics **scope:** `read` **response (200):** ```json { "success": true, "data": { "campaign_id": "uuid", "status": "active", "total_contacts": 150, "total_conversations": 42, "delivery_status": { "sent": 42, "delivered": 40, "opened": 28, "clicked": 12 }, "discovery_job_id": null } } ``` **errors:** - 404 CAMP_001: campaign not found **notes:** - discovery_job_id is the contact search running for this campaign right now (poll GET /discovery/jobs/:id); null when none is. #### POST /campaigns/:id/analyze queue AI analysis that writes the campaign's target profiles **scope:** `write` **errors:** - 400 SERVER_002: nothing to analyze (no product name or goal description), or an analysis started in the last ten minutes is still running - 404 CAMP_001: campaign not found - 429 AI_004: AI rate limit exceeded **notes:** - product_promotion campaigns are analyzed from the product URL/description; every other campaign from its goal_description. a location the goal names is stored on the campaign when it has none. - returns immediately with analysis_status 'analyzing' - poll GET /campaigns/:id until it is 'completed' (or 'failed', with analysis_error), then list the profiles or run POST /discovery/search/campaign. - a campaign created through onboarding is analyzed automatically, and its first contact search starts as soon as the profiles exist. #### GET /campaigns/:id/target-profiles list target profiles for a campaign **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "campaign_id": "uuid", "name": "SaaS founders", "profile_type": "b2b_professional", "fit_score": 85, "job_titles": ["CEO", "CTO", "founder"], "industries": ["technology", "SaaS"], "discovery_keywords": ["saas founder", "tech startup"], "recommended_channels": [] } ] } ``` **errors:** - 404 CAMP_001: campaign not found #### POST /campaigns/:id/target-profiles create a target profile for a campaign **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | yes | profile name (max 200 chars) | | profile_type | "local_business" | "content_creator" | "influencer" | "b2b_professional" | "ecommerce" | "saas_company" | "agency" | "freelancer" | "other" | yes | target profile type | | description | string | no | who this profile targets (max 2000 chars) | | fit_score | integer (0-100) | no | how well this profile fits the campaign | | job_titles | string[] | no | target job titles | | industries | string[] | no | target industries | | company_sizes | string[] | no | target company sizes (e.g. '1-10') | | pain_points | string[] | no | problems this profile feels | | buying_signals | string[] | no | signals they're ready to buy | | discovery_sources | string[] | no | discovery sources to search (e.g. google_maps, instagram) | | discovery_keywords | string[] | no | keywords for contact discovery | | outreach_angle | string | no | the hook messages should lead with (max 2000 chars) | **errors:** - 404 CAMP_001: campaign not found #### DELETE /campaigns/:id/target-profiles/:profileId delete a target profile **scope:** `write` **response:** 204 no content **errors:** - 404 CAMP_001: campaign or profile not found ### audiences your reusable audience library - target profiles created once (manually or AI-generated from a product) and attached to any campaign. attaching copies the profile into the campaign, so campaign edits never touch the library master. #### GET /audiences list your audience library (newest first) **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "name": "indie coffee shops", "description": "independent cafes with an active local following", "profile_type": "local_business", "fit_score": 82, "job_titles": ["owner", "general manager"], "industries": ["food and beverage", "hospitality"], "company_sizes": ["1-10"], "pain_points": ["slow weekday mornings", "no online ordering"], "buying_signals": ["hiring baristas", "new location announcement"], "discovery_sources": ["google_maps", "instagram"], "discovery_keywords": ["specialty coffee", "third wave cafe"], "outreach_angle": "help them turn quiet weekday mornings into regulars", "contacts_discovered": 24, "created_at": "2026-07-01T00:00:00Z", "updated_at": "2026-07-09T14:30:00Z" } ], "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } ``` #### POST /audiences create a library profile manually. names are unique per library (case-insensitive). **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | name | string | yes | audience name (1-100 chars) | | profile_type | "local_business" | "content_creator" | "influencer" | "b2b_professional" | "ecommerce" | "saas_company" | "agency" | "freelancer" | "other" | yes | target profile type | | description | string | no | who this audience is (max 500 chars) | | fit_score | integer (0-100) | no | how well this audience fits your product | | job_titles | string[] | no | target job titles (max 10) | | industries | string[] | no | target industries (max 10) | | company_sizes | string[] | no | target company sizes (max 10, e.g. '1-10') | | pain_points | string[] | no | problems they feel (max 10) | | buying_signals | string[] | no | signals they're ready to buy (max 10) | | discovery_sources | string[] | no | discovery sources to search (max 10, e.g. google_maps, instagram) | | discovery_keywords | string[] | no | keywords for contact discovery (max 10) | | outreach_angle | string | no | the hook messages should lead with (max 500 chars) | **response (201):** ```json { "success": true, "data": { "id": "uuid", "name": "indie coffee shops", "description": "independent cafes with an active local following", "profile_type": "local_business", "fit_score": 82, "job_titles": ["owner", "general manager"], "industries": ["food and beverage"], "company_sizes": [], "pain_points": ["slow weekday mornings"], "buying_signals": [], "discovery_sources": [], "discovery_keywords": ["specialty coffee"], "outreach_angle": "help them turn quiet weekday mornings into regulars", "contacts_discovered": 0, "created_at": "2026-07-09T14:30:00Z", "updated_at": "2026-07-09T14:30:00Z" } } ``` **errors:** - 400 SERVER_002: an audience with this name already exists - 422 SERVER_005: validation failed #### GET /audiences/:id get one library profile **scope:** `read` **response (200):** ```json { "success": true, "data": { "id": "uuid", "name": "indie coffee shops", "description": "independent cafes with an active local following", "profile_type": "local_business", "fit_score": 82, "job_titles": ["owner", "general manager"], "industries": ["food and beverage"], "company_sizes": ["1-10"], "pain_points": ["slow weekday mornings"], "buying_signals": ["hiring baristas"], "discovery_sources": ["google_maps"], "discovery_keywords": ["specialty coffee"], "outreach_angle": "help them turn quiet weekday mornings into regulars", "contacts_discovered": 24, "created_at": "2026-07-01T00:00:00Z", "updated_at": "2026-07-09T14:30:00Z" } } ``` **errors:** - 404 SERVER_003: audience not found #### DELETE /audiences/:id delete a library profile. campaigns it was attached to keep their copy (those use the campaign target-profile DELETE). **scope:** `write` **response:** 204 no content **errors:** - 404 SERVER_003: audience not found #### POST /audiences/:id/attach copy a library profile into a campaign. the response is the campaign's own copy (a TargetProfile) - editing it never touches the library master. if the campaign already has a profile with the same name, the existing copy is returned instead. **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | campaign_id | uuid | yes | the campaign to attach to (must be yours and not completed or deleted) | **response (201):** ```json { "success": true, "data": { "id": "uuid", "campaign_id": "uuid", "user_id": "uuid", "name": "indie coffee shops", "profile_type": "local_business", "fit_score": 82, "job_titles": ["owner", "general manager"], "industries": ["food and beverage"], "pain_points": ["slow weekday mornings"], "buying_signals": ["hiring baristas"], "discovery_keywords": ["specialty coffee"], "recommended_channels": [], "created_at": "2026-07-09T14:30:00Z", "updated_at": "2026-07-09T14:30:00Z" } } ``` **errors:** - 400 SERVER_002: campaign is completed or deleted - 404 SERVER_003: audience not found - 404 CAMP_001: campaign not found #### POST /audiences/generate AI-generate library profiles from a product (scrape + analysis). returns the created profiles; generated names already in your library are skipped, not overwritten. rate limited to 5 per hour. **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | product_name | string | yes | product name (1-200 chars) | | product_url | https url | no | product website - scraped for extra context | | product_description | string | no | what it does and who it's for (max 2000 chars) | **response (201):** ```json { "success": true, "data": [ { "id": "uuid", "name": "boutique fitness studios", "description": "independent gyms and studios booking classes online", "profile_type": "local_business", "fit_score": 88, "job_titles": ["owner", "studio manager"], "industries": ["fitness", "wellness"], "company_sizes": ["1-10"], "pain_points": ["no-shows", "manual scheduling"], "buying_signals": ["hiring front desk staff"], "discovery_sources": ["google_maps", "instagram"], "discovery_keywords": ["boutique fitness", "yoga studio"], "outreach_angle": "cut no-shows with automated scheduling", "contacts_discovered": 0, "created_at": "2026-07-09T14:30:00Z", "updated_at": "2026-07-09T14:30:00Z" } ] } ``` **errors:** - 403 BILLING_003: audience generation needs an active subscription - 422 SERVER_005: validation failed - 429 RATE_001: generation rate limit exceeded (5 per hour) ### contacts manage contacts and import leads. #### GET /contacts list all contacts **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | search | string | no | search by name or email | | campaign_id | uuid | no | filter to contacts in a campaign | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "email": "jane@example.com", "first_name": "Jane", "last_name": "Smith", "company_name": "Acme Inc", "tags": ["lead", "enterprise"] } ], "pagination": { "page": 1, "page_size": 50, "total": 1, "total_pages": 1 } } ``` #### POST /contacts create a single contact. idempotent on email: if a contact with the same email already exists for this user, returns 201 with the existing record (merging any new fields you supply) instead of 409. **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | email | string | no | contact email - optional; contacts can exist with social handles only. dedup and merging key on it | | first_name | string | no | first name | | last_name | string | no | last name | | company_name | string | no | company name | | instagram_handle | string | no | instagram handle | | twitter_handle | string | no | twitter/x handle | | tiktok_handle | string | no | tiktok handle | | notes | string | no | freeform notes | | discovery_method | string | no | how the contact was discovered | | tags | string[] | no | tags for categorization | | campaign_ids | uuid[] | no | campaigns to associate with | | campaign_id | uuid | no | single campaign to associate with (folded into campaign_ids server-side) | **errors:** - 429 CONTACT_009: contact limit reached for billing period #### GET /contacts/:id get a specific contact **scope:** `read` **errors:** - 404 CONTACT_001: contact not found #### PATCH /contacts/:id update a contact **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | first_name | string | no | first name | | last_name | string | no | last name | | company_name | string | no | company name | | tags | string[] | no | tags | | instagram_handle | string | no | instagram handle | | twitter_handle | string | no | twitter/x handle | | tiktok_handle | string | no | tiktok handle | | campaign_ids_to_add | uuid[] | no | campaigns to add this contact to | | campaign_ids_to_remove | uuid[] | no | campaigns to remove this contact from | **errors:** - 404 CONTACT_001: contact not found #### DELETE /contacts/:id soft-delete a contact (sets deleted_at timestamp) **scope:** `write` **response:** 204 no content **errors:** - 404 CONTACT_001: contact not found #### POST /contacts/bulk bulk import contacts (up to 500 per request) **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | contacts | array | yes | array of contact objects (same fields as POST /contacts - email optional; duplicates merged by email or social handle: instagram/twitter/tiktok, case-insensitive, @ stripped, including within one request - retried imports are idempotent) | | campaign_id | uuid | no | campaign to associate contacts with | **response (200):** ```json { "success": true, "data": { "created": 46, "updated": 2, "failed": 2, "contacts": [ { "id": "uuid", "user_id": "uuid", "email": "jane@example.com", "first_name": "Jane", "last_name": "Smith", "company_name": "Acme Inc", "job_title": null, "phone": null, "website": null, "tags": [], "enrichment_data": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z", "deleted_at": null } ], "errors": [{ "email": "bad@", "error": "invalid email format" }] } } ``` **errors:** - 429 CONTACT_009: contact limit reached for billing period **notes:** - duplicates are merged by email (counted as updated). max 500 contacts per request. #### DELETE /contacts/bulk bulk soft-delete contacts by ID **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | contact_ids | uuid[] | yes | non-empty array of contact IDs to delete | **response (200):** ```json { "success": true, "data": { "deletedCount": 12, "affectedCampaignIds": ["uuid"], "totalArchivedConversations": 3 } } ``` **notes:** - sets deleted_at on each contact - same soft-delete semantics as DELETE /contacts/:id. #### GET /contacts/usage get contact usage for the current billing period **scope:** `read` **response (200):** ```json { "success": true, "data": { "total_contacts": 1240, "period_contacts": 150, "period_limit": 30, "period_start": "2024-01-01T00:00:00Z", "period_end": "2024-02-01T00:00:00Z" } } ``` **notes:** - period_limit is per-campaign, not per-period. null on plans where the per-campaign cap is unlimited (admin/team plans). - period_contacts counts contacts created in the current billing period; total_contacts is the lifetime count of non-deleted contacts on the account. #### GET /contacts/:id/conversations get conversations for a specific contact **scope:** `read` **errors:** - 404 CONTACT_001: contact not found #### GET /contacts/:id/handles the contact's social handles with engagement metadata (profile_url, is_engageable, follower_count, engagement_rate). since 2.16.0 the contact responses also carry the plain instagram_handle/twitter_handle/tiktok_handle fields directly **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | id | uuid | yes | contact id | **response (200):** ```json { "success": true, "data": [ { "channel": "tiktok", "handle": "creator.one", "profile_url": "https://tiktok.com/@creator.one", "is_engageable": true, "follower_count": 120000, "engagement_rate": 0.041 } ] } ``` **errors:** - 404 CONTACT_001: contact not found ### conversations manage conversations across all channels. #### GET /conversations list all conversations **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | status | string | no | filter by status (active, archived, closed) | | channel | string | no | filter by channel (email, instagram, twitter, tiktok) | | campaign_id | uuid | no | filter by campaign | #### POST /conversations find-or-create a conversation for a contact - the hub conversation by default, or the campaign-scoped thread when campaign_id is passed (the contact must be a member of that campaign) **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | contact_id | uuid | yes | the contact to converse with | | campaign_id | uuid | no | scope to a campaign the contact belongs to. closes the activation-order gap: campaign threads no longer depend on drafting having run | **notes:** - idempotent: returns the existing conversation for the requested scope if one exists - add messages via POST /conversations/:id/messages - pending-approval statuses land drafts in the review queue #### GET /conversations/:id get a conversation with its contact and full message thread **scope:** `read` **response (200):** ```json { "success": true, "data": { "id": "uuid", "campaign_id": "uuid", "contact_id": "uuid", "user_id": "uuid", "channel": "email", "status": "active", "metadata": null, "contacts": { "id": "uuid", "full_name": "Jane Smith", "email": "jane@example.com", "company_name": "Acme Inc" }, "messages": [ { "id": "uuid", "conversation_id": "uuid", "direction": "outbound", "channel": "email", "content": "Hi Jane, ...", "status": "sent", "metadata": null, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ], "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } ``` **errors:** - 404 CONVERSATION_001: conversation not found #### PATCH /conversations/:id update a conversation's status **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | status | "active" | "archived" | "closed" | yes | new conversation status | **response (200):** ```json { "success": true, "data": { "id": "uuid", "campaign_id": "uuid", "contact_id": "uuid", "user_id": "uuid", "channel": "email", "status": "archived", "metadata": {}, "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T09:00:00Z" } } ``` **errors:** - 422 SERVER_005: status must be one of: active, archived, closed - 404 CONVERSATION_001: conversation not found #### GET /conversations/:id/messages get messages for a conversation **scope:** `read` **errors:** - 404 CONVERSATION_001: conversation not found #### POST /conversations/:id/messages create a message in a conversation **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | content | string | yes | message content | | direction | string | yes | one of: inbound, outbound | | status | string | yes | one of: draft, queued, sending, pending_approval, sent, delivered, failed, bounced, rejected | | channel | string | yes | one of: email, twitter, instagram, tiktok (tiktok is manual-send: drafts + CRM recording only, no API delivery) | | platform_recipient_id | string | no | platform recipient id (twitter/instagram channels) | **errors:** - 404 CONVERSATION_001: conversation not found **notes:** - status pending_approval places the message in the human review queue instead of sending - inbound messages fire the conversation.reply_received webhook event #### POST /conversations/:id/read mark a conversation as read **scope:** `write` **response (200):** ```json { "success": true, "data": { "unread_count": 0, "contact_id": "uuid", "already_read": false } } ``` **errors:** - 404 CONVERSATION_001: conversation not found #### GET /conversations/:id/responder get the responder's state for one conversation: whether iris is replying there, and if not, why. status is null for a conversation the responder has never seen **scope:** `read` **response (200):** ```json { "success": true, "data": { "conversation_id": "uuid", "status": "handed_off", "reason": "contact_asked_for_person", "origin": "dm", "replies_sent": 3, "last_inbound_at": "2026-09-28T17:58:00Z", "last_reply_at": "2026-09-28T17:41:20Z", "booking_link_sent_at": null } } ``` **errors:** - 404 CONVERSATION_001: conversation not found - 422 SERVER_005: the conversation id is not a uuid **notes:** - status: active (iris may reply), paused (you stepped in or paused it), handed_off (iris stopped on its own), or null - reason: human_replied, user_paused, contact_asked_for_person, needs_answer, sensitive, opted_out, reply_cap, message_limit, send_failed, outside_window, attachment, unsafe_reply #### PATCH /conversations/:id/responder pause or resume automatic replies in one conversation. pausing works on any conversation, including one iris has not replied in yet. sending a message yourself pauses it too **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | status | "active" | "paused" | yes | paused stops automatic replies here. active lets iris reply again | **response (200):** ```json { "success": true, "data": { "conversation_id": "uuid", "status": "paused", "reason": "user_paused", "origin": "dm", "replies_sent": 3, "last_inbound_at": "2026-09-28T17:58:00Z", "last_reply_at": "2026-09-28T17:41:20Z", "booking_link_sent_at": null } } ``` **errors:** - 400 SERVER_002: the person asked iris to stop, so automatic replies cannot be resumed here - 404 CONVERSATION_001: conversation not found - 422 SERVER_005: status is not active or paused, or the conversation id is not a uuid - 429 RATE_001: rate limit exceeded (20 changes per minute) #### GET /conversations/engagement get engagement metrics across conversations **scope:** `read` **response (200):** ```json { "success": true, "data": { "total": 250, "unread": 18, "by_status": { "active": 42, "archived": 8, "closed": 200 }, "by_channel": { "email": 210, "twitter": 25, "instagram": 15 } } } ``` ### messages manage message approval workflow and sending. #### GET /messages/pending list messages pending approval **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | status | string | no | filter by queue status (pending, approved, rejected, sending, sent, failed, revising) (default: pending) | | channel | string | no | filter by channel (email, twitter, instagram, tiktok) | | campaign_id | uuid | no | filter by campaign | #### POST /messages/:id/approve approve a pending message for sending **scope:** `send` **errors:** - 404 MESSAGE_005: message not found - 409 MESSAGE_004: message already approved #### POST /messages/:id/reject reject a pending message **scope:** `send` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | reason | string | no | rejection reason | **errors:** - 404 MESSAGE_005: message not found #### POST /messages/:id/retry retry a failed message. one that was never drafted (empty body) is drafted again instead of sent **scope:** `send` **errors:** - 404 MESSAGE_005: message not found #### POST /messages/:id/feedback submit feedback to revise a message with AI **scope:** `send` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | feedback | string | yes | revision instructions (e.g. 'make it more casual and shorter') | | approval_queue_id | string | no | approval queue item to revise (when the draft sits in the review queue) | **errors:** - 404 MESSAGE_005: message not found - 429 AI_004: AI rate limit exceeded #### POST /messages/:id/mark-sent mark a pending manual-channel draft as sent outside the platform. manual channels are the ones the API cannot deliver on: every tiktok draft, and instagram cold first-touch. completes the draft - review - done lifecycle for manual DMs **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | id | uuid | yes | approval queue item id, or the message id - drafts created through POST /conversations/:id/messages have no approval item, so their message id is the handle (2.18.0) | **errors:** - 400 SERVER_002: draft is API-sendable or channel not manual - 404 SERVER_003: no pending draft or approval item with that id **notes:** - api-sendable drafts (email, twitter, instagram follow-ups with a connected account) must go through /approve instead - a recorded 'sent' always means a real transmission - instagram cold first-touch additionally requires a connected instagram account (replies arrive via webhook); tiktok does not (record replies via POST /conversations/:id/messages) - a draft with no approval item gets a terminal 'sent' item recorded when its campaign contact resolves; approval_id is null when it cannot be #### POST /messages/bulk bulk approve or reject messages **scope:** `send` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | action | "approve" | "reject" | yes | action to perform | | message_ids | uuid[] | yes | message queue item IDs (1-100) | | reason | string | no | rejection reason (only used when action is reject) | **response (200):** ```json { "success": true, "data": { "affected_count": 5, "contact_ids": ["uuid", "uuid"], "skipped_count": 0, "status": "approved" } } ``` **notes:** - approve returns affected_count, contact_ids, skipped_count, and status; reject returns affected_count and contact_ids only. ### AI AI-powered content generation and analysis. #### POST /ai/generate generate AI content (email subject + body) **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | generation_type | string | yes | type of content to generate (e.g. initial_outreach, follow_up, reply) | | tone | string | yes | tone for the generated content (e.g. professional, casual, warm-direct) | | campaign_id | uuid | no | campaign to scope the generation to | | contact_id | uuid | no | target contact ID | | prompt | string | no | additional freeform instructions for the generation | | format | "email" | "dm" | no | output format. 'dm' produces short platform-native message text with an empty subject - no greeting, no signature. defaults to email (default: email) | | input_context | object | no | structured context, e.g. { include_cta: boolean } | **errors:** - 429 AI_004: AI rate limit exceeded - 500 AI_002: AI generation failed **notes:** - requires an API key with `generate` scope. agents do not call this directly. drafting runs as an internal QStash worker inside POST /campaigns. - when contact_id is set, the contact's tags and enrichment_data are fed into the generation context automatically - store per-contact intel there instead of smuggling it through prompt - the draft states nothing the context doesn't support: it is grounded in the account's saved outreach background plus the campaign's goal/product fields, and never invents a company, location, or customer win. with no sender context on the campaign at all, the draft stays general and confidence_score is capped at 0.4 #### POST /ai/generate/campaign generate campaign-level outreach content (email sequence, templates) from an inline brief. content-first: pass the strategy directly, no campaign id required **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | campaign_name | string | yes | campaign name (used as the brief title) | | objective | string | yes | campaign objective (e.g. "book DJ gigs", "sell SaaS to VPs of Eng") | | target_audience | string | yes | target audience description | | key_benefits | string[] | yes | non-empty list of key benefits to emphasise | | tone | string | yes | tone (e.g. professional, casual, warm-direct) | **errors:** - 422 SERVER_005: missing or invalid request body - 429 AI_004: AI rate limit exceeded #### POST /ai/analyze analyze an inbound message (email or DM) for intent, sentiment, key points, and a suggested reply **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | conversation_id | uuid | yes | conversation ID: the analysis is scoped to this thread's history and contact | | message_content | string | yes | inbound message text to analyze. `email_content` is accepted as a legacy alias. | **response (200):** ```json { "success": true, "data": { "intent_type": "interested", "sentiment": "positive", "key_points": ["asked about pricing for 50 seats", "wants demo next week"], "suggested_response": "Hi {{first_name}}, ...", "requires_human_review": false, "extracted_data": { "seats": 50, "timing": "next week" } } } ``` **errors:** - 429 AI_004: AI rate limit exceeded **notes:** - requires an API key with `generate` scope. agents do not call this directly. response analysis runs as an internal step of the campaign workflow when an inbound reply arrives. #### GET /ai/usage get AI generation counts for the current billing period, broken down by generation_type. iris does not enforce a separate AI quota - generations are bounded implicitly by the campaign envelope, so no limit field is exposed. **scope:** `read` **response (200):** ```json { "success": true, "data": { "billing_period_start": "2026-04-30T01:00:04.245Z", "billing_period_end": "2026-05-30T01:00:04.245Z", "total_generations": 14, "total_tokens": 11680, "by_generation_type": { "draft_email": 8, "draft_dm": 4, "suggested_response": 2 } } } ``` ### discovery search for and discover new contacts. #### POST /discovery/search start an asynchronous contact discovery search across configured sources (Instagram, TikTok, and public business listings). returns a job_id - poll GET /discovery/jobs/:id for results **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | keywords | string[] | yes | non-empty array of keywords to search for (e.g. ['coffee shop', 'cafe']) | | location | string | no | location to search around (city, address, lat/lng string) | | radius_miles | number | no | search radius in miles (default: 25) | | max_results | integer | no | maximum results to return (10-500) (default: 50) | | sources | string[] | no | discovery sources to use (e.g. ['instagram', 'tiktok']). defaults to all available sources | | campaign_id | uuid | no | campaign to associate discovered contacts with | | profile_type | "local_business" | "content_creator" | "influencer" | "b2b_professional" | "ecommerce" | "saas_company" | "agency" | "freelancer" | "other" | no | target profile type, used to route the appropriate discovery source | | enrich_emails | boolean | no | attempt to enrich discovered contacts with email addresses (default: true) | **response (200):** ```json { "success": true, "data": { "job_id": "uuid" } } ``` **errors:** - 429 DISCOVERY_008: discovery quota exceeded - 429 DISCOVERY_006: discovery rate limited **notes:** - discovery is asynchronous - the response returns a job_id only. poll GET /discovery/jobs/:id until status is 'completed' to retrieve the discovered contacts. - to fan out a discovery run by campaign target profile, use POST /discovery/search/campaign (also async - poll GET /discovery/jobs/:id). - requires an API key with `generate` scope. agents do not call this directly. discovery runs as an internal step of POST /campaigns. #### POST /discovery/search/campaign run discovery search using campaign target profiles **scope:** `generate` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | campaign_id | uuid | yes | campaign ID | | selected_profile_ids | uuid[] | no | specific target profile IDs to use (defaults to all profiles on the campaign) | | additional_keywords | string[] | no | extra keywords to append to each profile's discovery query | | max_results | integer | no | maximum results to return (10-500) (default: 50) | | sources | string[] | no | discovery sources to use (e.g. ['instagram', 'tiktok']). defaults to all available sources | **response (200):** ```json { "success": true, "data": { "job_id": "uuid" } } ``` **errors:** - 400 SERVER_002: campaign has no target profiles yet - analyze it first - 404 CAMP_001: campaign not found - 409 SERVER_016: a contact search is already running for this campaign - 429 DISCOVERY_008: discovery quota exceeded **notes:** - discovery is asynchronous - the response returns a job_id only. poll GET /discovery/jobs/:id until status is 'completed'. - contacts the search finds are added to the campaign when it completes, and a notification reports the count (or that nothing usable was found). - one search per campaign at a time: a second request while one runs returns 409. #### GET /discovery/jobs/:id get the status of a discovery job **scope:** `read` **response (200):** ```json { "success": true, "data": { "id": "uuid", "status": "completed", "progress_percent": 100, "progress_message": "discovery complete", "error": null, "started_at": "2024-01-15T10:30:00Z", "completed_at": "2024-01-15T10:35:00Z", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:35:00Z", "contact_count": 42, "contacts": [] } } ``` **errors:** - 404 DISCOVERY_002: discovery job not found #### GET /discovery/sources list available discovery data sources **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "instagram", "name": "Instagram", "available": true }, { "id": "tiktok", "name": "TikTok", "available": true } ] } ``` ### analytics campaign performance metrics and reporting. #### GET /analytics/overview get overall analytics overview across all campaigns **scope:** `read` **response (200):** ```json { "success": true, "data": { "campaigns": { "total": 12, "by_status": { "draft": 4, "active": 3, "completed": 5 } }, "contacts": { "total": 1250 }, "conversations": { "total": 450, "by_status": { "active": 120, "closed": 330 } }, "messages": { "total": 230, "by_status": { "approved": 200, "pending_approval": 30 } } } } ``` **notes:** - by_status keys are dynamic. they reflect whatever statuses exist in the user's data. Common values: campaigns (draft, active, paused, completed); conversations (active, archived, closed); messages (pending_approval, approved, rejected, sent, failed). #### GET /analytics/campaigns/:id get analytics for a specific campaign **scope:** `read` **response (200):** ```json { "success": true, "data": { "campaign": { "id": "uuid", "name": "Q1 outreach", "status": "active", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-16T08:00:00Z" }, "contacts": { "total": 150, "by_status": { "active": 120, "opted_out": 30 } }, "conversations": { "total": 42, "by_status": { "active": 12, "closed": 30 } }, "messages": { "total": 230, "by_status": { "sent": 200, "pending_approval": 30 } }, "delivery_status": { "sent": 42, "delivered": 40, "opened": 28, "clicked": 12 } } } ``` **errors:** - 404 CAMP_001: campaign not found #### GET /analytics/performance get a daily series of message counts by status. a sent message is counted on the day it was sent; a draft, queued, or failed one on the day it was created **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | days | integer | no | number of days to include in the time series (1-90) (default: 30) | | campaign_id | uuid | no | filter to a single campaign | #### GET /analytics/response-time get average and median time from the first outreach message sent in a conversation to the first reply after it. the responder's automatic messages do not start the clock, and automatic email replies are not replies **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | campaign_id | uuid | no | filter by campaign | #### GET /analytics/contact-types get contact type distribution **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | campaign_id | uuid | no | filter to a single campaign | ### billing view billing plans and subscription information. #### GET /me the authenticated user's profile + onboarding state (used for post-login routing) **scope:** `read` **response (200):** ```json { "success": true, "data": { "id": "uuid", "email": "you@example.com", "full_name": "Jane Smith", "created_at": "2024-01-15T10:30:00Z", "is_team": false, "has_completed_onboarding": true } } ``` #### POST /billing/portal create a Stripe billing-portal session and return the URL to send the user to **scope:** `write` **response (200):** ```json { "success": true, "data": { "url": "https://billing.stripe.com/session/..." } } ``` **notes:** - a user with no Stripe customer yet (free plan, never subscribed) gets the web billing page URL back with a 200 - there is no error case for it #### GET /usage get your current plan, quota usage, and billing period in one call - the campaign envelope (campaigns per period with used/remaining) plus the per-campaign contact and message limits. `"unlimited"` replaces numeric limits on team plans. **scope:** `read` **response (200):** ```json { "success": true, "data": { "plan": "starter", "is_locked": false, "is_team": false, "billing_period": { "start": "2026-07-01T00:00:00.000Z", "end": "2026-07-31T23:59:59.999Z" }, "limits": { "campaigns_per_period": { "limit": 5, "used": 2, "remaining": 3 }, "contacts_per_campaign": { "limit": 30 }, "messages_per_campaign": { "limit": 240 } } } } ``` #### GET /billing/plans get available billing plans and their features **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "plan_name": "free", "display_name": "Free", "description": "get started at no cost", "monthly_price_cents": 0, "yearly_price_cents": 0, "campaigns_per_period": 1, "contacts_per_campaign": 30, "messages_per_campaign": 240, "is_active": true, "sort_order": 0, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" }, { "id": "uuid", "plan_name": "starter", "display_name": "Starter", "description": "for growing outreach", "monthly_price_cents": 1200, "yearly_price_cents": 12000, "campaigns_per_period": 5, "contacts_per_campaign": 30, "messages_per_campaign": 240, "is_active": true, "sort_order": 1, "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z" } ] } ``` ### affiliate your affiliate status, link, sign-ups, and commission totals, with the program terms. #### GET /affiliate get your affiliate status, link, sign-up count, and commission totals **scope:** `read` **response (200):** ```json { "success": true, "data": { "status": "approved", "code": "yourname", "link": "https://www.iris-ai.dev/?via=yourname", "referrals": 7, "commissions": { "pending_cents": 1740, "payable_cents": 870, "paid_out_cents": 2610 }, "terms": { "commission_rate_percent": 30, "commission_window_months": 12, "payout_hold_days": 30, "referral_cookie_days": 30 } } } ``` **notes:** - status is "none" (never applied), "pending" (waiting for review), "approved", or "rejected". code is null when status is "none" - link is set only while status is approved. a pending or rejected code credits no sign-ups - referrals counts people who signed up within referral_cookie_days of first clicking your link - commissions are US cents. pending_cents is still inside the payout hold, payable_cents is past it and not yet paid, paid_out_cents has been sent. a full refund or a dispute cancels the commission on that payment, and a partial refund reduces it. a commission already paid out is not changed by a later refund - commissions come from card subscription payments on the web. App Store purchases and pay-per-campaign agent payments earn none - read-only. applying is done in the app, at /settings/affiliate; each application is reviewed, and payouts are sent by hand ### recap your last 30 days of outreach: messages sent, conversations, replies, and messages per channel. #### GET /recap get your last 30 days of outreach as counts **scope:** `read` **response (200):** ```json { "success": true, "data": { "period_start": "2026-10-12T15:04:05.000Z", "period_end": "2026-11-11T15:04:05.000Z", "sent": 48, "conversations": 41, "replied": 9, "reply_rate_percent": 22, "channels": [ { "channel": "email", "sent": 30 }, { "channel": "instagram", "sent": 18 } ] } } ``` **notes:** - the window is the 30 days ending at the request. period_start and period_end are ISO 8601 timestamps - sent counts messages you sent as outreach with status sent or delivered. the responder's automatic replies, comment-trigger DMs, and messages typed in the Instagram app are left out - a message is dated by when it was sent, not when it was drafted. a draft written before the window and sent inside it counts. messages sent before version 2.28.0 carry the send time only where one was recorded, and are otherwise dated by when they were drafted - conversations is how many conversations (one contact in one campaign) were sent at least one of those messages - replied is how many of those conversations wrote back after the first message sent to them in the window. a contact who wrote first is not counted, and neither is an email received since version 2.28.0 whose headers mark it as an automatic reply, such as an out-of-office notice - reply_rate_percent is replied divided by conversations, as a whole number. it is 0 when conversations is 0 - channels lists messages sent per channel, most-used first. a channel with no messages sent is absent - read-only, counts only: no contact names, addresses, campaign names, or message text. creating a public share link is done in the app, at /recap - returns 500 when the window holds 50,000 or more sent messages, or 50,000 or more received ones, since a partial count would be wrong ### autopilot configure the autonomous outreach loop - discovery top-ups and drafts on a standing campaign, review-only. #### GET /autopilot get autopilot status: whether it's configured, the current config, the pending-review count for the standing campaign, and the latest run's step results **scope:** `read` **response (200):** ```json { "success": true, "data": { "configured": true, "config": { "enabled": true, "campaign_id": "uuid", "max_new_contacts_per_run": 10, "max_pending_reviews": 25, "run_hour": 2, "timezone": "America/New_York", "paused": false, "pause_reason": null, "created_at": "2026-07-01T00:00:00Z", "updated_at": "2026-07-09T02:00:00Z" }, "pending_reviews": 4, "last_run": { "run_date": "2026-07-09", "steps": [ { "step": "refresh_insights", "status": "completed" }, { "step": "discover_contacts", "status": "completed" } ] } } } ``` #### PATCH /autopilot create or update the autopilot config. merge semantics: only the fields you send change; the first call creates the config with defaults for anything omitted. autopilot never sends - every drafted message waits in your approval queue. **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | enabled | boolean | no | turn the nightly loop on or off. enabling requires a campaign_id and clears any pause state | | campaign_id | uuid | no | the ONE standing campaign autopilot tends (must be yours and draft, scheduled, or active). null to unset | | max_new_contacts_per_run | integer (10-50) | no | discovery batch size per nightly run (default: 10) | | max_pending_reviews | integer (5-200) | no | skip discovery while this many drafts sit unreviewed in the approval queue (default: 25) | | run_hour | integer (0-23) | no | local hour the nightly run fires (default: 2) | | timezone | string | no | IANA timezone for run_hour (e.g. America/New_York) (default: America/New_York) | **response (200):** ```json { "success": true, "data": { "enabled": true, "campaign_id": "uuid", "max_new_contacts_per_run": 15, "max_pending_reviews": 25, "run_hour": 2, "timezone": "America/New_York", "paused": false, "pause_reason": null, "created_at": "2026-07-01T00:00:00Z", "updated_at": "2026-07-09T14:30:00Z" } } ``` **errors:** - 400 SERVER_002: invalid timezone, or enabled without a campaign_id - 403 BILLING_003: autopilot needs an active subscription #### POST /autopilot/run queue a manual autopilot run immediately. steps that already completed today are skipped, so this tops up the approval queue rather than double-discovering. rate limited to 2 per hour. **scope:** `generate` **response (202):** ```json { "success": true, "data": { "queued": true, "run_date": "2026-07-09" } } ``` **errors:** - 400 SERVER_002: autopilot is disabled or paused - 403 BILLING_003: autopilot needs an active subscription - 404 SERVER_003: autopilot is not set up yet - 429 RATE_001: manual run rate limit exceeded (2 per hour) ### responder answer inbound instagram DMs automatically, and send one DM to people who comment a keyword. off by default. needs an API key and a connected instagram account. #### GET /responder get responder status: the config, whether iris is replying right now, and counts for the last 30 days **scope:** `read` **response (200):** ```json { "success": true, "data": { "configured": true, "config": { "enabled": true, "auto_reply": true, "instructions": "1:1 coaching, $200 a session. sessions run 50 minutes over zoom.", "booking_url": "https://calendly.com/you/intro", "qualifying_questions": ["what are you hoping to work on?"], "disclosure": null, "max_replies_per_conversation": 8, "paused": false, "pause_reason": null, "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T14:30:00Z" }, "status": { "instagram_connected": true, "replying": true, "sees_instagram_app_replies": true, "comment_triggers": "ready", "paused": false, "pause_reason": null, "kill_switch": false }, "last_30_days": { "threads": 42, "replies_sent": 117, "handoffs": 9, "booking_links_sent": 14, "comment_dms_sent": 31 } } } ``` **notes:** - status.replying is true only when enabled, auto_reply, a connected instagram account, and no pause all hold - status.sees_instagram_app_replies: when true, a reply you type in the instagram app pauses iris in that conversation. when false iris only sees replies sent through iris, so pause the conversation before answering from instagram - pause_reason: failures (instagram refused 5 replies in a row), subscription, or daily_cap (iris worked on 300 inbound messages in one day). send enabled: true to resume - status.comment_triggers: ready (comment triggers send), needs_permission (the owner has to allow comments on the instagram connection, from the responder settings page in the iris web app), or unavailable (comment triggers are not offered on this account yet, and their endpoints return 403) #### PATCH /responder create or update the responder config. merge semantics: only the fields you send change; the first call creates the config with defaults for anything omitted. with auto_reply on, replies are sent without review **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | enabled | boolean | no | thread instagram DMs from anyone into the inbox. a sender iris has never seen becomes a contact. turning this off also turns auto_reply off. true clears any pause state | | auto_reply | boolean | no | let iris send replies itself. requires enabled, and either instructions or a profile background to answer from | | instructions | string (max 4000) | no | what you offer, prices, answers to common questions, tone. iris states nothing about you that is not here or in your profile background | | booking_url | https url (max 500) | no | a link people can book on (calendly, cal.com, any https url). iris adds it when someone asks to talk or book. null to unset | | qualifying_questions | string[] (max 5, 200 chars each) | no | asked one per message, in order, before the booking link is shared | | disclosure | string (10-200) | no | the line that says the reply is automated, sent once per conversation with the first reply. null uses the default | | max_replies_per_conversation | integer (1-30) | no | after this many automatic replies the conversation is handed to you (default: 8) | **response (200):** ```json { "success": true, "data": { "enabled": true, "auto_reply": true, "instructions": "1:1 coaching, $200 a session. sessions run 50 minutes over zoom.", "booking_url": "https://calendly.com/you/intro", "qualifying_questions": ["what are you hoping to work on?"], "disclosure": null, "max_replies_per_conversation": 8, "paused": false, "pause_reason": null, "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T14:30:00Z" } } ``` **errors:** - 400 SERVER_002: auto_reply without enabled, auto_reply with nothing to answer from, a booking_url that is not https, or a booking_url and disclosure too long together (700 bytes) - 403 BILLING_003: the responder needs an active subscription - 422 SERVER_005: a field of the wrong type, or past the limit listed for it - 429 RATE_001: rate limit exceeded (20 changes per minute) **notes:** - instagram only allows a reply within 24 hours of the person's last message, and only to someone who wrote first. the responder cannot start a conversation - iris stops and hands the conversation to you when someone asks for a person, asks something your instructions do not cover, raises a complaint or a refund, sends a photo or video, or says stop - a reply that carries a link, email address, or phone number is not sent unless that detail is your booking_url or appears in your instructions or profile background. the conversation is handed to you instead (reason unsafe_reply) - each automatic reply counts as a message against your plan, the same as a reply you send from the inbox - iris cannot see whether someone booked. booking_links_sent counts links shared #### GET /responder/activity list what the responder did, newest first: replies sent, conversations handed to you, messages it stood down on, and sends instagram refused **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | results per page (max 100) (default: 50) | **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "kind": "reply_sent", "reason": null, "conversation_id": "uuid", "contact_id": "uuid", "message_id": "uuid", "booking_link_sent": true, "created_at": "2026-09-28T17:41:20Z" }, { "id": "uuid", "kind": "handoff", "reason": "contact_asked_for_person", "conversation_id": "uuid", "contact_id": "uuid", "message_id": null, "booking_link_sent": false, "created_at": "2026-09-28T17:58:02Z" } ], "pagination": { "page": 1, "page_size": 50, "total": 2, "total_pages": 1 } } ``` **notes:** - kind: reply_sent, handoff, skipped (iris stood down, for example a newer message arrived), failed, comment_dm_sent, comment_dm_failed #### GET /responder/comment-triggers list comment triggers. a comment trigger sends one DM to a person who comments a keyword on your instagram post **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "keyword": "guide", "message": "thanks for asking! here is the guide: https://example.com/guide", "media_id": null, "enabled": true, "sent_count": 31, "last_sent_at": "2026-09-28T17:41:20Z", "created_at": "2026-09-20T00:00:00Z", "updated_at": "2026-09-20T00:00:00Z" } ] } ``` **errors:** - 403 BILLING_011: comment triggers are not available on this account yet **notes:** - instagram allows one DM per comment, within 7 days of the comment. nothing more can be sent to that person unless they reply. when they do, their DM is handled like any other - the DM is your message as written, followed by the automated-message notice (the responder's disclosure). no model writes or changes it - triggers send only while the responder is enabled and not paused, your subscription is active, and status.comment_triggers on GET /responder is ready. they stop with everything else when automatic messages are turned off for everyone (status.kill_switch) - a reply someone writes under another comment is a comment too, and sets off a trigger the same way - when your own automated-message notice is too long to fit after a trigger's message, iris sends its standard notice in its place. the message itself is never cut - each DM sent counts as a message against your plan and shares your instagram account's send pacing with every other DM iris sends for you. a comment gets no DM when it arrives while that pace or your plan's message allowance is reached, or when instagram refuses or fails the send. iris does not try the same comment again - a comment by the account itself never sets off a trigger #### POST /responder/comment-triggers create a comment trigger **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | keyword | string (1-50) | yes | the word or phrase that sets the trigger off. matched as a whole word, case-insensitive: guide matches "GUIDE please" and not "guidelines" | | message | string (max 900, and 700 bytes) | yes | the DM to send, as written. instagram counts bytes, and an emoji is up to 4. the automated-message notice is added after it | | media_id | string | null | no | limit the trigger to one post: its instagram media id, from GET /responder/posts. null or omitted applies it to every post. when both match a comment, the trigger for the post wins | | enabled | boolean | no | false saves the trigger without sending (default: true) | **response (201):** ```json { "success": true, "data": { "id": "uuid", "keyword": "guide", "message": "thanks for asking! here is the guide: https://example.com/guide", "media_id": null, "enabled": true, "sent_count": 0, "last_sent_at": null, "created_at": "2026-09-28T00:00:00Z", "updated_at": "2026-09-28T00:00:00Z" } } ``` **errors:** - 400 SERVER_002: a keyword or a message that is only spaces, a message over 700 bytes, a media_id that is not a numeric instagram media id, or 20 triggers already saved - 403 BILLING_011: comment triggers are not available on this account yet - 409 SERVER_016: a trigger for that keyword on that post already exists - 422 SERVER_005: keyword or message missing, a field of the wrong type, a keyword over 50 characters, or a message over 900 - 429 RATE_001: rate limit exceeded (20 changes per minute) #### PATCH /responder/comment-triggers/:id update a comment trigger. only the fields you send change. sending enabled: false alone works even when comment triggers are no longer offered on the account **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | id | uuid | yes | comment trigger id | **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | keyword | string (1-50) | no | the word or phrase | | message | string (max 900, and 700 bytes) | no | the DM to send | | media_id | string | null | no | an instagram media id from GET /responder/posts, or null for every post | | enabled | boolean | no | false stops the trigger from sending | **response (200):** ```json { "success": true, "data": { "id": "uuid", "keyword": "guide", "message": "thanks for asking! here is the guide: https://example.com/guide", "media_id": "17912345678901234", "enabled": false, "sent_count": 31, "last_sent_at": "2026-09-28T17:41:20Z", "created_at": "2026-09-20T00:00:00Z", "updated_at": "2026-09-28T18:00:00Z" } } ``` **errors:** - 400 SERVER_002: a value that breaks a rule listed under POST - 403 BILLING_011: comment triggers are not available on this account yet (not returned for a body of enabled: false alone) - 404 SERVER_003: comment trigger not found - 409 SERVER_016: a trigger for that keyword on that post already exists - 422 SERVER_005: a field of the wrong type or past its limit, or an id that is not a uuid - 429 RATE_001: rate limit exceeded (20 changes per minute) #### DELETE /responder/comment-triggers/:id delete a comment trigger. DMs it already sent stay in the inbox. works even when comment triggers are no longer offered on the account **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | id | uuid | yes | comment trigger id | **response:** 204 no content **errors:** - 404 SERVER_003: comment trigger not found - 422 SERVER_005: the id is not a uuid - 429 RATE_001: rate limit exceeded (20 changes per minute) #### GET /responder/posts list the account's 25 newest instagram posts with their media ids, for limiting a comment trigger to one post **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "17912345678901234", "caption": "5 things i wish i knew before my first client. comment GUIDE for the full list", "permalink": "https://www.instagram.com/p/DAbCdEfGhIj/", "media_type": "CAROUSEL_ALBUM", "posted_at": "2026-09-27T16:00:00.000Z" } ] } ``` **errors:** - 400 SERVER_002: no instagram account is connected - 403 BILLING_011: comment triggers are not available on this account yet - 429 RATE_001: rate limit exceeded (20 per minute) - 500 SERVER_001: instagram did not return the posts. try again **notes:** - read from instagram on every call. caption is the first 120 characters - media_type is instagram's own value: IMAGE, VIDEO, or CAROUSEL_ALBUM ### channels manage connected accounts and multi-channel messaging. #### POST /channels/accounts/:channel/connect start an OAuth connect for a channel. returns the URL to send the user to, plus the `state` that identifies the flow on return. **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | channel | string | yes | one of: twitter, instagram | **response (200):** ```json { "success": true, "data": { "auth_url": "https://twitter.com/i/oauth2/authorize?...", "state": "opaque-flow-id" } } ``` **errors:** - 400 SERVER_002: unsupported or unconfigured channel #### DELETE /channels/accounts/:channel disconnect a channel and revoke its stored tokens **scope:** `write` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | channel | string | yes | one of: twitter, instagram | **response (200):** ```json { "success": true, "data": { "disconnected": true } } ``` **errors:** - 400 SERVER_002: unsupported channel #### GET /channels/accounts list connected social accounts **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "id": "uuid", "channel": "twitter", "platform_username": "@myaccount", "status": "active", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } ] } ``` #### GET /channels/availability per-channel availability with send mode: mode 'api' = deliverable via /channels/send when connected; mode 'manual' = tiktok's draft + mark-sent flow (no send API exists, never 'connected') **scope:** `read` **response (200):** ```json { "success": true, "data": [ { "channel": "email", "available": true, "connected": true }, { "channel": "twitter", "available": true, "connected": true }, { "channel": "instagram", "available": true, "connected": false } ] } ``` #### POST /channels/send send a message through a specific channel into an existing conversation **scope:** `send` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | channel | "email" | "twitter" | "instagram" | yes | outreach channel | | conversation_id | uuid | yes | ID of an existing conversation to send the message into | | recipient_id | uuid | yes | ID of the contact who will receive the message | | content | string | yes | message content (whitespace is trimmed) | | subject | string | no | subject line (email only - ignored for DM channels) | | variables | Record | no | key/value pairs substituted into the content template (e.g. {{first_name}}) | **errors:** - 404 CONVERSATION_001: conversation not found - 429 MESSAGE_015: message limit reached **notes:** - tiktok cannot be sent through this endpoint (no send API exists) - draft via campaigns or record via POST /conversations/:id/messages, and complete drafts with POST /messages/:id/mark-sent - prerequisites: the conversation must already exist - there is no API endpoint to create one ad hoc. conversations are created by the campaign-activation flow when contacts are added to an active campaign. for queued AI drafts use the message-approval flow (GET /messages/pending → POST /messages/:id/approve). - prerequisites: twitter and instagram require an OAuth-connected account on the user. connect via the iris dashboard at /settings/channels - there is no API for connecting social accounts. - check GET /channels/availability before sending to avoid silent failures on disconnected channels. - requires an API key with `send` scope. agents do not call this directly. message sends run as an internal step of POST /campaigns + the message approval flow. ### notifications manage user notifications. #### GET /notifications list notifications **scope:** `read` **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | | read | boolean | no | filter by read state (true/false) | | type | string | no | filter by notification type | #### PATCH /notifications/:id update a notification (e.g. mark as read) **scope:** `write` **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | read | boolean | yes | mark as read/unread | **errors:** - 404 NOTIFICATION_001: notification not found #### DELETE /notifications/:id delete a notification **scope:** `write` **response:** 204 no content **errors:** - 404 NOTIFICATION_001: notification not found #### POST /notifications/read-all mark all notifications as read **scope:** `write` **response (200):** ```json { "success": true, "data": { "updated_count": 12 } } ``` ### webhooks manage webhook endpoints for receiving real-time event notifications. all routes in this group require an API key with the `admin` scope (round-6 audit closed a privilege-escalation gap where a non-admin key could create or rotate webhooks). #### GET /webhooks list all webhook endpoints **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | #### POST /webhooks create a new webhook endpoint **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | url | url | yes | webhook endpoint URL (HTTPS) | | events | string[] | yes | event types to subscribe to (e.g. ["campaign.created", "contact.created"]). use ["*"] for all events | | description | string | no | optional description | **response (200):** ```json { "success": true, "data": { "id": "uuid", "user_id": "uuid", "url": "https://example.com/webhooks/iris", "events": ["campaign.created", "contact.created"], "description": "production events", "active": true, "secret": "whsec_a3f5b9c2d8e1f4a7b6c9d2e5f8a1b4c7d0e3f6a9b2c5d8e1f4a7b0c3d6e9f2a5", "created_at": "2024-01-15T10:30:00Z", "updated_at": "2024-01-15T10:30:00Z" } } ``` **errors:** - 409 SERVER_016: a webhook is already registered for this URL. update or delete it before re-creating. **notes:** - the signing secret is only returned on creation - store it securely - new secrets are prefixed `whsec_`. legacy bare-hex secrets created before the prefix was introduced still verify normally. the HMAC is computed over the stored value as-is. - each (user, url) pair is unique. a 409 means you already have a webhook at that url. PATCH /webhooks/:id to update it, or DELETE /webhooks/:id then re-create. #### GET /webhooks/:id get a specific webhook endpoint **errors:** - 404 WEBHOOK_001: webhook not found #### PATCH /webhooks/:id update a webhook endpoint **request body (JSON):** | name | type | required | description | |------|------|----------|-------------| | url | url | no | webhook endpoint URL (HTTPS) | | events | string[] | no | event types | | active | boolean | no | enable/disable | | description | string | no | description (max 500 chars) | **errors:** - 404 WEBHOOK_001: webhook not found #### DELETE /webhooks/:id delete a webhook endpoint **response:** 204 no content **errors:** - 404 WEBHOOK_001: webhook not found #### POST /webhooks/:id/test send a test event to a webhook endpoint **response (200):** ```json { "success": true, "data": { "success": true, "delivery_id": "uuid", "response_status": 200, "response_body": "OK" } } ``` **errors:** - 404 WEBHOOK_001: webhook not found #### GET /webhooks/:id/deliveries list recent webhook deliveries **query parameters:** | name | type | required | description | |------|------|----------|-------------| | page | integer | no | page number (default: 1) | | page_size | integer | no | items per page (default: 50) | **errors:** - 404 WEBHOOK_001: webhook not found #### POST /webhooks/:id/rotate-secret rotate the signing secret for a webhook. the new secret is returned once and the old secret is invalidated immediately. update HMAC verification on the receiver side before the next delivery, otherwise signature checks will fail. **response (200):** ```json { "success": true, "data": { "id": "uuid", "secret": "whsec_b7c4d1e8f2a5c9d6e3f0a7b4c1d8e5f2a9b6c3d0e7f4a1b8c5d2e9f6a3b0c7d4" } } ``` **errors:** - 404 WEBHOOK_001: webhook not found ### agent credits credit-based payments for AI agents using x402 (USDC on Base) or MPP (Stripe). 1 credit = 1 campaign (30 contacts, 240 messages, AI drafting bundled in). no subscription required. #### GET /agent/credits check the agent's current credit balance **response (200):** ```json { "success": true, "data": { "balance": 7, "identity_id": "uuid" } } ``` **notes:** - requires x402 or MPP identity header (no payment needed for balance check). - returns null balance for API key users (they don't use credits). #### POST /agent/credits purchase 5 credits with x402 or MPP payment **response (201):** ```json { "success": true, "data": { "balance": 5, "credits_added": 5, "pack": "pack_5" } } ``` **errors:** - 402 PAYMENT_001: payment required - $12.00 (MPP) for 5 credits. x402 agents: use per-campaign pricing at POST /campaigns. - 500 PAYMENT_007: purchase failed after payment (contact support) **notes:** - credit packs: 5 credits for $12.00 (MPP only). x402 agents pay per-campaign ($2.25) at POST /campaigns. - x402 agents can pay per-campaign ($2.25) by replaying POST /campaigns with a PAYMENT-SIGNATURE header (x402 v2). MPP agents must use packs. - credits never expire. send PAYMENT-SIGNATURE (x402 v2) or Authorization: Payment (MPP) header. ### changelog machine-readable release history - public, no API key required. #### GET /changelog release history newest-first: version, date, type (feature/fix/breaking/docs), summary, and migration notes on breaking entries. public - the one-line X-Notice header on every response is the latest entry's summary; this is the structured history behind it **response (200):** ```json { "success": true, "data": [ { "version": "1.0.0", "date": "2026-07-21", "type": "feature", "summary": "..." } ] } ``` ## MCP server the iris MCP server lets AI agents manage campaigns, contacts, conversations, messages, and more. ```bash npx -y -p @jclvsh/iris iris-mcp ``` the package ships two binaries: `iris-mcp` (the MCP server, shown above) and `iris` (a CLI for terminal use). set the IRIS_API_KEY environment variable to your API key. recommended scopes: read, write, generate, send (or pass ["*"] for full access). hosted endpoint for clients that connect to a remote MCP server: https://api.iris-ai.dev/mcp (MCP streamable HTTP, POST only, Authorization: Bearer is_live_...). initialize and tools/list answer without a key, so a client can read the tool list before signing up; calling a tool needs the key. it serves 81 of the 99 tools, each annotated read, write, or sensitive; credits, API key, webhook, affiliate, and recap tools are only in the npm package. the class of every hosted tool is listed at https://www.iris-ai.dev/docs#mcp-hosted. listed in the official MCP registry (registry.modelcontextprotocol.io) as io.github.JCLVSH/iris ## OpenAPI spec OpenAPI 3.1 spec available at: https://api.iris-ai.dev/openapi.json ## error codes all errors return: `{ success: false, error: { code, message } }` ### authentication | code | HTTP | description | |------|------|-------------| | AUTH_001 | 401 | unauthorized - invalid or missing API key | | AUTH_002 | 403 | forbidden - insufficient permissions | | AUTH_003 | 401 | session expired | ### API keys | code | HTTP | description | |------|------|-------------| | APIKEY_001 | 401 | invalid or missing API key | | APIKEY_002 | 401 | API key expired | | APIKEY_003 | 401 | API key revoked | | APIKEY_004 | 403 | scope not granted for this operation | | APIKEY_005 | 429 | API key creation limit reached | | APIKEY_006 | 404 | API key not found | ### campaigns | code | HTTP | description | |------|------|-------------| | CAMP_001 | 404 | campaign not found | | CAMP_002 | 500 | campaign creation failed | | CAMP_003 | 500 | campaign update failed | | CAMP_005 | 409 | campaign already active | | CAMP_007 | 400 | campaign has no contacts | | CAMP_008 | 400 | invalid campaign status transition | | CAMP_009 | 429 | campaign limit reached for billing period | ### contacts | code | HTTP | description | |------|------|-------------| | CONTACT_001 | 404 | contact not found | | CONTACT_003 | 400 | invalid email address | | CONTACT_007 | 500 | bulk import failed | | CONTACT_009 | 429 | contact limit reached for billing period | ### conversations | code | HTTP | description | |------|------|-------------| | CONVERSATION_001 | 404 | conversation not found | | CONVERSATION_002 | 500 | conversation update failed | | CONVERSATION_003 | 500 | message send failed | ### messages | code | HTTP | description | |------|------|-------------| | MESSAGE_001 | 500 | message send failed | | MESSAGE_004 | 409 | message already approved | | MESSAGE_005 | 404 | message not found | | MESSAGE_015 | 429 | message limit reached for billing period | ### AI | code | HTTP | description | |------|------|-------------| | AI_001 | 503 | AI service unavailable | | AI_002 | 500 | AI generation failed | | AI_003 | 500 | AI analysis failed | | AI_004 | 429 | AI rate limit exceeded | | AI_005 | 400 | AI content filtered | ### discovery | code | HTTP | description | |------|------|-------------| | DISCOVERY_001 | 500 | discovery job failed | | DISCOVERY_002 | 404 | discovery job not found | | DISCOVERY_006 | 429 | discovery rate limited | | DISCOVERY_008 | 429 | discovery quota exceeded | ### webhooks | code | HTTP | description | |------|------|-------------| | HOOK_001 | 400 | invalid webhook signature | | HOOK_003 | 400 | invalid webhook payload | | WEBHOOK_001 | 404 | webhook not found | ### agent payments | code | HTTP | description | |------|------|-------------| | PAYMENT_001 | 402 | payment required: agent must send PAYMENT-SIGNATURE (x402 v2) or Authorization: Payment (MPP) header | | PAYMENT_002 | 402 | x402 payment verification failed | | PAYMENT_003 | 402 | MPP credential verification failed | | PAYMENT_004 | 500 | settlement failed after payment was charged. contact support | | PAYMENT_005 | 402 | insufficient credit balance: purchase a credit pack via POST /agent/credits | | PAYMENT_006 | 400 | invalid credit pack id | | PAYMENT_007 | 500 | credit purchase failed. if payment was charged, contact support | ### billing | code | HTTP | description | |------|------|-------------| | BILLING_004 | 402 | payment failed (Stripe charge declined) | | BILLING_010 | 429 | plan usage limit reached: upgrade to continue (alias of BILLING_USAGE_EXCEEDED) | | BILLING_011 | 402 | active subscription required for this operation | ### rate limiting | code | HTTP | description | |------|------|-------------| | RATE_001 | 429 | too many requests | | RATE_002 | 429 | API rate limit exceeded | ### server | code | HTTP | description | |------|------|-------------| | SERVER_001 | 500 | internal server error | | SERVER_002 | 400 | request validation failed (also returned for invalid Idempotency-Key) | | SERVER_003 | 404 | resource not found | | SERVER_004 | 405 | method not allowed | | SERVER_005 | 422 | invalid input (validation failed) | | SERVER_006 | 500 | database error | | SERVER_008 | 504 | request timeout | | SERVER_009 | 503 | service temporarily unavailable | | SERVER_016 | 409 | conflict: concurrent retry with same Idempotency-Key in flight |