iris API v1

getting started

create an API key

go to settings → API keys in your iris dashboard and click create key. give it a name and pick scopes, then copy the key immediately - it is shown only once.

base URL

make your first request

curl https://api.iris-ai.dev/campaigns \
  -H "Authorization: Bearer is_live_YOUR_KEY"

quick example

create a campaign, discover contacts, check connected channels, and send a message - the minimum end-to-end flow.

step 1 - create a campaign

curl -X POST https://api.iris-ai.dev/campaigns \
  -H "Authorization: Bearer is_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "April DJ outreach - Brooklyn",
    "objective_type": "venue_dj",
    "location": "Brooklyn, NY",
    "radius_miles": 10,
    "venue_types": ["bar", "club", "lounge"],
    "keywords": ["live music", "dj nights"],
    "max_results": 50,
    "outreach_channels": ["email", "instagram", "twitter"],
    "followup_days": [3, 7, 14],
    "status": "draft"
  }'
# response: { "success": true, "data": { "id": "<campaign_id>", ... } }

step 2 - discover contacts (synchronous)

curl -X POST https://api.iris-ai.dev/discovery/search \
  -H "Authorization: Bearer is_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["bar", "lounge"],
    "location": "Brooklyn, NY",
    "radius_miles": 10,
    "max_results": 50,
    "campaign_id": "<campaign_id>",
    "enrich_emails": true
  }'
# returns synchronously - { "data": { "contacts": [...], "total_results": 50, ... } }

step 3 - check connected channels

curl https://api.iris-ai.dev/channels/availability \
  -H "Authorization: Bearer is_live_YOUR_KEY"
# email is always available; twitter and instagram require an OAuth-connected account

step 4 - send a message (or approve a draft)

# direct send to an existing conversation:
curl -X POST https://api.iris-ai.dev/channels/send \
  -H "Authorization: Bearer is_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "conversation_id": "<conversation_id>",
    "recipient_id": "<contact_id>",
    "subject": "quick question about djing at {{venue}}",
    "content": "hi {{first_name}}, ...",
    "variables": { "first_name": "Alex", "venue": "The Bell House" }
  }'

# OR - list AI-drafted messages waiting for approval and approve one:
curl "https://api.iris-ai.dev/messages/pending?campaign_id=<campaign_id>" \
  -H "Authorization: Bearer is_live_YOUR_KEY"

curl -X POST https://api.iris-ai.dev/messages/<id>/approve \
  -H "Authorization: Bearer is_live_YOUR_KEY"

authentication & rate limits

authentication methods

the iris API accepts three authentication headers. send any one - the API tries them in order:

bearer token format

invalid or revoked keys return 401 with error code APIKEY_001. missing scope returns 403 with APIKEY_004.

rate limits

when rate-limited you receive a 429 response with a Retry-After header (seconds):

{
  "success": false,
  "error": {
    "code": "RATE_001",
    "message": "too many requests. please try again in 12 seconds.",
    "requestId": "req_abc123"
  },
  "retryAfter": 12,
  "limit": 60,
  "remaining": 0
}

response headers

X-Request-ID is set on every response. The X-RateLimit-* headers are set on 429 rate-limited responses, alongside Retry-After.

scopes

API keys can be created with specific scopes to limit their permissions. defense-in-depth - even if a key is compromised, it can only perform operations within its granted scopes. use * for full access on trusted integrations.

available scopes

missing scope error

requests without the required scope receive a 403 response:

{
  "success": false,
  "error": {
    "code": "APIKEY_004",
    "message": "API key missing required scope: write",
    "requestId": "req_abc123"
  }
}

recommended scopes by use case

audit logging

destructive and sensitive operations performed via the API are automatically written to api_audit_log with the API key ID, user ID, action, resource ID, and a metadata JSON blob.

audited operations

idempotency

mutating endpoints (POST /campaigns, POST /agent/credits) accept an Idempotency-Key request header. on a timed-out network retry, the second call with the same key returns the cached response without re-executing — critical for agent-pay endpoints where re-execution would double-charge USDC or double-charge a Stripe credit pack.

idempotency is opt-in: requests without the header execute fresh. cached responses ship for 24 hours and only 2xx outcomes are cached (errors re-execute on retry).

curl -X POST https://api.iris-ai.dev/campaigns \
  -H "Authorization: Bearer is_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-12345" \
  -d '{"name": "Q2 outreach", "objective_type": "product_promotion"}'

key requirements

