IrisOS API

Authentication

The IrisOS API uses API keys for authentication. You can obtain an API key from your account dashboard. Include your API key in the Authorization header of your requests:

Authorization: Bearer your_api_key

Important: Keep your API key secure and never expose it in client-side code.

Endpoints

The IrisOS API provides the following main endpoints:

Create Agent

Create a new AI agent with specific capabilities and configurations.

POST /agents

Request Body

{
  "name": "research_assistant",
  "description": "Agent for web research tasks",
  "capabilities": ["web_browsing", "content_extraction"],
  "settings": {
    "max_runtime": 300,
    "allowed_domains": ["example.com", "wikipedia.org"],
    "webhook_url": "https://your-app.com/webhooks/irisagent"
  }
}

Response

{
  "id": "agt_123456789",
  "name": "research_assistant",
  "description": "Agent for web research tasks",
  "capabilities": ["web_browsing", "content_extraction"],
  "settings": {
    "max_runtime": 300,
    "allowed_domains": ["example.com", "wikipedia.org"],
    "webhook_url": "https://your-app.com/webhooks/irisagent"
  },
  "created_at": "2025-04-03T12:00:00Z",
  "status": "active"
}

Run Agent

Create a task for an agent to perform.

POST /agents/:agent_id/run

Request Body

{
  "message": "Find the latest research papers on artificial intelligence from the past month",
  "context": {
    "source": "user_request",
    "priority": "normal"
  },
  "parameters": {
    "max_results": 5,
    "include_summaries": true
  }
}

Response

{
  "task_id": "tsk_987654321",
  "agent_id": "agt_123456789",
  "status": "pending",
  "created_at": "2025-04-03T12:05:00Z",
  "estimated_completion": "2025-04-03T12:10:00Z"
}

Webhooks

IrisOS can send webhook notifications when tasks are completed or when certain events occur. Configure a webhook URL in your agent settings or when creating a task.

Example Webhook Payload

{
  "event_type": "task.completed",
  "task_id": "tsk_987654321",
  "agent_id": "agt_123456789",
  "status": "completed",
  "result": {
    "papers": [
      {
        "title": "Advances in Neural Networks for Language Processing",
        "authors": ["Smith, J.", "Johnson, K."],
        "publication": "AI Journal",
        "date": "2025-03-15",
        "url": "https://example.com/paper1",
        "summary": "This paper discusses recent advancements in neural network architectures for natural language processing tasks."
      },
      // Additional papers...
    ],
    "summary": "Recent research in AI has focused on improving neural network architectures for language processing, developing more efficient training methods, and exploring applications in healthcare and climate science."
  },
  "metrics": {
    "total_runtime": 242,
    "sites_visited": 8
  },
  "timestamp": "2025-04-03T12:09:12Z"
}

Code Examples

JavaScript

// Using fetch API
async function runAgent(agentId, message) {
  const response = await fetch("https://api.irisosai.com/v1/agents/${agentId}/run", {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_api_key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message,
      context: {
        source: 'user_request',
        priority: 'normal'
      }
    })
  });
  
  return await response.json();
}

// Example usage
runAgent('agt_123456789', 'Find information about renewable energy')
  .then(result => console.log(result))
  .catch(error => console.error(error));

Python

import requests

def run_agent(agent_id, message):
    url = f"https://api.irisosai.com/v1/agents/{agent_id}/run"
    headers = {
        "Authorization": "Bearer your_api_key",
        "Content-Type": "application/json"
    }
    payload = {
        "message": message,
        "context": {
            "source": "user_request",
            "priority": "normal"
        }
    }
    
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# Example usage
result = run_agent("agt_123456789", "Find information about renewable energy")
print(result)