Build on NebulaHex programmatically

The NebulaHex API is a small, scoped REST surface for the operations your bots do every day — sending messages, capturing leads, resolving conversations, and subscribing your own systems to events as they happen. It runs against the same data and authorization model your dashboard does. Whatever your role in the workspace lets you do in the dashboard, the API key issued to you can do over HTTP.

Three steps to a working integration:

1. Open your dashboard → Settings → API Keys, click New Key, name it, copy the full key value once (we don’t show it back to you after that).
2. Send the key as a Bearer token in the Authorization header on every request.
3. Hit GET /api/v1/auth/me to confirm the key works. The response contains your workspace identity.

Everything below is shipped and reachable today. We’re running v1 of the API; the version is part of every URL. When v2 arrives, v1 keeps working as-is.

Authentication uses a Bearer token model. Every request must include:

Authorization: Bearer nhx_sk_•••••••••••••••••••••••••••••••••••

Where the key comes from.Workspace owners and admins can create keys from Settings → API Keys in the dashboard. Each key is scoped to one workspace, never crosses workspace boundaries, and is fully revocable from the same screen.

Reveal-once semantics. When a key is created, the dashboard shows the full nhx_sk_... value exactly once. If you lose it, revoke that key and create a new one. There is a one-time POST /api/v1/auth/keys/{keyId}/reveal escape hatch you can call programmatically right after key creation if your provisioning flow needs it.

Forensics. Every API-injected message and lead is stamped with the apiKeyId that produced it. If a key is ever compromised, you can trace exactly what it did before revocation.

Every endpoint is scoped to your workspace via the API key you authenticate with. Resources from other workspaces return 404— we don’t leak existence through errors.

The endpoint groups above cover the lifecycle most integrations need: read your bots and conversations, take programmatic action on live threads, subscribe to events, and manage your own access. The Actions group is where most production integrations spend their time — sending replies, capturing leads to your CRM, marking threads resolved when a downstream ticket gets closed.

Polling for state changes is a tax on both ends. Subscribe a webhook endpoint to NebulaHex events and we push events to you when they happen. Subscriptions are managed through POST /api/v1/hooks.

Every delivery is HMAC-signed with a secret you control. The signature is in the X-NebulaHex-Signatureheader. Verify it before processing — the signature is what proves the request came from us and nobody’s spoofing.

Available event types:

Sample payloads. Hit GET /api/v1/triggers/samples to get an example payload for every event type. Useful for testing your webhook handler locally before flipping the real subscription on.

Retries. Failed deliveries (any non-2xx response, network error, or timeout) are retried with exponential backoff. After a delivery has failed enough times to indicate the endpoint is gone, the subscription is paused and surfaced in the dashboard for you to fix.

Every endpoint is rate-limited per API key on a 60-second sliding window. The default ceiling is 60 requests per minute per key. Hit the limit and you get a 429 with a Retry-After header in seconds. Wait, retry.

If your production workload is consistently hitting the ceiling, you can either parallelize across multiple API keys (each key has its own bucket) or contact us about a higher limit on your account.

CORS. Every endpoint responds to OPTIONS preflight requests with the headers you need to call from a browser. The Authorization header is allowed; standard content types are accepted.

Three patterns that cover most production usage.

List bots in your workspace (curl)

# GET /api/v1/bots
curl https://nebulahex.com/api/v1/bots \
  -H "Authorization: Bearer $NEBULAHEX_API_KEY"

# Response
{
  "bots": [
    {
      "id": "bot_4a7b2",
      "name": "Help center bot",
      "isActive": true,
      "createdAt": "2026-03-14T09:21:47Z"
    }
  ]
}

Subscribe a webhook (Node.js)

// Listen for escalations on your own URL
const res = await fetch("https://nebulahex.com/api/v1/hooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer $${process.env.NEBULAHEX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    event: "conversation.escalation",
    targetUrl: "https://yourapp.com/hooks/nebulahex"
  })
});

const { hookId, signingSecret } = await res.json();
// Store signingSecret server-side — we won’t show it again.

Inject a message and resolve a conversation (curl)

# Step 1: Send a reply as your team
curl -X POST \
  https://nebulahex.com/api/v1/actions/send-message \
  -H "Authorization: Bearer $NEBULAHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"cnv_4a7b2", "message":"Refund processed, you’ll see it in 3 business days."}'

# Step 2: Mark the conversation resolved so the bot takes over next message
curl -X POST \
  https://nebulahex.com/api/v1/actions/resolve-conversation \
  -H "Authorization: Bearer $NEBULAHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"cnv_4a7b2"}'

Everything documented here is shipped and reachable today. We’re running v1 of the API and committed to backward compatibility within v1 — new fields may be added to responses, but existing fields and shapes won’t change without a major version bump.

Reference docs (OpenAPI / Swagger) are in progress.Until they ship, this page covers the surface most integrations need; for endpoint-level field details we haven’t documented yet, the easiest path is to call the endpoint against a test workspace and inspect the response. Reach us via the contact form if you hit a blocker.