> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opengeni.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP API overview

> The shape of the public OpenGeni HTTP API behind the SDK.

OpenGeni's public contract is a workspace-scoped HTTP API. Most integrations should use [`@opengeni/sdk`](/reference/sdk), which wraps these routes with types, retries, and stream recovery. Every request authenticates first (see [Authentication](/reference/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](/integrate/production#keep-sdk-and-server-compatible).

The full route list is in the repository's [HTTP API overview](https://github.com/Cloudgeni-ai/opengeni/blob/main/docs/http-api.md).