Skip to main content

​
Overview

The Iris OSINT API provides programmatic access to powerful open-source intelligence gathering capabilities. All endpoints are built with Next.js API routes and support both JSON and Server-Sent Events (SSE) streaming for real-time progress updates.

​
Base URL

http://localhost:3000/api
For production deployments, replace with your deployment URL.

​
Authentication

The current API implementation does not require authentication. For production use, implement authentication middleware to secure your endpoints.
For production deployments, consider adding:
  • API Keys: Bearer token authentication
  • Rate Limiting: Prevent abuse with request throttling
  • CORS Configuration: Control which domains can access your API
// middleware.ts example
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const apiKey = request.headers.get('authorization');
  
  if (!apiKey || !apiKey.startsWith('Bearer ')) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }
  
  return NextResponse.next();
}

export const config = {
  matcher: '/api/:path*',
};

​
Response Formats

​
JSON Response

Standard endpoints return JSON with the following structure:
​
success
boolean
Indicates if the request was successful
​
error
string
Error message if the request failed (only present on errors)
{
  "success": true,
  "result": { ... }
}

​
Server-Sent Events (SSE)

Streaming endpoints (username search, domain analysis, company analysis) use SSE for real-time updates: 
const response = await fetch('/api/username/search', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ username: 'john_doe' })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      console.log(data.type, data.data);
    }
  }
}

​
SSE Event Types

{
  "type": "progress",
  "data": {
    "step": "Checking domain existence",
    "total": 8,
    "completed": 2
  }
}

​
Error Codes

​
400
Bad Request
Invalid request parameters or malformed input
​
500
Internal Server Error
Server-side error during processing

​
Error Response Format

{
  "success": false,
  "error": "Invalid email format"
}

​
Rate Limits

No rate limits are enforced by default. Implement rate limiting in production to prevent abuse.
  • Username Search: 10 requests per minute
  • Email Verification: 20 requests per minute
  • Domain Analysis: 5 requests per minute
  • Image Upload: 5 requests per minute (max 32MB)
  • Company Analysis: 5 requests per minute

​
Configuration

Some API endpoints require environment variables: 
# Image Upload
IMGBB_API_KEY=your_imgbb_api_key
MAX_IMAGE_SIZE=32000  # in KB
IMAGE_EXPIRY=600      # in seconds

# Email Verification
IPQUALITYSCORE_API_KEY=your_ipqs_api_key

# Company Analysis (UK)
COMPANIES_HOUSE_API_KEY=your_companies_house_key

​
Available Endpoints

Username Search

Search for username across OSINT sources

Email Verification

Verify email validity and check reputation

Image Analysis

Upload and extract EXIF metadata from images

Domain Analysis

Analyze domains with DNS, WHOIS, SSL, and more

Company Lookup

Search company registries and filings

​
SDK Support

No official SDK is currently available. Use standard HTTP clients like fetch, axios, or your language’s HTTP library.

​
Example: Node.js Client

const fetch = require('node-fetch');

class IrisClient {
  constructor(baseUrl = 'http://localhost:3000') {
    this.baseUrl = baseUrl;
  }

  async verifyEmail(email) {
    const response = await fetch(`${this.baseUrl}/api/email/verify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email })
    });
    return await response.json();
  }

  async analyzeDomain(domain, options = {}) {
    const response = await fetch(`${this.baseUrl}/api/domain/analyze`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ domain, options })
    });
    return response.body; // SSE stream
  }
}

module.exports = IrisClient;

​
Next Steps

Username Search

Start searching usernames across platforms

Email Verification

Verify email addresses and check risk scores

Build docs developers (and LLMs) love

Get started for freeTalk to us