Utviklerplattform · Generelt API

Gjør plattformen din AI-operativt.

Call 2,418 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.

Få en API -nøkkel Les docs OpenAPI kontrakt

Skjulte Bearer-nøkler2,418 contract actionsOpenAPI 3.0.3 + PostmannHMAC webhook levering

Omfattende anmodning i

Signert webhook ut→ 200OK

Nivå

2,418navngitt Generelt API handlingar

69minstepris

dry_runValidere skriftlig kontrakt før gjennomføring

24tvellykket idempowen-write replay

Forespørselen livssyklus

Omfattende forespørsel i. Signert hendelse ut.

POST en handling til /api/v1.php med en omfanget Bearer-nøkkel. OpsIQ pins arbeidsområdet, valideres handlingsavtalen og tillatelsene, deretter utfører eller tørkekjør den. Abonnert kanoniske hendelser går gjennom HMAC - signert levering kø med sporbare forsøk og begrensede retries.

HMAC- SHA256 webhooks - inngående og utgående webhook nyttelaster er signert over rå kroppen; API samtaler autentisering med en omfangsbestemt Bearer nøkkelen.

Automatiske retries - mislykkede leveranser tilbake og forsøke, med en levering ID kan du spore.

Replay-safe skriver - vellykkede idempotensielle skriver returnerer samme respons for 24 -timer; samtidig dupliserer deler ett krav.

01 Bearer-forespørsel 02 pin arbeidsflate 03 Valider kontrakt 04 Utførelse eller tørrkjøring 05 køen signert hendelse

Hurtigstart

Fra nøkkelen til styret integrasjon i Tre trinn.

Sende en minstprivilege nøkkel, oppdage den genererte kontrakten og tørrkjør et skrivebrev. Deretter abonnere på Webhook når programmet trenger bakgrunnsbegivenhet levering.

KontraktkonsollTilkoblet

Kjørtorr_run → godkjent skrive, samme kontrakt

Få en nøkkel

Registrer deg og generere en omdøpt Bearer API nøkkel (opq_…) i utviklerinnstillinger, og gi hver integrasjon bare de overflatene det trenger.

Oppdag & valider

Les meta.actions, meta.action og meta.scopes; bruk dry_run å validere skriver før henrettelse.

Køyr & abonner

Legg til en idempetensnøkkel for skriving, og abonner deretter endepunktene dine på kanoniske hendelsene programmet trenger.

Hvordan det passer sammen

Ett kontaktmønster. Fem rene primitive.

Alt plattformspesifikk bor i en kontakt. OpsIQ -kjernen forblir generisk, AI forblir forutsigbar og din integrasjon forblir revisjonsbar.

Utløsere

Fortell OpsIQ hva som bare skjedde.

Emit kanoniske hendelser fra plattformen din, eller definere en styret egendefinert begivenhet. Abonnementere mottar arrangementet gjennom den registrerte prioritet og leveringsregler.

Hendelsesreferanse

Universal + tilpassede hendelserinvoice.paid, ticket.created, subscription.cancelled, customer.signed_up eller din egen. Fan-out abonnenterAI-hjernen, automatiseringsreglene, speilkontaktene og dine webhook-endepunkter alle reagerer. PrioritetsordenDeterministisk forsendelse så speil skrive før varsler brann.

02 / Handlingskontrakter

Fortell OpsIQ hva AI har lov til å gjøre.

Hver navngitt operasjon mottar en generert kontrakt: omfang, funksjonsevne eller skrive type, risiko, bekreftelsesregler og -responsskjemaer.

Handlingsskjema

AI kan ikke oppfinne handlingerDet kan bare be om å kjøre dem du har registrert. BekreftelsespolicyRisikofulle handlinger utløser et forhåndsvisningskort før noen bivirkning. Rolle + overflate gatingHver handling erklærer rolle og overflater som kan kjøre den.

generert handlingskontrakt · 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 / Signert webhooks

