API Reference

Welcome to the API reference. This guide will help you understand how to use our API in simple terms. Every API request requires you to send your API key in the headers, using the x-api-key header.

Current API version: v1

Every endpoint is reached under /api/v1/.... This is the only version that has ever existed, there is nothing to migrate between yet. When a v2 ships, it will be announced here with a clear migration guide and advance notice well before v1 is ever deprecated.

Domain Path: The base URL for all API requests is https://portal.orenyxengine.com/api/v1. For example, to get your balance, you would make a request to https://portal.orenyxengine.com/api/v1/ledger/balance.
If you prefer machine-readable formats, you can view our interactive OpenAPI specification by visiting https://portal.orenyxengine.com/docs, or download the ready-to-import Postman collection covering every endpoint in this reference.

Try it out

You can paste your API key below to test a real request right from this page, including checking a bot's status or looking up a lead by ID. We never store your key!

Your key is sent server-side to your own API for this one request and never stored. Nothing here is persisted after you navigate away.

How to Authenticate

To authenticate, you must include your API key in the headers of your request. Here is an example of what that looks like in code.

Example: Fetching your Balance (cURL)

curl -X GET https://portal.orenyxengine.com/api/v1/ledger/balance \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json"

API Key Security Best Practices

Your API key gives full access to your Orenyx Engine data. Here are real-world ways you must secure it:

  • Never commit keys to code: Use Environment Variables (e.g., process.env.ORENYX_API_KEY). If you accidentally push a orx_live_ key to a public GitHub repository, our automated GitHub Secret Scanning webhook will detect it and instantly revoke the key before a malicious bot can steal it.
  • Use IP Allowlisting: When issuing a key, restrict it to the static IP address of your backend server. Even if a hacker steals the key, they cannot use it from their own computer.
  • Use Environment Tagging: Create separate keys for your local machine vs. your production server. Use a Test key for your staging environment to guarantee your testing scripts can never accidentally modify live customer data.
  • Limit Scopes: If an API key is only used by a background cron job to read balances, restrict its scope to only ledger. Do not give it unrestricted access.

Enterprise Compliance & Auditing

To ensure strict compliance and operational transparency, Orenyx Engine includes several enterprise-grade key management features:

  • Immutable Audit Logging: Every lifecycle event (creating, updating, rotating, or revoking a key) is permanently recorded in the system's Audit Log. You always have a forensic paper trail of exactly who touched a key and when.
  • Partial Key Masking: For security, we never store the raw API key. Instead, we display the prefix and the last 4 characters (e.g. orx_live_••••••••a1b2). This allows developers to safely cross-reference which keys are in use on which servers without exposing the secret itself.
  • "Last Used IP" Tracking: Every single time an API key is used, our gateway records the exact client IP address. You can instantly see the exact IP that last made a request from the developer dashboard, making unauthorized usage instantly obvious.

Real-World Scenario: Rotating a Key without Downtime

What happens if a developer leaves your company and you need to change your API keys? You cannot just delete the key, because your live application will immediately crash and throw 401 Unauthorized errors until you deploy the new key.

To solve this, use the Rotate Key feature in the dashboard. When you click Rotate:

  • You instantly receive a brand new API key.
  • The old API key is placed into a 24-hour Grace Period.
  • Your live app continues functioning perfectly using the old key.
  • You have exactly 24 hours to safely deploy the new key to your servers before the old key is permanently destroyed.

Example: Fetching your Balance (JavaScript/Node.js)

