API Reference

Integrate Iris into your applications with our REST API

API Overview

The Iris API is a RESTful JSON API hosted at api.irisvision.ai. It allows you to programmatically create conversations, send messages to AI agents, trigger tool executions, and retrieve results -- all from your own applications.

All requests and responses use JSON format. Authentication is handled via API keys passed as Bearer tokens. The API follows standard HTTP conventions with appropriate status codes for success, validation errors, and server errors.

Base URL: https://api.irisvision.ai/v1

Content-Type: application/json
Accept: application/json

Authentication

All API requests require a valid API key passed in the Authorization header as a Bearer token.

To obtain your API key, navigate to the Settings > API Keys section in your Iris dashboard. You can create multiple keys for different environments and revoke them at any time.

Example Header

Authorization: Bearer iris_sk_your_api_key_here

Keep your API keys secure. Do not expose them in client-side code, public repositories, or logs. If a key is compromised, revoke it immediately from the dashboard and generate a new one.

Core Endpoints

These endpoints form the foundation of the Iris API, allowing you to manage conversations and exchange messages with AI agents.

Create Conversation

Start a new conversation with an Iris agent. You can optionally specify which model and tools the agent should have access to.

POST /v1/conversations

{
  "title": "Market Research Q1",
  "model": "claude-3-opus",
  "tools": ["web_search", "document_gen"],
  "metadata": {
    "project": "growth-strategy"
  }
}

Response:

{
  "id": "conv_a1b2c3d4e5f6",
  "title": "Market Research Q1",
  "model": "claude-3-opus",
  "tools": ["web_search", "document_gen"],
  "created_at": "2025-01-15T10:30:00Z",
  "status": "active"
}

Send Message

Send a message to an existing conversation. The agent will process your message, optionally invoke tools, and return a response. Use the stream parameter for real-time streaming responses.

POST /v1/conversations/{conversation_id}/messages

{
  "content": "Research the top 5 competitors in the AI agent space and summarize their key features.",
  "stream": false,
  "attachments": []
}

Response:

{
  "id": "msg_x9y8z7w6v5",
  "conversation_id": "conv_a1b2c3d4e5f6",
  "role": "assistant",
  "content": "Here are the top 5 competitors in the AI agent space...",
  "tools_used": ["web_search"],
  "tokens": {
    "input": 145,
    "output": 1230
  },
  "created_at": "2025-01-15T10:31:12Z"
}

Get Conversation

Retrieve the full history of a conversation, including all messages, tool invocations, and metadata.

GET /v1/conversations/{conversation_id}

Response:

