Overview

Welcome to the IrisOS API documentation. This guide will help you get started with building and managing AI agents through our REST API.

Base URL

All API requests should be made to:

https://api.irisos.xyz/v1

Authentication

IrisOS uses API keys for authentication. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

1. Sign up at irisos.xyz

2. Navigate to Settings → API Keys

3. Generate a new API key

4. Store it securely (it won't be shown again)

Security Best Practices

• Never commit API keys to version control

• Use environment variables to store API keys

• Rotate keys regularly (every 90 days recommended)

• Use different keys for development and production

• Revoke unused keys immediately

API Endpoints

Agents

Manage your AI agents:

• Create Agent - POST /agents

• List Agents - GET /agents

• Get Agent - GET /agents/{agentId}

• Update Agent - PATCH /agents/{agentId}

• Delete Agent - DELETE /agents/{agentId}

• Send Message - POST /agents/{agentId}/messages

Characters

Manage agent character configurations (coming soon)

Conversations

Access conversation history and analytics (coming soon)

Plugins

Manage and configure plugins (coming soon)

Request Format

All POST and PATCH requests should include a JSON body with the Content-Type: application/json header:

curl -X POST https://api.irisos.xyz/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "MyAgent"}'

Response Format

All API responses follow this structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // Additional error details
    }
  }
}

HTTP Status Codes

Status Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Rate Limits

Default rate limits apply to all endpoints:

• Standard tier: 60 requests per minute

• Pro tier: 300 requests per minute

• Enterprise tier: Custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642089600

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 status code:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 30 seconds.",
    "details": {
      "retryAfter": 30
    }
  }
}

Implement exponential backoff:

const makeRequestWithRetry = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.response?.status === 429 && i < maxRetries - 1) {
        const retryAfter = error.response.data.error.details?.retryAfter || Math.pow(2, i);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      throw error;
    }
  }
};

Pagination

List endpoints support pagination:

GET /agents?page=1&limit=20

Response includes pagination metadata:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "currentPage": 1,
      "totalPages": 5,
      "totalItems": 95,
      "itemsPerPage": 20
    }
  }
}

Versioning

The API version is included in the URL path:

https://api.irisos.xyz/v1/agents

We maintain backward compatibility within major versions. Breaking changes will result in a new major version (v2, v3, etc.).

SDKs and Libraries

Official SDKs are available for popular languages:

• JavaScript/TypeScript: npm install @irisos/sdk

• Python: pip install irisos

• Go: go get github.com/IrisOS-xyz/irisos-go

• Ruby: gem install irisos

Quick Start with SDK

const { IrisOS } = require('@irisos/sdk');

const iris = new IrisOS({
  apiKey: process.env.IRIS_API_KEY
});

// Create an agent
const agent = await iris.agents.create({
  name: 'MyAgent',
  personality: {
    traits: ['helpful', 'friendly']
  }
});

// Send a message
const response = await iris.agents.sendMessage(agent.id, {
  text: 'Hello!',
  userId: 'user_123'
});

console.log(response.data.response);

Webhooks

Configure webhooks to receive real-time notifications about agent events (coming soon).

Error Codes

Common error codes you may encounter:

Code	Description
INVALID_REQUEST	Request parameters are invalid
UNAUTHORIZED	Invalid or missing API key
AGENT_NOT_FOUND	Requested agent doesn't exist
RATE_LIMIT_EXCEEDED	Too many requests
INSUFFICIENT_QUOTA	Account quota exceeded
AGENT_UNAVAILABLE	Agent is not responding
MODEL_ERROR	AI model provider error

See the Error Codes Reference for complete details.

Support

Need help?

• API Documentation

• Discord Community

• GitHub Issues

• Email: [email protected]

Changelog

Stay updated with API changes:

• API Changelog

• Release Notes