Push hendelser til stabelen din - med kryptografisk bevis.

Subscribe any URL to any of the 52 deliverable events. OpsIQ POSTs the JSON payload signed with HMAC-SHA256 over the scheme version, the timestamp, the delivery ID and the body together, not the body alone, so yesterday's delivery cannot be replayed at you today.

Replay beskyttelseSporbar levering ID5-step back-off

Webhook referanse

verifisere webhook - php

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_OPSIQ_SIGNATURE'] ?? '';   // "v2=<hex>"
$ts  = (int)($_SERVER['HTTP_X_OPSIQ_TIMESTAMP'] ?? 0);
$id  = (int)($_SERVER['HTTP_X_OPSIQ_DELIVERY'] ?? 0);

if (abs(time() - $ts) > 300) http_response_code(401);   // replay window
[$ver, $hex] = array_pad(explode('=', $sig, 2), 2, '');  // split the prefix

$signed   = $ver . '.' . $ts . '.' . $id . '.' . $raw;   // NOT the body alone
$expected = hash_hmac('sha256', $signed, $secret);
if (!hash_equals($expected, $hex)) http_response_code(401);

$event = json_decode($raw, true);   // $id is stable across retries

04 /SDKs

Bruk direkte HTTP eller generer klienten du foretrekker.

Den fulle generalenAPI utgitt som OpenAPI 3.0.3 og Postman. PHP referanseavsendere pluss Node-og Python integrasjonsklienter dekker signert hendelser og webhook flyt; enhver stabel kan kalle det samme JSON handlingsoverflate direkte.

kundeeksempler

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.",
    },
)

Direkte JSON HTTPOpenAPI3.0.3Postman samlingIntegrasjonshjelpere

05 / Koblingsmønsteret

Bygg en gang.

En kontakt er en styret pakke generert eller importeres gjennom identitet, Auth, Teste, Handlinger og Triggers. Det manifest erklærer evneflatene OpsIQ har lov til å eksponere.

Åpne 6-trinns byggmesteren

Seks veiledede stadierIdentifikasjon, authorization, Teste, Handlinger og Triggers holder pakkegenerasjon forklarelig. Kontraktdrevet8 profiles and 57 capability types declare the surfaces a package implements. UtgivelsesportertSikkerhets-, bevis og samsvarskontroll kjører før en pakke behandles som klar.

Fra intensjon til sikker handling

Vanlig engelsk i. -Revidert operasjon ute.

OpsIQ oppfinner aldri riktig anrop. Den går gjennom registrerte kontrakter, forbereder nyttelasten, ber om bekreftelse når handlingen krever det og produsere en komplett revisjonsrad når den gjennomføres så et AI som kan handling Aldri bli en AI du ikke kan stole på.

Kontraktbundet. AI foreslår bare handlinger du har registrert.

Bekreft før bivirkninger. Risikofulle handlinger overflater et forhåndsvisningskort først.

Total tilbakemelding. Hver rask, respons og handling resulterer i AI History.

Se handlingsskjemaet

4 -trinnForsett → revisjon

HMACsignert før utførelse

Ingen oppfunnne samtalerkun kontraktsregister

BekreftetForhåndsvisning før bivirkninger

Forespørselssporskuespiller + kontrakt + resultat

Referanse

API -overflate - Et blikk.

One JSON POST surface exposes 2,418 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 referanse

HandlingAutentiserSkrive sikkerhetBegrens

Skriv handlingerPOST /api/v1.php · Kontrakt validert

ACTION tickets.replytickets.writetorr_run + idempactensKonfigurert / time

ACTION security.reportsecurity.writetorr_run + idempactensKonfigurert / time

ACTION platform.routes.writeadminBekreftelse + nøkkelKonfigurert / time

Lese- og oppdagelseshandlingerSamme POST overflate · stabile konvolutter

ACTION meta.actionsOffentlig oppdagelseLesebeskyttetKonfigurert / time

