Developer platform · General API · webhooks · connectors

Make your platform AI-operable.

Call 1,728 named operations through one contract-generated API, with least-privilege scopes, workspace pinning, dry-run validation and replay-safe writes. Subscribe to canonical events through HMAC-signed background webhooks, or build a governed package in the six-stage Connector Builder.

Get an API key Read the docs OpenAPI contract

Scoped Bearer keys1,728 contract actionsOpenAPI 3.0.3 + PostmanHMAC webhook delivery

Scoped request in

Signed webhook out → 200 OK

Live

1,728named General API actions

62least-privilege scopes

dry_runvalidate write contracts before execution

24hsuccessful idempotent-write replay

The request lifecycle

Scoped request in. Signed event out.

POST an action to /api/v1.php with a scoped Bearer key. OpsIQ pins the workspace, validates the action contract and permissions, then executes or dry-runs it. Subscribed canonical events leave through an HMAC-signed delivery queue with traceable attempts and bounded retries.

HMAC-SHA256 webhooks - inbound and outbound webhook payloads are signed over the raw body; API calls authenticate with a scoped Bearer key.

Automatic retries - failed deliveries back off and retry, with a delivery ID you can trace.

Replay-safe writes - successful idempotent writes return the same response for 24 hours; concurrent duplicates share one claim.

01 Bearer request 02 pin workspace 03 validate contract 04 execute or dry-run 05 queue signed event

Quickstart

From key to governed integration in three steps.

Issue a least-privilege key, discover the generated contract, dry-run a write, then subscribe a webhook when your application needs background event delivery.

Contract consoleConnected

Executedry_run → approved write, same contract

Get a key

Sign up and generate a scoped Bearer API key (opq_…) in developer settings, and give each integration only the surfaces it needs.

Discover & validate

Read meta.actions, meta.action and meta.scopes; use dry_run to validate writes before execution.

Execute & subscribe

Add an idempotency key for writes, then subscribe your endpoint to the canonical events your application needs.

How it fits together

One connector pattern. Five clean primitives.

Anything platform-specific lives in a connector. The OpsIQ core stays generic, the AI stays predictable, and your integration stays auditable.

Triggers

Tell OpsIQ what just happened.

Emit canonical events from your platform, or define a governed custom event. Subscribers receive the event through the registered priority and delivery rules.

Event reference

Universal + custom eventsinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up or your own. Fan-out subscribersThe AI brain, automation rules, mirror connectors and your webhook endpoints all react. Priority orderDeterministic dispatch so mirrors write before alerts fire.

02 / Action contracts

Tell OpsIQ what the AI is allowed to do.

Every named operation receives a generated contract: scope, feature, read or write kind, risk, confirmation policy, request and response schema, dry-run support, idempotency and stable errors.

Action schema

The AI can't invent actionsIt can only ask to run ones you've registered. Confirmation policyRisky actions trigger a preview card before any side-effect. Role + surface gatingEvery action declares the roles and surfaces allowed to run it.

generated action contract · JSON

{
  "action": "tickets.reply",
  "kind": "write",
  "scopes": ["tickets.write", "admin"],
  "feature": "ticket_system",
  "risk": "medium",
  "confirmation": "recommended",
  "idempotency": "supported",
  "dry_run": true,
  "request": { "type": "object" },
  "response": { "required": ["success"] }
}

03 / Signed webhooks

Push events to your stack - with cryptographic proof.

Subscribe any URL to any event. OpsIQ POSTs the JSON payload signed with HMAC-SHA256 over the raw body - verify it in a few lines.

Replay protectionTraceable delivery IDBack-off retries

Webhook reference

verify webhook - php

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, $secret); // hex digest, no prefix
if (!hash_equals($expected, $sig)) http_response_code(401);
$event = json_decode($raw, true);

04 / SDKs

Use direct HTTP or generate the client you prefer.

The full General API is published as OpenAPI 3.0.3 and Postman. PHP reference senders plus Node and Python integration clients cover signed event and webhook flows; any stack can call the same JSON action surface directly.

client examples

const response = await fetch(`${base}/api/v1.php`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.OPSIQ_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    action: "tickets.reply",
    dry_run: true,
    idempotency_key: crypto.randomUUID(),
    body: "Thanks. We are checking this now."
  })
});

$payload = json_encode([
  'action' => 'tickets.reply',
  'dry_run' => true,
  'idempotency_key' => bin2hex(random_bytes(16)),
  'body' => 'Thanks - we are checking this now.',
]);

$ch = curl_init($base . '/api/v1.php');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('OPSIQ_KEY'),
    'Content-Type: application/json',
  ],
]);

response = requests.post(
    f"{base}/api/v1.php",
    headers={
        "Authorization": f"Bearer {os.environ['OPSIQ_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "action": "tickets.reply",
        "dry_run": True,
        "idempotency_key": str(uuid.uuid4()),
        "body": "Thanks - we are checking this now.",
    },
)

Direct JSON HTTPOpenAPI 3.0.3Postman collectionIntegration helpers

05 / The connector pattern

Build once. Plug into anything.

A connector is a governed package generated or imported through Identity, Auth, Test, Actions, Triggers and Review. Its manifest declares the capability surfaces OpsIQ is allowed to expose.

Open the six-stage Builder

Six guided stagesIdentity, Auth, Test, Actions, Triggers and Review keep package generation explainable. Contract-drivenProfiles and 52 capability types declare the surfaces a package implements. Release-gatedSafety, provenance and conformance checks run before a package is treated as ready.

From intent to safe action

Plain English in. Audited operation out.