const response = await fetch("https://portal.orenyxengine.com/api/v1/ledger/balance", {
  method: "GET",
  headers: {
    "x-api-key": "your_api_key_here",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);

Available Resources & Endpoints

Here is a list of all the different areas of our API and the endpoints you can call. Some API keys might be restricted to only specific "Scopes".

ResourceWhat it doesEndpointsScope
LedgerCheck your balances and transaction history.GET /ledger/balance, /ledger/entries, /ledger/verifyledger
BillingManage invoices, alerts, and proration.GET /billing/invoice-preview, POST /billing/usage-alertsbilling
SettlementManage payouts and payment reconciliations.GET /settlement, POST /settlement/:id/retrysettlement
WebhooksManage where we send automated alerts.GET/POST /webhooks/subscriptions, PATCH /webhooks/subscriptions/:idwebhooks
API KeysManage other API keys programmatically.GET/POST /api-keys, PATCH/DELETE /api-keys/:idNone
BotsConfigure your automated bots.GET /bots, PUT /bots/:botKey/config, POST /bots/:botKey/pausebots
Feature FlagsCheck or toggle feature flags.GET /feature-flags, POST /feature-flags/:key/togglefeature-flags
LeadsIngest, look up, and manage sales leads.GET /leads, GET /leads/:id, POST /leads/bulk, DELETE /leads/:idleads
TriggersConfigure incoming event hooks, and capture leads.GET/POST /triggers, PATCH /triggers/:id, POST /triggers/leadtriggers
WorkflowsDefine and run multi-step automated processes.GET/POST /workflows, POST /workflows/:id/execute, GET /workflows/executions, POST /workflows/executions/:id/cancelworkflows
ContextA generic per-tenant key-value store for a bot, workflow, or integration to persist state between calls.GET /context, GET/PUT/DELETE /context/:keycontext

Context is scratch storage, not a modeled entity — store whatever JSON shape your integration needs under a key (letters, numbers, _, ., :, -, up to 200 characters), and read it back later. Each value is capped at 64KB; this is for small pieces of state (a workflow's running counters, an integration's last-synced cursor), not for storing files or large payloads.

A "workflow" is defined once (a sequence of steps) and can be triggered many times. Every trigger creates a tracked "execution" you can watch, and cancel mid-run if needed. See Workflow System for the full step-by-step walkthrough.

When you create an API key, you can lock it down so it only has access to specific scopes (like only billing). If you try to use a key for something it doesn't have access to, you will get a 403 Forbidden error.

Understanding Errors

If something goes wrong, we will tell you exactly why. If you send bad data, you will get a 400 error like this:

{
  "message": "Validation failed: 'name' is required",
  "error": "Bad Request",
  "statusCode": 400
}

Here is a cheat sheet of the error codes you might see and what they mean in simple terms:

Error CodeWhat it means
400Bad Request: You sent invalid data or missed a required field.
401Unauthorized: Your API key is missing, expired, or invalid.
403Forbidden: Your API key is valid, but it does not have permission.
404Not Found: The thing you are looking for does not exist.
429Too Many Requests: You are making too many requests too fast. Slow down!
500Server Error: Something broke on our end. Try again later.

Common API Key Issues

  • "API key has expired (MAE-4014)": Orenyx enforces a mandatory 90-day expiration on all keys. If your key hits day 90, it will stop working. We send automated warning emails to the bot owner 7 days before this happens so you can rotate the key.
  • "Caller IP is not on this API key's allowlist (MAE-4015)": You restricted the key to a specific IP, but the request came from somewhere else. Note: If your backend is behind a Load Balancer, ensure your server is configured to correctly forward the real client IP (e.g. trust proxy), otherwise Orenyx will see your load balancer's IP and block it.
  • "API key is not scoped for '...' (MAE-4013)": Your key was created with a restricted scope (like billing), but you tried to hit an endpoint that requires a different scope (like ledger).
  • "This product is temporarily suspended (MAE-4043)": Orenyx has paused access to the product your key belongs to, usually for maintenance or an account review. Your key, data and settings are untouched and nothing needs to change on your side: the same key works again as soon as access is restored, usually within a few seconds of it. Retry with a backoff rather than rotating the key, and check the status page or contact support if it lasts.

Rate Limits

To keep our systems fast for everyone, each API key has a speed limit. If you send too many requests in a short time, you will get a 429 Too Many Requests error. If this happens, just wait a few seconds and try again.

Safe Retries (Idempotency)

Sometimes the internet drops out and you aren't sure if your request went through. To prevent doing something twice by accident (like making two payments), you can send a unique ID in the Idempotency-Key header.

If you send the exact same request again with the exact same Idempotency-Key, we will just give you the original result instead of doing the action twice!

Enterprise Security Features

Orenyx is built for enterprise-grade security. Here are the key security features enabled on your account:

  • Application-Layer PII Encryption: All Personally Identifiable Information (PII) for your leads, such as phone numbers and messages, is encrypted using AES-256-GCM before being stored in our database. Even in the event of a raw database dump, your customer data remains secure.
  • Strict API Key Scopes & IP Allowlisting: You can lock down API keys to specific endpoints and exact IP addresses.

Webhook Signature Verification

To prevent spoofing attacks, we sign every outgoing webhook using HMAC-SHA256. You can verify that a webhook came from Orenyx by hashing the raw request body with your webhook secret and comparing it to the x-orenyx-signature header.

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hash = crypto.createHmac('sha256', secret)
                     .update(JSON.stringify(payload))
                     .digest('hex');
  return hash === signature;
}

Example: Safe Retry

curl -X POST https://portal.orenyxengine.com/api/v1/settlement/123/retry \
  -H "x-api-key: your_api_key_here" \
  -H "Idempotency-Key: my-unique-retry-id-456" \
  -H "Content-Type: application/json"

Example: Bulk Lead Ingestion

If you need to ingest a large historical list of leads, or you have thousands of leads from a CSV, you can bypass the standard per-request rate limit using the bulk endpoint. This pushes the leads directly to the Intake Bot for processing.

curl -X POST https://portal.orenyxengine.com/api/v1/leads/bulk \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      { 
        "email": "founder@startup.com", 
        "firstName": "Alice",
        "lastName": "Smith",
        "company": "Startup Inc.",
        "phone": "+1234567890",
        "role": "Founder",
        "budget": "50000",
        "message": "We need help scaling our automated workflows.",
        "source": "organic_search"
      },
      { 
        "email": "ceo@enterprise.com", 
        "firstName": "Bob" 
      }
    ]
  }'