ACTION tickets.listtickets.readLesebeskyttetKonfigurert / time

ACTION connectors.listconnectors.readLesebeskyttetKonfigurert / time

FolkOS HR-handlingerCurated hr.* kontrakt · hr.read / hr.write Omfang

ACTION hr.people.listhr.readLesebeskyttetKonfigurert / time

ACTION hr.people.createhr.writetorr_run + idempactensKonfigurert / time

ACTION hr.org.treehr.readLesebeskyttetKonfigurert / time

PeopleOS HR sender ikke utgående HRS-webhook hendelser. Nå det gjennom samme POT overflate, eller abonnere på arrangementene andre moduler publisere. Full referanse: PeopleOSAPIog kontakter og PeopleOS-delen av utviklerreferansen. Modulen er rettighetsportet, så en nøkkel uten hr får et avslag, ikke en tom liste. Hva folk er.

Prisgrenser konfigureres per nøkkel på et timevindu. Responser eksponere X-RateLimit-Limit, X-RateLimit-Remaining og X-RateLimit-ResetEn avvist anmodning returnerer 429 med Retry-After. Bruke OpenAPI 3.0.3 kontrakt eller Postman samling generert fra samme kjøringstid.

Bygg en kobling

Bygge, test og frigjøre i Seks stadier.

Start fra en styret profil eller definert kontrakten selv. Byggemaskin validerer hvert trinn før den genererer et egeninnbefattet kontaktpakke.

1Identifikasjon. Navn, sløvhet og profilert evnesflater.

2Auth. API Nøkkel, Bearer OAuth 2.0 HMAC eller en tilpasset klient.

3Test. Valider innstillingene for avgrenset tilkobling før emballasje.

4Handlinger. Kart navngitte operasjoner, parametere og risiko.

5Triggere. Deklarere inngående hendelser, webhooks, polling og synkronisering oppførsel.

6-Recension. Inspeksjon av den genererte kontrakten og passere utgivelsesport.

Test før du skiper

Valider trygt, og deretter passer utgivelsesporten.

Bruk dry_run på støttede skrivehandlinger, kjøre Byggemannens begrenset tilkobling test og inspisere den genererte manifestet og kontrakten før utgivelse. Pakkesivalidering sjekk evne navn, innstillinger, bevis og nødvendige filer; bakgrunnsarbeidere håndterer reaktiv polling og outbound levering.

Torrdreven skriver Begrenset tilkoblingstest Kontraktskonformasjon Cron-drevet levering

Åpne kontaktbygger Webhook referanse

kobling. php · php

