API endpoints

Overview

A running QiForge oracle exposes a REST + WebSocket surface. Most routes require a UCAN delegation header; some (/health, /docs, plus anything declared in getAuthExcludedRoutes() or authExcludedRoutes) are public.

The Swagger UI at /docs is generated from the running app's controllers — open it in a browser for the live, deployment-specific reference.

Authentication

Protected routes authenticate with a user-signed UCAN invocation, plus an optional delegation for downstream authorization. This is the same model the Identity and auth guide describes.

When neither an invocation nor a delegation is present, protected routes return 401:

Missing UCAN authentication: provide Authorization: Bearer <invocation> with X-Auth-Type: ucan, or an x-ucan-delegation header

A malformed or expired invocation returns 401 Invalid UCAN invocation. Public routes ignore auth headers and don't validate them.

CORS

CORS_ORIGIN controls allowed origins (wildcard * is the default; specific origins enable credentials).

Allowed request headers:

Content-Type, Authorization, x-ucan-delegation,
x-matrix-access-token, x-matrix-homeserver,
x-did, x-request-id, x-auth-type, x-timezone

Allowed methods: GET, POST, PUT, DELETE, PATCH, OPTIONS.

Exposed response headers: X-Request-Id.

Public routes

Plus any route returned by a plugin's getAuthExcludedRoutes() or by createOracleApp({ authExcludedRoutes }).

Protected routes

All of these require the auth headers above. For the request/response schemas of your specific deployment, hit GET /docs.

Sessions (/sessions)

Messages (/messages)

POST /messages/:sessionId body (SendMessageDto):

Streaming is a flag on this single endpoint — there is no separate /stream route.

Delegation (/delegation)

A user→oracle UCAN delegation lets the oracle mint downstream-service invocations on the user's behalf. The client-sdk re-auth popup POSTs here; a non-React client must implement this to complete the authorization flow.

POST /delegation body (StoreDelegationDto):

Other modules

• SubscriptionModule — credit/subscription gating middleware (active when the credits plugin is loaded).
• WsModule — the WebSocket gateway (see below).

Plugins contribute more routes via getNestModules() — e.g. SlackModule (Slack webhooks), UserPreferencesController (/user-preferences), and claim-processing cron endpoints. The Swagger UI at /docs is generated from your app's controllers — including plugin and host routes — so it's always the authoritative, deployment-specific list.

WebSocket

The oracle runs a socket.io gateway on namespace /. Plugins emit typed events via rtCtx.emit; the framework forwards them to the client over the session's room.

Handshake

Connect with a sessionId query param and a UCAN in auth. A handshake with no sessionId, or with no valid UCAN, is disconnected immediately.

import { io } from 'socket.io-client';

const socket = io('https://your-oracle.example', {
  query: { sessionId },
  auth: {
    invocation,      // primary: the user-signed UCAN invocation
    ucanDelegation,  // fallback: a bare delegation (pre-invocation clients)
  },
});

The server validates the invocation (primary) or delegation (fallback) the same way HTTP requests do; the authenticated DID is the validated invoker, never the query value. On success it emits connected.

Server → client events

Client → server events

Event payload types are currently Record<string, unknown> and may be tightened in future runtime versions. The @ixo/oracles-client-sdk React SDK handles this handshake, parses these events, and renders them.

Client SDK

For frontend integration, use @ixo/oracles-client-sdk — it handles the SSE / WebSocket protocol, UCAN delegation, and event parsing. See Client SDK.

Related references

• Identity and auth — the UCAN flow.
• Plugin HTTP endpoints — adding your own routes.
• Client SDK — React integration.