HTTP API overview

OpenGeni’s public contract is a workspace-scoped HTTP API. Most integrations should use @opengeni/sdk, which wraps these routes with types, retries, and stream recovery. Every request authenticates first (see Authentication); protected routes include the workspace id in the path and are authorized against it.

Discovery

Route	Returns
`GET /healthz`	Liveness and the server version
`GET /v1/config/client`	Deployment features and client configuration, including version
`GET /v1/access/me`	The caller’s organization and workspace grants

Main route families

Family	Routes
Organizations	`/v1/organizations/:organizationId/...`: API keys, members, workspaces, organization-wide session lists
External workspaces	`PUT /v1/workspaces/external` (idempotent `ensureWorkspace`)
Sessions	`POST /v1/workspaces/:workspaceId/sessions`, `GET .../sessions/:sessionId`
Events	`GET .../sessions/:sessionId/events` (replay), `POST .../events` (messages, decisions, control)
Live stream	`GET .../sessions/:sessionId/events/stream` (Server-Sent Events, resumable by sequence)
Goals	`GET`, `PATCH`, and `DELETE` on `.../sessions/:sessionId/goal`
Files	Upload begin and complete, download URLs
Scheduled tasks	`/v1/workspaces/:workspaceId/scheduled-tasks/...`
Automations	`/v1/workspaces/:workspaceId/automations/...`, and the public `POST /v1/webhooks/automations/:endpointId`
Integrations	`/v1/workspaces/:workspaceId/integrations/...` (preview, install, uninstall)
Connected Machines	`/v1/workspaces/:workspaceId/enrollments/...`

Streaming

The event stream is Server-Sent Events. Every event has a contiguous sequence number, so a client can reconnect with the last sequence it saw and backfill any gap from the replay route. Postgres is the source of truth; the stream only fans out what was already written. Configure proxies with buffering disabled and read timeouts of at least an hour.

Compatibility

Within a major version, the API only grows: clients ignore unknown response fields and event types, and servers ignore unknown request fields. See Going to production. The full route list is in the repository’s HTTP API overview.

Get started

Build

Concepts

Guides

Reference

Examples

Further reading

HTTP API overview

Discovery

Main route families

Streaming

Compatibility

​Discovery

​Main route families

​Streaming

​Compatibility

Discovery

Main route families

Streaming

Compatibility