klasse AcmeConnector strekker seg AbstractConnector { offentlig funksjon dobbel (): streng { tilbake \"Acme\"; } offentlig funksjon navn( 2): streng { tilbake «Acme»; } offentlig funksjon Beskrivelse(): streng { tilbake \"Acme bro\"; } // Bruk navn fra ConnectorContract offentlig funksjon kapasiteter (): matrise { tilbake [«handlinger», 'webhook']; } offentlig funksjon innstillingerSchema(): matrise { tilbake [[\"nøkkel\" => \"token\", \"type\" => \"passord\"]]; } offentlig funksjon testConnection(matrise $settings): matrise { tilbake [«vellykke» => sant]; } offentlig funksjon håndtakWebhook( matrise $payload, matrise $headers, matrise $settings ): matrise { tilbake [«vellykke» => sant]; } }

01 · Connector contract 2.4

En pakke kan ikke hevde en evne Koden har ikke.

OpsIQ\Connectors\ConnectorContract er myndigheten. Runtime oppdagelse, Builder, førsteparts pakker, konformance, General API og hver referanse leser at ett register. Deklarer en kapasitet, og tre filer må være enige med hverandre før OpsIQ Ruter en rad til deg.

-Fig. 01kontaktpakke, deler manifest scale 1:1 · contract 2.4

01 connector.php i Runtime-klassen
02 IdentityProvider.php stabil ekstern nøkkel
03 SalesIngest.php forsoningSales ()
04 actions.json navngitte operasjoner
05 settings.json operatørkonfigurasjon
06 connector_contract.json maskinlesbar myndighet

07 signature.json en HMAC over en SHA-256 av hver fil over, pluss et ed25519 opprinnelsesbevis

Kapabilitetsmatrise all 57, as registered

Handlinger Utløsere webhook journey_events sammenheng guest_lookup identitet sales sales_reconciliation Fakturering payments handel inbound_ticket outbound_reply ticket_merge sync_users sync_departments sync_orders sync_products sync_projects customer_import security_events security_native_block survey reply_feedback promo_audience promo_feed email_mailbox inbound_email outbound_email mailbox ai_tickets ai_reply ai_brain_aware native_api platform_bridge native_data crm block_registry inbound_comment outbound_note outbound_notification oauth reviews lokal dette site_intelligence Analyser comms admin_assets enterprise_hooks durable_queue ticket_mirror attachment_bridge database_migrations scheduled_workers conflict_resolution

generert 30 deklarativ 20 utvidelse 7

To signaturer, to spørsmål.

hmac-sha256 over en deterministisk nyttelast av per fil SHA-256 Hashes svar Dette har blitt endret siden signering. En ed25519 signatursvar ble det signert av Nabtech, kontrollerbar med den pakkede offentlige nøkkelen og ingen delt hemmelighet. Redigere en byte og de første stoppene matcher.

marketplace.json er utenfor signaturen per definisjon: installereren skriver den etter signering, så forlaget kunne aldri ha signert det.

02 · verktøy/mutation_proof.php

En vakt som aldri har mislykkes er ubevisst.

Grønne tester forteller deg ingenting brøt i dag. De sier ikke at vakten du skrev ville stoppe det som var skrevet for å slutte, fordi en garde som aldri utøves passerer nøyaktig som et vakt som gjør ingenting. Så vi stopper hjertet med hensikt og krever at skjermen skriker.

· Leserollen må nekte en destruktiv operasjon CH1 verify_commerce_contracts

src/Connectors/CommerceRoleMapVerifier.php MUTERT

211    /* A read role must never reach a destructive operation. */
212-   if ($isRead && $isDestructive) {
212+   if (false) {
213        $errors[] = "read role '{$role}' points at a destructive op";
214        return false;
215    }

Nøyaktig en Det kreves tekstspill. Null kamper, eller to og beviset stopper før det kan lyve.

$ php tools/mutation_proof.php --spec=proofs.json

1[ ok ]hash    sha256 4f2a9c1e…
          remember the file exactly as it is
2[ ok ]control exit 0
          green BEFORE anything is touched
3[ ok ]mutate  1 match, lint ok
          one replacement, then php -l the mutant
4[RED ]prove   exit 1
          and "read role destructive" IS in the failures
5[ ok ]restore bytes written
          the original, not a regenerated copy
6[ ok ]verify  sha256 matches
          and the check is green again
 ══ PROVEN. file restored, hash matched, 1 proof run, 0 failed.

Et mislykket bevis er Aldri dokumenter om at en sjekk gikk galt er ikke bevis for å vakten fungerer.

Mutasjonen ble aldri brukt.

Søketeksten var ikke lik, filen ble urørt og suiten passerte. Grønn under den gamle koden om kode som aldri var gammel. Fanget ved å kreve nøyaktig én tekstual match og sammenligne fil hashes hver side .

Mutasjonen brøt noe annet.

Suiten gikk rødt fordi filen sluttet å tolke eller bootstrap døde, og beviset registrerte en raud som ikke hadde noe med vakten å gjøre. Fanges ved å lindre den mutate og krevde at navngitt Test blant feilene.

Det kan ikke være en mutant på disken.

Hver mutasjon kopierer originalen til en sidebil utenfor det webbevarte treet, skriver den markør som navngir den enestående endringa og blir angret av et nedleggelseshåndteringsprogram på hver utgangsbane. En markering fra ett krasj er æret før neste mutasjon i filen.

03 · Konformanse

Sertifisering er en kommando med en utgangskode.

Not a review queue where somebody reads your code and forms an opinion. Run the same suites we run, on your own machine, before you submit. 8 published JSON Schemas under doc/contracts/schemas/ dekningsinnstillinger, handlinger, Byggeserie specs, reise- og handelsarrangementkartlegginger, arbeidsflytoppskrifter, kontaktkontrakter og utgivelsesmanifest.

manifests Fortolke og være enige med hverandre
kapasitet Finnes i løpetid-klassen
interfaces implementert der deklarerte
files alle nødvendige filtilstedeværelser
Handlinger matcher handlingene manifest
destructive Deklarere bekreftelse
identitet En stabil ekstern nøkkel, ikke e-post
gjenta en gjenta oppdateringer, aldri dupliserer
virksomhet Erklæringer samsvare med utvidelsen
dokumenter LESME, DEVELOPER
skjemaer hver JSON -validerer

avslutting 0 acme: conformant against contract 2.4 En feil suite navn sjekk og fil. Du fikser den, ikke oss

$ php tools/test_connector_conformance_all.php --connector=acme $ php tools/test_connector_json_schemas.php $ php tools/verify_commerce_contracts.php $ php tools/release_gate_connectors.php --require-signatures

Punkt den første på en reell ikke-produksjon konto med --live-settings=/secure/test-acme.jsonMens du fortsatt iterrer, bytte den siste for --unsigned-okDet behandler en manglende signatur som forventet advarsel i stedet for å late som om det er bra.

04 · Trade_roles.json

Deklarer det du kan selge En fil, ikke en registrering.

En kontakt som kan selge erklærer hvilken av sin egen operasjoner svarer OpsIQs kanoniske handelsrollene. Tilstedeværelsen av filen er kravet. Det vises i salgsinnstillingen det øyeblikket den erklærer og forsvinner når den stopper. Ingen liste å bli med, ingen å spørre.

kanonisk rolle commerce_roles.json din operasjon

REFUSED

En kanonisk skrive rolle kartlagt til en generell rekordskrive. Kampen er strukturell: et lagrings substantiv ved siden av ett quartng verb, uansett navngivning konvensjon. Skriving forretningsrekke direkte hopper over plattformens priser, tilgjengelighet lås og bekreftelse post, og produserer en ordre kjøperens eget system bare halvparten tror på. Nei recovery En tidsavbrudd ville være ugjenvinningsbar.

commerce_roles.jsonVALID

{
  "commerce": {
    "roles": {
      "catalog_search": { "operation": "acme_search_products", "transport": "http" },
      "order_get":      { "operation": "acme_get_order",       "transport": "http" },
      "order_create":   { "operation": "acme_create_order",    "transport": "http",
                         "recovery":  "acme_get_order" }
    }
  }
}

Dens egen fil på hensikt: connector_contract.json genereres og skjemasettene additionalProperties:false, så en hånd-forfatter blokk der ville mislykkes validering og deretter bli overskrevet på nestegeneratorkjøring.

Lukket ordforråd

En rolle ikke i CommerceRole eksisterer ikke. OpsIQ utviser aldri en fra et operasjonsnavn, fordi navnet er ikke et løfte.

Din egen handling

Operasjonen må vises i din actions.jsonDeklarer en som ikke eksisterer lover kunden noe som da produserer ingenting.

Skriver erklærer gjenoppretting

Den farligste tidsavbruddet er den som allerede har gjort arbeidet. Uten en idempotensiell - hadde min skrivejord - oppslag, de eneste alternativene blir forsøkt blind eller mister ordren.

Betalingsroller som sertifiseres

Enhver betalingsklasse-rolle erklærer også payment_profile med omgivelsene, webhook_verify bruk av leverandørens egen ordning, og event_map. Et uuttalt miljø er hvordan en testmodus-leverandør tar live betaling.

Byggemaskinen validerer disse som du skriver og verifisert bekrefter pakken. Begge kaller de samme funksjonene, så det kan ikke være uenigt.

⚖️ Hvordan den sammenligner

OpsIQvs a DIY-integrasjon.

For en kontraktsbunden, signert og revidert plattform gir deg at rulle dine egne webhooks og AI-action VVS aldri vil.

Kapabilitet	Rull din egen	OpsIQ
Skjulte Bjørn API + HMAC-signert webhooks	Håndvalset	✓
Dry-run skriver + 24/ time vellykket replay	DIY	✓
1m→5m→30m→ 2h → 12hRetries	DIY kø	✓
Handlingskontraktregister (AI kan ikke oppfinne samtaler)	—	✓
Bekreftelsespolicy før bivirkninger	—	✓
Stabil feil konvolutt + forespørsel IDs	Manuell logging	✓
Direkte HTTP + genererte klientalternativer	Skriv din egen	✓
OpenAPI 3.0.3 maskinlesbar kontrakt	Kanskje	✓
Sekstrinns byggmester + pakkeutgivelsesport	Bygg et verktøykjede	✓
Arbeidsplass-pinnede tastar og timebegrenser	Varierer	✓
Koble til mønster: plattformkode forblir isolert	—	✓

Ofte stilte spørsmål

Utviklerspørsmål, Svaret.

Autentisering, kontrakter, retries, klientgenerering, sikker testing og kontaktmodellen før den første produksjonsforespørselen.

Generelt API Kontakter Send Authorization: Bearer opq_…. Nøkkelene kan være ubegrenset, begrenset eller leselig, ha minst privilegere omfanger, adlyde en times grense og kan festes til et arbeidsområde. Webhook-signaturen er separat: utgående leveranse bære X-OpsIQ-Signature, X-OpsIQ-Timestamp, X-OpsIQ-Event og X-OpsIQ-Delivery.

Nei. AI kan bare foreslå navngitte operasjoner i handlingsregisteret. Hver generert kontrakt erklærer omfang, forespurn feltene, risiko- og bekreftelsesregler; drift som krever bekreftelser på overflate en menneskelig forhåndsvisning før gjennomføringen.

Beregne hash_hmac('sha256', $rawBody, $secret) og sammenligne dens Heksadesmør fordøyelse med X-OpsIQ-Signature bruk av hash_equals. Valider X-OpsIQ-Timestamp i ditt gjenspill-vindu og bruk X-OpsIQ-Delivery som sporbar leveringsidentifikator.

Et ikke-vellykket forsøk kommer inn i bakgrunnslevering køen. OpsIQ Restier på1-minutt, 5-minutt, 30-minutt,2- timer og 12-time stige mens du beholder leveringsidentifikatoren og forsøk historie for diagnostikk.

Ring JSON handlingsoverflate direkte, importer den genererte Postman samlingen eller generere en klient fra OpenAPI 3.0.3. PHP referanseavsendere og Node/Pothon integrasjonsklienter støtter hendelsen og webhook-strømmer; de er hjelpere i stedet for separatAPI kontrakter.

Bruk dry_run på handlinger som har generert kontrakt støtter det, kjører Connector Builders begrensede tilkoblingstester og inspiserer degenererte filene og passere pakken konformans-og frigjøringsportene før du behandler kontakten som klar.

Den installerte utgivelsen genererer sin API og kontaktkontrakter fra sine egne Runtime-registre. Din utplassering eier sin offentlighet URL Hemmeligheter, lagring og cron/arbeidere så atferd bør verifiseres mot den installerte utgivelsen i stedet for antatt fra et skymiljø.

En kobling er en styret pakke som inneholder den, settings.json, valgfri actions.json, en generert funksjonskontrakt og dokumentasjon. Den sekstrinns byggemaskinen samler den; registeret oppdager det; konformasjon og frigjør porter validere dem.