Developer Hub

ORCONIC API — REST + Webhooks

Die ORCONIC API ist ein REST-API mit JSON-Payloads, Bearer-Style Authentifizierung und HMAC-signierten Webhooks. Alles, was du im Dashboard machst, geht auch programmatisch.

Quick-Start

API-Key im Dashboard erstellen, in den Header packen, los geht's.

curl https://app.orconic.com/api/agents \
  -H "X-API-Key: $ORCONIC_API_KEY" \
  -H "Accept: application/json"

Authentication

Authentifizierung erfolgt über workspace-scoped API-Keys. Jeder Key ist an einen User und ein Workspace gebunden und unterliegt RBAC. Verloren gegangene Keys können jederzeit rotiert werden.

Header: X-API-Key: orc_live_…
Nur HTTPS. HTTP-Requests werden mit 426 abgewiesen.
Verwaltung im Dashboard unter Einstellungen → API-Keys.

Endpoint-Reference

Die vollständige, maschinenlesbare Definition findest du unter /api/openapi. Die interaktive Referenz ist weiter unten in dieser Seite eingebettet.

Workspaces & Users

Lese und verwalte den Workspace-Kontext, Mitgliedschaften und Rollen.

OpenAPI

Method	Path	Description
GET	/api/workspace	Aktiven Workspace inkl. Plan & Limits abrufen
GET	/api/workspace/members	Mitglieder mit Rollen auflisten
POST	/api/workspace/invites	Einladung versenden
GET	/api/me	Aktuellen API-Key-Owner abrufen

Agents

Erstelle, konfiguriere und führe Agents aus. Persistente Memory-Layer inklusive.

OpenAPI

Method	Path	Description
GET	/api/agents	Alle Agents im Workspace
POST	/api/agents	Neuen Agent anlegen
GET	/api/agents/{id}	Agent-Detail inkl. Tools & Triggern
PATCH	/api/agents/{id}	Agent-Konfiguration aktualisieren
POST	/api/agents/{id}/run	Agent synchron ausführen

Workflows + Runs

Multi-Step-Workflows orchestrieren, mit Runs als History-of-Record.

OpenAPI

Method	Path	Description
GET	/api/workflows	Workflows auflisten
POST	/api/workflows	Workflow anlegen
POST	/api/workflows/{id}/runs	Run starten
GET	/api/workflows/{id}/runs/{runId}	Run-Status & Step-Log

Inbox + Auto-Reply

Eingehende E-Mails, Klassifikation, Auto-Reply-Regeln und Threading.

OpenAPI

Method	Path	Description
GET	/api/inbox	Threads mit Filter (Status, Owner, Tag)
POST	/api/inbox/auto-reply	Auto-Reply-Regel erstellen
POST	/api/inbox/{threadId}/reply	Antwort als Mensch oder Agent senden

CRM (Leads / Deals / Customers / Pipeline)

Vollständiger CRM-Layer mit Pipeline-Stufen und Deal-Forecasting.

OpenAPI

Method	Path	Description
GET	/api/crm/leads	Leads inkl. Score & Owner
POST	/api/crm/leads	Lead anlegen oder upserten
GET	/api/crm/deals	Deals nach Stage
PATCH	/api/crm/deals/{id}	Deal aktualisieren
GET	/api/crm/pipeline	Pipeline-Snapshot mit Forecast

Integrations (per provider)

OAuth-Verbindungen, Provider-Status und Re-Authentifizierung.

OpenAPI

Method	Path	Description
GET	/api/integrations	Verbundene Provider auflisten
POST	/api/integrations/{provider}/connect	OAuth-Flow starten
DELETE	/api/integrations/{provider}	Verbindung trennen

Marketplace (install / uninstall)

Plugins und Templates installieren, konfigurieren und deinstallieren.

OpenAPI

Method	Path	Description
GET	/api/marketplace	Verfügbare Plugins
POST	/api/marketplace/{slug}/install	Plugin installieren
DELETE	/api/marketplace/{slug}	Plugin deinstallieren

Webhooks (inbound + outbound)

Inbound-URLs für Trigger und signierte Outbound-Webhooks an deine Systeme.

OpenAPI

Method	Path	Description
GET	/api/webhooks	Konfigurierte Outbound-Webhooks
POST	/api/webhooks	Outbound-Webhook registrieren
POST	/api/webhooks/inbound/{token}	Generischer Inbound-Endpoint (öffentlich)

Billing

Plan, Nutzung, Rechnungen und Self-Service-Portal via Stripe.

OpenAPI

Method	Path	Description
GET	/api/billing/usage	Aktuelle Nutzung & Limits
GET	/api/billing/invoices	Rechnungs-History
POST	/api/billing/portal	Stripe-Portal-Session erstellen

Rate-Limits

Limits sind pro Workspace, nicht pro Key. Jede Antwort enthält die aktuellen Werte als Response-Header.

Scope	Default	Header
Standard-Endpoints	1000 req/min	X-RateLimit-Limit / -Remaining / -Reset
Auth-Endpoints	100 req/min	X-RateLimit-Limit / -Remaining / -Reset

Webhook-Signing

Outbound-Webhooks tragen den Header X-Orconic-Signature — ein hex-encoded HMAC-SHA256 des rohen Request-Bodys mit deinem Webhook-Secret. Verifiziere ihn bei jedem Request, bevor du den Payload verarbeitest.

// Node — verify an incoming Orconic webhook
import crypto from "node:crypto";

function verify(secret, rawBody, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signatureHeader, "hex"),
  );
}

// header: X-Orconic-Signature

SDKs & Tooling

Node / TypeScript: npm install @orconic/sdk — source unter packages/orconic-sdk.
Python SDK — geplant für Q4 2026.
OpenAPI 3.1 Spec für jeden Generator: /api/openapi (YAML: /api/openapi?format=yaml).

Versionierung & Breaking-Changes: Changelog. Public-stable Endpunkte unter /api/v1/* — siehe v1-Surface.

v1 Public Surface (W3-A6)

Die stabilen, versionierten Endpunkte für Embed-Widgets, Programmatic-Chat und Skill-Aufrufe. Auth: API-Key (Bearer) oder Customer-Session-JWT.

POST/api/v1/conversationsConversation anlegen (idempotent über externalId)

GET/api/v1/conversations/{id}Conversation-State abrufen

POST/api/v1/conversations/{id}/messagesUser-Message + Agent-Reply (synchron)

POST/api/v1/agents/{slug}/executeAgent direkt ausführen

POST/api/v1/embed/sessionsCustomer-Session-JWT für Widget erstellen

GET/api/v1/skillsVerfügbare Skills auflisten

POST/api/v1/skills/{slug}/runSkill ausführen

Komplettes Embed-Quickstart: docs/embed-quickstart.md · API Getting-Started: API & Webhooks

Interactive Reference

Vollständige, navigierbare API-Referenz, gerendert mit Redoc direkt aus unserer OpenAPI-3.1-Spec.