OpsIQ Developer Documentation

Start Here

OpsIQ exposes a stable namespaced action API at /api/v1.php. Send {"action":"meta.actions"} to discover the live catalog, then call actions such as crm.contacts.list, tickets.open, writing.reply, crm.deals.list, or kb.faq.save.

curl /api/v1/openapi.php

https://your-opsiq-domain.com/api/v1.php

Authentication

Create an API key in OpsIQ, assign only the scopes that integration needs, and send it as a bearer token.

Authorization: Bearer opq_your_key_here

curl -X POST https://your-opsiq-domain.com/api/v1.php \
  -H "Authorization: Bearer opq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"meta.actions"}'

Keys can be rotated at any time. Store them server-side only. Browser widgets should use the widget identity token flow, not public API keys.

Every API v1 response includes a request_id. Keep it with integration logs so OpsIQ support can trace the exact authenticated request, workspace, action, outcome, and latency without storing the caller's raw IP address.

POST /api/v1.php
{"action":"meta.me"}

meta.me returns the verified key name, scopes, permissions mode, workspace, effective allowed/blocked actions, and recent usage summary for agency and enterprise integrations.

Scopes

Contacts

curl -X POST https://your-opsiq-domain.com/api/v1.php \
  -H "Authorization: Bearer opq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"crm.contacts.list","q":"ada","limit":25}'

{
  "action": "crm.contacts.upsert",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "tags": ["trial", "developer"]
}

Tickets

{
  "action": "tickets.open",
  "customer_email": "customer@example.com",
  "customer_name": "Example Customer",
  "subject": "Cannot activate account",
  "body": "Activation email never arrived.",
  "priority": "high"
}

{"action":"tickets.bulk","operation":"close","ids":[123,124]}

Chats

For visitor live chat, use the widget runtime. The public action API is for server-side integrations and operator tooling.

Analytics

curl -X POST https://your-opsiq-domain.com/api/v1.php \
  -H "Authorization: Bearer opq_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"action":"crm.events.list","limit":50}'

Responses are workspace-scoped. Shared site groups do not merge per-domain visitor data unless the called action explicitly supports that aggregation.

Proactive Events

{
  "action": "crm.activities.record",
  "email": "customer@example.com",
  "event": "checkout.abandoned",
  "value": 129.50,
  "currency": "USD"
}

Use meta.actions to discover the currently enabled proactive and lifecycle actions on the install.

Knowledge Base

{
  "action": "kb.faq.save",
  "question": "How do I reset my password?",
  "answer": "Open Account Settings, choose Security, then Reset Password.",
  "status": "published"
}

The customer AI can use published knowledge-base content when answering visitors, depending on your AI instruction settings.

Widget And Identity

Install the OpsIQ widget on each website you want to track. Visitor data is collected per domain and stamped to the active site.

<script>
  window.OpsIQSettings = {
    siteKey: 'site_public_key',
    identity: {
      email: 'customer@example.com',
      name: 'Example Customer',
      external_id: 'cust_123'
    }
  };
</script>
<script src="https://your-opsiq-domain.com/widget.php" async></script>

Use identity when the visitor is logged in. For anonymous visitors, omit identity and OpsIQ will stitch later activity when the visitor identifies themselves.

Webhooks

Webhooks let other tools subscribe to OpsIQ activity. Register endpoints with crm.webhooks.save (or in the admin), then sign requests with the shared secret. The event names below come from the CRM event stream; call crm.events.catalog for the authoritative live list of subscribable events on your install. The same rows are also queryable by polling crm.events.list.

Also emitted: crm.company.created, crm.company.merged, crm.company.updated, crm.deal.updated.

{
  "event":"crm.contact.created",
  "event_id":"evt_123",
  "_workspace_key":"site_abc123",
  "contact_id":42
}

Connector SDK

Connectors are the production path for platform-specific actions. A connector defines metadata, settings, capability flags, and action specs. OpsIQ calls those actions through the gateway so validation, audit hooks, and platform sync stay consistent.

{
  "slug":"example_platform",
  "name":"Example Platform",
  "version":"1.0.0",
  "manifest_version":1,
  "compatibility":{"opsiq_min":"1.0.0","opsiq_max":"*"},
  "capabilities":["native_api","tickets","customers"],
  "settings":[{"key":"api_key","type":"password","label":"API key"}]
}

{
  "id":"ticket.reply",
  "label":"Reply to ticket",
  "params":{"ticket_id":"string","message":"string"},
  "requires_confirmation":true
}

Email connectors should expose mailbox/piping settings, not store or currency settings. Commerce connectors should expose order/customer/product actions. Support connectors should expose ticket, comment, assignment, and status actions.

Errors And Status Codes

{"success":false,"error":"Action 'tickets.open' is restricted on this API key.","permissions_mode":"restricted","request_id":"req_..."}

Authentication failures (missing, invalid, expired, or rate-limited key) return 401 with {"success":false,"error":"Invalid, expired, or rate-limited API key."}. A valid key that lacks a required scope, or is blocked by its permissions mode, returns 403.

Examples

JavaScript fetch

const res = await fetch('https://your-opsiq-domain.com/api/v1.php', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer opq_your_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'tickets.open',
    customer_email: 'customer@example.com',
    subject: 'Need help',
    body: 'The checkout page is failing.'
  })
});
const ticket = await res.json();

PHP cURL

$ch = curl_init('https://your-opsiq-domain.com/api/v1.php');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer opq_your_key_here',
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode(['action' => 'crm.contacts.upsert', 'email' => 'ada@example.com', 'name' => 'Ada Lovelace']),
]);
$response = json_decode(curl_exec($ch), true);

Python requests

import requests

r = requests.post(
    'https://your-opsiq-domain.com/api/v1.php',
    headers={'Authorization': 'Bearer opq_your_key_here'},
    json={'action': 'crm.events.list', 'limit': 50},
    timeout=20,
)
r.raise_for_status()
print(r.json())