Server API & webhooks

The Server API lets operators integrate their community with their own systems: manage members and approvals, schedule rooms, curate the directory, read usage, and receive events. It is served by the community server in the operator's deployment, so requests and data never leave the operator's environment.

ConventionsCopy Anchor Link

Base URL. https://<deployment.domain>/api/v1. Examples below use https://community.orbit.example/api/v1.

Authentication. Operator API keys, created in the admin console and sent as a bearer token. Each key has scopes — for example members:read, members:write, rooms:write, directory:write, usage:read — and is tied to the console user who created it for auditing.

curl https://community.orbit.example/api/v1/community \
  -H "Authorization: Bearer $SYMORVA_API_KEY"

Idempotency. Every POST accepts an Idempotency-Key header. Repeating a request with the same key and body returns the original result; the same key with a different body is rejected with idempotency_conflict.

Pagination. List endpoints take limit (1 to 100, default 20) and cursor, and return nextCursor until the last page.

Errors. Non-2xx responses share one envelope:

{
  "error": {
    "code": "forbidden",
    "message": "The API key lacks the members:write scope.",
    "requestId": "req_01JBX7Q4M9W8ZK2N5T3F6RVY0D"
  }
}

Concurrency. Resources edited by more than one operator carry a revision. Updates must send the revision they read; a stale revision returns 409 stale_revision instead of overwriting someone else's change.

ResourcesCopy Anchor Link

Endpoints of a disabled module return 403 module_disabled.

There is deliberately no endpoint that reads message content, creates an AI grant on a member's behalf, or moves a member's funds. Announcements are system messages: they originate on the server, are not end-to-end encrypted, and are labelled as system messages in apps.

Example: schedule a roomCopy Anchor Link

curl -X POST https://community.orbit.example/api/v1/rooms \
  -H "Authorization: Bearer $SYMORVA_API_KEY" \
  -H "Idempotency-Key: 6f1c2a3e-governance-2026-11-04" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Governance call",
    "hostId": "mem_8Q2K",
    "startsAt": "2026-11-04T10:00:00Z",
    "durationMinutes": 60,
    "broadcast": { "enabled": true, "maxAudience": 2000 }
  }'

{
  "id": "room_3VJ9",
  "title": "Governance call",
  "status": "scheduled",
  "mode": "large-room",
  "hostId": "mem_8Q2K",
  "startsAt": "2026-11-04T10:00:00Z",
  "durationMinutes": 60,
  "broadcast": { "enabled": true, "maxAudience": 2000 },
  "revision": "1"
}

maxAudience cannot exceed the manifest's modules.meetings.broadcast.maxAudience.

Example: read usageCopy Anchor Link

curl "https://community.orbit.example/api/v1/usage?unit=participant-minutes&from=2026-10-01&to=2026-11-01" \
  -H "Authorization: Bearer $SYMORVA_API_KEY"

{
  "data": [
    {
      "recordId": "use_01JBX8",
      "module": "meetings",
      "unit": "participant-minutes",
      "quantity": 1840,
      "windowStart": "2026-10-01T00:00:00Z",
      "windowEnd": "2026-10-02T00:00:00Z"
    }
  ],
  "nextCursor": "c_02"
}

WebhooksCopy Anchor Link

Modules emit events to the endpoints you register. Delivery is at least once: the same event can arrive more than once, and events can arrive out of order. Use the event id to deduplicate and the occurredAt timestamp, not arrival order, to sequence.

DeliveryCopy Anchor Link

Each delivery is an HTTPS POST with a JSON body and these headers:

Respond with any 2xx status within 10 seconds to acknowledge. Other responses and timeouts are retried with exponential backoff for up to 24 hours; after that the event is kept in the endpoint's failed-delivery list in the admin console and can be replayed.

Event envelopeCopy Anchor Link

{
  "id": "evt_01JBX9R2C4",
  "type": "chat.join_request.created",
  "community": "orbit-collective",
  "occurredAt": "2026-10-28T09:41:12Z",
  "data": {
    "requestId": "jr_5TQ1",
    "memberId": "mem_2B7X",
    "groupId": "grp_governance"
  }
}

Verifying signaturesCopy Anchor Link

The signature is an HMAC-SHA256 over the timestamp, a period and the raw request body, keyed with the endpoint's signing secret. Verify it before parsing the body, and reject timestamps outside a short tolerance window to prevent replay.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifySymorvaSignature(
  rawBody: string,
  header: string,
  secret: string,
  toleranceSeconds = 300,
): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Event catalogCopy Anchor Link

Field lists for each event are on the module pages. Events never contain message content, prompts, generated content, data released to partner apps, or key material. Subscribing an endpoint to an event of a disabled module is rejected.