OpsIQ never invents the right call. It walks through the registered contracts, prepares the payload, asks for confirmation when the action requires it, and produces a complete audit row when it executes, so an AI that can act never becomes an AI you can't trust.

Contract-bound. The AI only proposes actions you've registered.

Confirm before side-effects. Risky actions surface a preview card first.

Total recall. Every prompt, response and action result captured in AI History.

See the action schema

4 stepsintent → audit

HMACsigned before execute

No invented callscontract registry only

Confirm-gatedpreview before side-effects

Request traceactor + contract + result

Reference

API surface at a glance.

One JSON POST surface exposes 1,728 named actions. Each generated contract declares auth scopes, read/write kind, risk, confirmation, request schema, dry-run, idempotency and stable errors.

OpenAPI 3.0.3 reference

ActionAuthWrite safetyLimit

Write actionsPOST /api/v1.php · contract validated

ACTION tickets.replytickets.writedry_run + idempotencyConfigured / hour

ACTION security.reportsecurity.writedry_run + idempotencyConfigured / hour

ACTION platform.routes.writeadminconfirmation + keyConfigured / hour

Read & discovery actionsSame POST surface · stable envelopes

ACTION meta.actionsPublic discoveryRead onlyConfigured / hour

ACTION tickets.listtickets.readRead onlyConfigured / hour

ACTION connectors.listconnectors.readRead onlyConfigured / hour

Rate limits are configured per key on an hourly window. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a rejected request returns 429 with Retry-After. Use the OpenAPI 3.0.3 contract or Postman collection generated from the same runtime registries.

Build a connector

Build, test and release in six stages.

Start from a governed profile or define the contract yourself. The Builder validates each stage before it generates a self-contained connector package.

1Identity. Name, slug, profile and declared capability surfaces.

2Auth. API key, Bearer, Basic, OAuth 2.0, HMAC or a custom client.

3Test. Validate the bounded connection settings before packaging.

4Actions. Map named operations, parameters, scopes and risk.

5Triggers. Declare inbound events, webhooks, polling and sync behavior.

6Review. Inspect the generated contract and pass the release gate.

Test before you ship

Validate safely, then pass the release gate.

Use dry_run on supported write actions, run the Builder's bounded connection test, and inspect the generated manifest and contract before release. Package validation checks capability names, settings, provenance and required files; background workers handle reactive polling and outbound delivery.

Dry-run writes Bounded connection test Contract conformance Cron-driven delivery

Open Connector Builder Webhook reference

connector.php · php

class AcmeConnector extends AbstractConnector { public function slug(): string { return 'acme'; } public function name(): string { return 'Acme'; } public function description(): string { return 'Acme bridge'; } // Use names from ConnectorContract public function capabilities(): array { return ['actions', 'webhook']; } public function settingsSchema(): array { return [['key' => 'token', 'type' => 'password']]; } public function testConnection(array $settings): array { return ['success' => true]; } public function handleWebhook( array $payload, array $headers, array $settings ): array { return ['success' => true]; } }

⚖️ How it compares

OpsIQ vs a DIY integration.

What a contract-bound, signed, audited platform gives you that rolling your own webhooks and AI-action plumbing never will.

Capability	Roll your own	OpsIQ
Scoped Bearer API + HMAC-signed webhooks	Hand-rolled	✓
Dry-run writes + 24-hour successful replay	DIY	✓
1m → 5m → 30m → 2h → 12h retries	DIY queue	✓
Action-contract registry (AI can't invent calls)	—	✓
Confirmation policy before side-effects	—	✓
Stable error envelope + request IDs	Manual logging	✓
Direct HTTP + generated client options	Write your own	✓
OpenAPI 3.0.3 machine-readable contract	Maybe	✓
Six-stage Builder + package release gate	Build a toolchain	✓
Workspace-pinned keys and hourly limits	Varies	✓
Connector pattern: platform code stays isolated	—	✓

FAQ

Developer questions, answered.

Authentication, contracts, retries, client generation, safe testing and the connector model, before the first production request.

General API calls send Authorization: Bearer opq_…. Keys can be unrestricted, restricted or read-only, carry least-privilege scopes, obey an hourly limit and can be pinned to a workspace. Webhook signing is separate: outbound deliveries carry X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event and X-OpsIQ-Delivery.

No. The AI can only propose named operations in the action registry. Each generated contract declares scope, request fields, risk and confirmation policy; operations whose policy requires confirmation surface a human preview before execution.

Recompute hash_hmac('sha256', $rawBody, $secret) and compare its hexadecimal digest with X-OpsIQ-Signature using hash_equals. Validate X-OpsIQ-Timestamp within your replay window and use X-OpsIQ-Delivery as the traceable delivery identifier.

A non-successful attempt enters the background delivery queue. OpsIQ retries on the 1-minute, 5-minute, 30-minute, 2-hour and 12-hour ladder while retaining the delivery identifier and attempt history for diagnostics.

Call the JSON action surface directly, import the generated Postman collection, or generate a client from OpenAPI 3.0.3. PHP reference senders and Node/Python integration clients support event and webhook flows; they are helpers rather than separate API contracts.

Use dry_run on actions whose generated contract supports it, run the Connector Builder's bounded connection test, inspect its generated files, and pass the package conformance and release gates before treating the connector as ready.

The installed release generates its API and connector contracts from its own runtime registries. Your deployment owns its public URL, secrets, storage and cron/workers, so behavior should be verified against the installed release rather than assumed from a cloud environment.

A connector is a governed package containing the adapter, settings.json, optional actions.json, a generated capability contract, documentation and optional enterprise extensions. The six-stage Builder assembles it; the registry discovers it; conformance and release gates validate it.