Supported Fields: The email field is strictly required. You can optionally include firstName, lastName, company, phone, role, budget, message, source, and utmCampaign. Our Intake Bot will automatically parse these fields, securely encrypt any PII (like phone numbers and messages), and populate the Lead record! Any other custom fields sent will also be securely stored in the lead's raw data for future reference.

Example: Checking Bot Status

Every automated bot (Intake, Qualification, Scheduling, Payment, Support, Outreach, Follow-up) reports its own live status: whether it's running or paused, and how many jobs are waiting, active, completed, delayed, or failed in its queue.

# Status of every bot at once
curl https://portal.orenyxengine.com/api/v1/bots \
  -H "x-api-key: your_api_key_here"

# Status of a single bot
curl https://portal.orenyxengine.com/api/v1/bots/intake \
  -H "x-api-key: your_api_key_here"
Scope required: a key needs the bots scope for either of these calls. The response includes a queueStats object: { waiting, active, completed, failed, delayed, paused }.

Example: Looking Up a Single Lead

Once you know a lead's ID (returned when it's created, or from GET /leads), you can fetch its full record, including its BANT score breakdown, at any time.

curl https://portal.orenyxengine.com/api/v1/leads/cms6ea5ww0003fjb74eseuecc \
  -H "x-api-key: your_api_key_here"
Returns a 404 Not Found if the ID doesn't exist, or if it belongs to a different tenant than the one your API key is scoped to. One tenant can never read another tenant's lead by guessing an ID.

Example: Authenticated Lead Capture

POST /triggers/lead supports two ways of identifying which tenant a lead belongs to:

  • With an API key (recommended for your own integrations): the tenant is taken from the key automatically. You don't need to include tenantId in the request at all.
  • Without an API key (for public web forms, landing pages, or chat widgets with no login): include tenantId in the request body so we know which pipeline should receive the lead.
# Authenticated: tenantId is derived from your API key
curl -X POST https://portal.orenyxengine.com/api/v1/triggers/lead \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan Ashford",
    "email": "jordan@ashfordlogistics.com",
    "company": "Ashford Logistics",
    "message": "Looking to automate lead qualification and scheduling."
  }'

# Public web form: no API key, tenantId required instead
curl -X POST https://portal.orenyxengine.com/api/v1/triggers/lead \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "your_tenant_id",
    "name": "Jordan Ashford",
    "email": "jordan@ashfordlogistics.com"
  }'
If you present an API key, it always wins over any tenantId in the body. This stops a valid key for one tenant from being used to inject a lead into a different tenant's pipeline.

What's changed recently

  • 2026-07: Added GET /leads/:id to look up a single lead, and POST /triggers/lead now derives the tenant automatically from an API key (no tenantId needed) while still supporting the original public web-form path.
  • 2026-07: Added Enterprise API Key management features: Audit Logging, Partial Key Masking, and IP Tracking.
  • 2026-07: Added feature flags, exportable activity logs, a command-line tool, and machine-readable API docs.
  • 2026-07: Settlement history became listable, usage alerts became listable, and webhook endpoints are now locked down to public HTTPS addresses only.
  • 2026-07: Multi-currency balances, prorated billing changes, automatic reminders for overdue accounts, and deeper health checks.
  • 2026-07: The original core: the ledger, billing, settlement reconciliation, scoped API keys, rate limiting, safe retries, and webhooks.

Was this page helpful?