{
  "id": "conv_a1b2c3d4e5f6",
  "title": "Market Research Q1",
  "model": "claude-3-opus",
  "status": "active",
  "messages": [
    {
      "id": "msg_u1t2s3r4q5",
      "role": "user",
      "content": "Research the top 5 competitors...",
      "created_at": "2025-01-15T10:30:45Z"
    },
    {
      "id": "msg_x9y8z7w6v5",
      "role": "assistant",
      "content": "Here are the top 5 competitors...",
      "tools_used": ["web_search"],
      "created_at": "2025-01-15T10:31:12Z"
    }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:31:12Z"
}

List Conversations

Retrieve a paginated list of all conversations in your account. Use query parameters to filter by status, date range, or search by title.

GET /v1/conversations?limit=20&offset=0&status=active

Response:

{
  "data": [
    {
      "id": "conv_a1b2c3d4e5f6",
      "title": "Market Research Q1",
      "model": "claude-3-opus",
      "status": "active",
      "message_count": 12,
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T14:22:00Z"
    }
  ],
  "total": 47,
  "limit": 20,
  "offset": 0
}

Tool Endpoints

Tool endpoints allow you to trigger specific Iris capabilities directly, without going through the conversational interface. These are ideal for automation workflows and batch processing.

Research

Trigger a deep research task. Iris will search the web, synthesize sources, and return a structured research report with citations.

POST /v1/tools/research

{
  "query": "Latest trends in autonomous AI agents for enterprise",
  "depth": "comprehensive",
  "max_sources": 15,
  "output_format": "structured"
}

Response:

{
  "id": "task_r1e2s3e4a5",
  "status": "completed",
  "result": {
    "summary": "The autonomous AI agent market is rapidly evolving...",
    "sections": [...],
    "sources": [
      {
        "title": "Enterprise AI Agents Report 2025",
        "url": "https://example.com/report",
        "relevance": 0.95
      }
    ]
  },
  "tokens_used": 8450,
  "created_at": "2025-01-15T11:00:00Z"
}

Generate Document

Generate a formatted document (PDF, DOCX, or Markdown) from a prompt or existing data. Supports custom templates, styling, and automatic table of contents.

POST /v1/tools/document

{
  "prompt": "Write a quarterly business review for Q4 2024",
  "format": "pdf",
  "template": "business-report",
  "include_toc": true,
  "data": {
    "revenue": "$2.4M",
    "growth": "18%"
  }
}

Response:

{
  "id": "task_d1o2c3u4m5",
  "status": "completed",
  "result": {
    "file_url": "https://api.irisvision.ai/v1/files/doc_abc123.pdf",
    "format": "pdf",
    "pages": 12,
    "word_count": 3400
  },
  "tokens_used": 5200,
  "created_at": "2025-01-15T11:15:00Z"
}

Generate Presentation

Auto-generate slide decks from a topic, outline, or data. Iris creates visually polished presentations with proper layout, charts, and speaker notes.

POST /v1/tools/presentation

{
  "topic": "AI Agent Platform Overview for Investors",
  "slide_count": 15,
  "style": "modern-dark",
  "include_speaker_notes": true,
  "sections": [
    "Market Opportunity",
    "Product Demo",
    "Business Model",
    "Team"
  ]
}

Response:

{
  "id": "task_p1r2e3s4e5",
  "status": "completed",
  "result": {
    "file_url": "https://api.irisvision.ai/v1/files/pres_xyz789.pptx",
    "slide_count": 15,
    "thumbnail_url": "https://api.irisvision.ai/v1/files/pres_xyz789_thumb.png"
  },
  "tokens_used": 6800,
  "created_at": "2025-01-15T11:30:00Z"
}

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Iris account. Configure webhook URLs in your dashboard under Settings > Webhooks.

Iris sends a POST request to your configured URL with a JSON payload for each event. All webhook payloads include a signature header for verification.

Supported Events

task.completed -- Fired when an async tool task (research, document generation, etc.) finishes successfully.
task.failed -- Fired when a task encounters an unrecoverable error.
conversation.message -- Fired when a new assistant message is added to a conversation.
usage.threshold -- Fired when your usage reaches a configured spending threshold.

Example Payload

POST https://your-app.com/webhooks/iris

Headers:
  X-Iris-Signature: sha256=a1b2c3d4...
  Content-Type: application/json

{
  "event": "task.completed",
  "timestamp": "2025-01-15T11:35:00Z",
  "data": {
    "task_id": "task_r1e2s3e4a5",
    "type": "research",
    "status": "completed",
    "result_url": "https://api.irisvision.ai/v1/tasks/task_r1e2s3e4a5"
  }
}

Rate Limits

The Iris API enforces rate limits to ensure fair usage and platform stability. Limits are applied per API key and vary by plan.

Plan	Rate Limit	Burst
Free	100 requests/min	150 requests
Pro	1,000 requests/min	1,500 requests
Enterprise	Custom	Custom

When you exceed the rate limit, the API returns a 429 Too Many Requests status code with a Retry-After header indicating when you can retry.

Python SDK

For Python developers, the official Iris SDK provides a convenient wrapper around the REST API with type hints, automatic retries, and streaming support.

Installation

pip install iris-sdk

Basic Usage

from iris_sdk import IrisClient

# Initialize the client
client = IrisClient(api_key="iris_sk_your_api_key_here")

# Create a conversation
conversation = client.conversations.create(
    title="Research Task",
    model="claude-3-opus"
)

# Send a message
response = client.messages.send(
    conversation_id=conversation.id,
    content="What are the latest trends in AI agents?"
)

print(response.content)

# Stream a response
for chunk in client.messages.stream(
    conversation_id=conversation.id,
    content="Write a detailed report on this topic."
):
    print(chunk.text, end="", flush=True)

# Trigger a research task
research = client.tools.research(
    query="Enterprise AI adoption rates 2025",
    depth="comprehensive"
)

print(research.result.summary)

For comprehensive SDK documentation, including advanced configuration, error handling, and async support, see the SDK Reference.