Developer Guide

Overview

The Irora SEC API provides programmatic access to SEC filings, insider trading data, congressional trading disclosures, watchlists, alerts, and AI-powered search. It follows REST conventions with JSON request and response bodies, uses Bearer token authentication, and supports webhooks for real-time event delivery.

This guide covers everything you need to know to integrate Irora SEC into your application — from authentication and making your first request to webhook configuration, SDK usage, and error handling.

Base URL for all API requests:

Authentication

All API requests require authentication via an API key sent in theAuthorizationheader using the Bearer token scheme.

Authorization: Bearer sk_live_your_api_key

Creating API Keys

API keys are created from the Developer Dashboard in the Irora SEC web application. Navigate to Developer in the sidebar and click Create New Key. Give your key a descriptive name (e.g., "Production Server", "CI/CD Pipeline") for easy identification.

Key Types

• Live keys (prefix sk_live_) — For production use. All requests count against your rate limit and usage quota.
• Test keys (prefix sk_test_) — For development and testing. Returns mock data. Free and unlimited, with no impact on your production quota.

Making Requests

All endpoints accept and return JSON. Include theContent-Type: application/jsonheader on requests with a body (POST, PUT). GET requests use query parameters for filtering.

curl -X GET "https://api.irora.com/v1/filings?ticker=AAPL&formType=10-K&limit=5" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json"

POST Requests

For endpoints that accept a request body (like search), pass a JSON payload:

const response = await fetch("https://api.irora.com/v1/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.IRORA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "artificial intelligence risk factors",
    formTypes: ["10-K", "10-Q"],
    dateRange: { from: "2025-01-01", to: "2026-02-27" },
    limit: 10,
  }),
});

const results = await response.json();
console.log(results.results); // Array of search results with relevance scores

SDKs

Official client libraries are available for popular languages. All SDKs are open source and available on GitHub.

Install

npm install @irora-dev/sdk

JavaScript / TypeScript Usage

import { IroraSEC } from "@irora-dev/sdk";

const client = new IroraSEC({
  apiKey: process.env.IRORA_API_KEY,
});

// Search filings with AI
const results = await client.search({
  query: "artificial intelligence risk factors",
  formTypes: ["10-K"],
  limit: 10,
});

// Get insider trades
const trades = await client.insiderTrades.list({
  ticker: "NVDA",
  transactionType: "BUY",
});

// Subscribe to webhooks
await client.webhooks.create({
  url: "https://api.myapp.com/webhooks/irora",
  events: ["filing.new", "insider_trade.new"],
});

Python Usage

from irora import IroraSEC

client = IroraSEC(api_key=os.environ["IRORA_API_KEY"])

# Search filings
results = client.search(
    query="revenue recognition changes",
    form_types=["10-K", "10-Q"],
    limit=10,
)

# Get insider trades
trades = client.insider_trades.list(
    ticker="AAPL",
    transaction_type="BUY",
)

Try It

Test the API workflow below. Enter search parameters and see a simulated response to understand the data format before writing your integration code.

Webhooks

Webhooks allow your application to receive real-time notifications when events occur, rather than polling the API. Configure webhook endpoints from the Developer Dashboard and subscribe to specific event types.

Available Events

• filing.new — A new SEC filing matching your criteria is published
• filing.amended — An existing filing is amended or restated
• insider_trade.new — A new Form 4 insider transaction is detected
• alert.triggered — One of your custom alerts fires

Webhook Payload

{
  "event": "filing.new",
  "timestamp": "2026-02-27T14:23:07Z",
  "data": {
    "accession": "0000320193-26-000042",
    "formType": "10-K",
    "company": "Apple Inc",
    "ticker": "AAPL",
    "filedAt": "2026-02-27T14:20:00Z"
  },
  "webhook_id": "wh_abc123",
  "signature": "sha256=a1b2c3d4..."
}

Verifying Signatures

Every webhook delivery includes a signature computed using your webhook secret. Always verify the signature before processing the payload to ensure it was sent by Irora SEC and not a malicious third party.

import crypto from "crypto";

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expected}`)
  );
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. Error responses include a JSON body with an error code and human-readable message.

Error Response Format

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "status": 401,
    "requestId": "req_abc123xyz"
  }
}

Common Status Codes

• 200 — Success. The request was processed and data is returned.
• 201 — Created. A new resource was successfully created (e.g., new alert or webhook).
• 400 — Bad Request. The request parameters are invalid or missing required fields.
• 401 — Unauthorized. The API key is missing, invalid, or revoked.
• 403 — Forbidden. The API key does not have permission for this resource (plan limit exceeded).
• 404 — Not Found. The requested resource does not exist.
• 429 — Too Many Requests. Rate limit exceeded. Check the Retry-After header.
• 500 — Internal Server Error. An unexpected error occurred on our side.

Rate Limits

Rate limits are applied per API key on a rolling 24-hour window. The limits vary by plan tier:

Rate Limit Headers

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 8753
X-RateLimit-Reset: 1708876800
Retry-After: 3600  # Only present on 429 responses

When you receive a 429 response, wait for the number of seconds specified in theRetry-Afterheader before making another request. Implementing exponential backoff is recommended for production applications.

Frequently Asked Questions