• 1–255 characters, allowlist [A-Za-z0-9._-]
• scoped per-(api-key, endpoint) — same key value across different endpoints is safe
• invalid keys (too long, bad chars) → 400 SERVER_BAD_REQUEST (don't retry — fix the value)
• concurrent retry while first call still in-flight → 409 SERVER_CONFLICT with Retry-After: 1

replay detection

replayed responses carry the Idempotent-Replayed: true response header so the client can distinguish a fresh execution from a cached replay.

MCP server

the model context protocol (MCP) lets AI agents interact with external tools. the iris MCP server gives agents like Claude Code and Cursor the ability to manage campaigns, contacts, conversations, messages, AI drafting, discovery, channels, webhooks, and more - 66 tools across 13 categories, all from your editor.

install

npx -y -p @jclvsh/iris iris-mcp

the package ships two binaries - iris-mcp (MCP server, used below) and iris (CLI).

Claude Code

{
  "mcpServers": {
    "iris": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@jclvsh/iris",
        "iris-mcp"
      ],
      "env": {
        "IRIS_API_KEY": "is_live_YOUR_API_KEY"
      }
    }
  }
}

add to .claude/settings.json

Cursor

{
  "mcpServers": {
    "iris": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@jclvsh/iris",
        "iris-mcp"
      ],
      "env": {
        "IRIS_API_KEY": "is_live_YOUR_API_KEY"
      }
    }
  }
}

add to .cursor/mcp.json

available tools

for machine-readable API references, see api.iris-ai.dev/llms.txt (plain text for LLMs) and api.iris-ai.dev/openapi.json (OpenAPI 3.1 spec).

CLI

the iris CLI lets you manage campaigns, contacts, messages, and more from your terminal. same API and same shape as the MCP server - just a different interface.

install

npm install -g @jclvsh/iris

or run directly with npx: npx @jclvsh/iris campaigns list

commands

70 total commands.

examples

# list your campaigns
iris campaigns list

# create a campaign
iris campaigns create --name "Q2 outreach" --objective product_promotion

# discover contacts and add to a campaign
iris discovery search --keywords "coffee shop" --location "Brooklyn, NY" --campaign <id>

# review pending message drafts
iris messages pending --campaign <id>

# approve a draft
iris messages approve <message-id>

# check your API key
iris keys me

# table output
iris --format table campaigns list

run iris --help or iris campaigns --help for the full command reference.

API reference

all endpoints are relative to https://api.iris-ai.dev. send Authorization: Bearer is_live_… on every request. responses follow the shape { success, data, meta? } on success and { success: false, error: { code, message, requestId } } on error.

authentication

verify your API key and view its metadata.

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.

campaigns

create and manage outreach campaigns.

contacts

manage contacts and import leads.

conversations

manage conversations across all channels.

messages

manage message approval workflow and sending.

AI

AI-powered content generation and analysis.

discovery

search for and discover new contacts.

analytics

campaign performance metrics and reporting.

billing

view billing plans and subscription information.

channels

manage connected accounts and multi-channel messaging.

notifications

manage user notifications.

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).

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.

webhook delivery

register a webhook via POST /webhooks with an HTTPS URL and an event filter. iris signs every delivery with HMAC-SHA256 using the secret returned at creation.

event types

payload format

every delivery wraps the event-specific data in an envelope:

{
  "id": "evt_a1b2c3d4e5f6...",
  "event": "campaign.created",
  "timestamp": "2026-04-29T12:00:00.000Z",
  "created_at": "2026-04-29T12:00:00.000Z",
  "data": { "id": "uuid", "name": "Q2 outreach", "status": "draft", "objective_type": "product_promotion" }
}

headers

signature verification

verify the X-Iris-Signature header using your webhook secret to ensure the request is from iris:

import crypto from "node:crypto";

// in your webhook handler
export async function POST(request: Request) {
  const signature = request.headers.get("x-iris-signature");
  const timestamp = request.headers.get("x-iris-timestamp");
  const body = await request.text();

  // reconstruct the signed payload
  const signed = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", process.env.IRIS_WEBHOOK_SECRET)
    .update(signed)
    .digest("hex");

  // timing-safe compare
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return new Response("invalid signature", { status: 401 });
  }

  const event = JSON.parse(body);
  // dispatch on event.event - "campaign.created", "message.delivered",
  // "conversation.reply_received", etc. (full list at /docs/api#webhooks)
  return new Response("ok");
}

retry behavior

• up to 3 retries with exponential backoff (via QStash)
• 30-second timeout per delivery attempt
• return 2xx to acknowledge - any other status code triggers retry
• use the X-Iris-Delivery header as an idempotency key to avoid processing the same event twice

agent payments

autonomous AI agents can use the iris API without an account or subscription via two payment protocols: x402 (crypto, USDC on Base) and MPP (Stripe via the Machine Payments Protocol).

how it works

• •each campaign creation costs $2.25 via x402 (USDC) or 1 credit via MPP ($2.40 effective from a 5-credit pack)
• •discovery, AI drafting, and message sends run automatically inside the campaign workflow as internal jobs (30 contacts, 240 messages allotment) — agents never call /discovery/search, /ai/generate, or /channels/send directly
• •payment proofs identify the agent - settlement only occurs on the campaign-creation request
• •agent-created campaigns are owned by an internal system user and can only be operated on by the agent identity

protocols

supported endpoints

these are the only two endpoints that accept agent auth (x402 / MPP). discovery, AI drafting, and message sends are not separately callable — they run automatically inside the campaign workflow as internal QStash jobs. all other endpoints (reads, listings, analytics, webhooks, keys, plus /discovery/search, /ai/generate, /channels/send) require an API key — no agent auth path. issue a key from /settings/api.

example flow

1. request with no payment proof

curl -X POST https://api.iris-ai.dev/campaigns \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 outreach",
    "objective_type": "product_promotion",
    "outreach_channels": ["email"]
  }'

2. 402 response (includes both challenges)

the body contains both x402 and mpp challenge objects, plus a credits alternative for MPP agents.

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64-encoded x402 v2 envelope>
WWW-Authenticate: Payment realm="www.iris-ai.dev", challenge_id="...", price_cents=240, ...
Access-Control-Expose-Headers: PAYMENT-REQUIRED, PAYMENT-RESPONSE, X-PAYMENT-RESPONSE, WWW-Authenticate

{
  "error": {
    "code": "PAYMENT_001",
    "message": "payment required: $2.25 USDC (x402) or $2.40 via Stripe (MPP)"
  },
  "x402": {
    "version": 2,
    "scheme": "exact",
    "network": "eip155:8453",
    "asset": "USDC",
    "amount": "2.25",
    "receiver": "0x...",
    "resource": "POST /campaigns"
  },
  "mpp": {
    "version": 1,
    "method": "stripe",
    "intent": "charge",
    "currency": "usd",
    "amount_cents": 240,
    "resource": "POST /campaigns"
  },
  "credits": {
    "purchase_endpoint": "POST /agent/credits",
    "packs": [{ "id": "pack_5", "credits": 5, "price_usd": "12.00" }]
  }
}

3a. pay with x402 (per-campaign USDC)

curl -X POST https://api.iris-ai.dev/campaigns \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded EIP-3009 signed payload>" \
  -d '{
    "name": "Q2 outreach",
    "objective_type": "product_promotion",
    "outreach_channels": ["email"]
  }'

3b. pay with MPP (deduct from credit pack)

curl -X POST https://api.iris-ai.dev/campaigns \
  -H "Content-Type: application/json" \
  -H "Authorization: Payment <base64url-encoded mppx credential>" \
  -d '{
    "name": "Q2 outreach",
    "objective_type": "product_promotion",
    "outreach_channels": ["email"]
  }'

credit packs

MPP (Stripe) agents purchase credit packs to prepay for campaigns in bulk. instead of paying per-campaign individually, buy 5 credits for $12.00 in a single Stripe charge. credits are deducted automatically when creating campaigns - no payment credential needed for each request after purchase.

pricing

how it works

• check balance - GET /agent/credits returns your current credit balance and the available pack.
• purchase - POST /agent/credits with an MPP credential for $12.00 adds 5 credits.
• auto-deduction - when you create a campaign with credits available, 1 credit is deducted instead of charging Stripe again.
• out of credits - if credits run out, the next campaign returns 402 with purchase instructions. buy another pack to continue.
• refunds - if campaign creation fails after credit deduction, the credit is refunded automatically.
• no expiration - credits never expire.

purchase example

send an MPP credential for $12.00 (1200 cents) to the purchase endpoint:

curl -X POST https://api.iris-ai.dev/agent/credits \
  -H "Content-Type: application/json" \
  -H "Authorization: Payment <base64url-credential-for-1200-cents>" \
  -d '{ "pack": "pack_5" }'

# response:
# {
#   "success": true,
#   "data": {
#     "balance": 5,
#     "credits_added": 5,
#     "pack": "pack_5"
#   }
# }

check balance

curl https://api.iris-ai.dev/agent/credits \
  -H "Authorization: Payment <base64url-credential>"

# response:
# {
#   "success": true,
#   "data": {
#     "balance": 3,
#     "identity_id": "uuid"
#   }
# }

error handling

error response shape

every error response includes a stable code, a human-readable message, and a requestId for support correlation:

{
  "success": false,
  "error": {
    "code": "CAMP_001",
    "message": "campaign not found",
    "requestId": "req_a1b2c3d4"
  }
}

error codes

every response includes an X-Request-ID header and a requestId field on errors - quote it when filing a support ticket.