API

Everything the Opereo AI UI does goes through this API — it is not a separate facade, so what you can click you can curl. That is also what makes Opereo AI a control plane for platforms that deploy and manage agents for their own users: one org-scoped key drives the full lifecycle, and your users never need an Opereo AI account. Platform resources (projects, engines, templates, your organization, API keys) have their own namespaces; engine operations are namespaced by engine kind, and today that means Hermes:

• /api/projects, /api/templates, /api/org, /api/keys, … — the platform
• GET /api/engines/{engineId} — what an engine is, whatever its kind
• /api/hermes/{engineId}/… — every Hermes operation

Authentication

Two credentials work on every endpoint:

• An API key — create one in Settings → API keys (org admins only). Keys are org-scoped: one key manages every project and engine the organization owns. The full key is shown once at creation and stored hashed.
• Your browser session — the app itself calls these endpoints with your Clerk session, so anything you can do signed in, the API does too.

curl -H "Authorization: Bearer fl_..." \
  https://your-opereo.example/api/engines/$ENGINE_ID

The engine id is a UUID — it's in the URL (?engine=...) when you open an engine from the sidebar.

Errors

Every failure is JSON: { "error": "message" } with a meaningful status — 400 invalid body or an engine kind that doesn't support the resource · 401 missing or invalid credentials · 403 not yours to touch · 404 unknown resource (including ones owned by another org) · 409 a name or address is already taken · 424 the engine or an upstream service failed (box down, unknown profile, …).

Projects

A project groups engines. Creating one is instant and provisions nothing — add engines to it with POST /api/hermes.

Engines

Engine creation is asynchronous. The row lands as status: "creating"; poll GET /api/projects/{projectId}/engines until it is ready, or failed with the reason in error. Hetzner takes ~2–3 min, Railway ~1 min, Upstash ~25 s.

Engine creation is kind-specific (POST /api/hermes); future engine kinds get their own namespace root.

Agents

name is a free-text display name (1–64 characters), and description allows up to 500 characters. Creating or cloning generates a separate internal Hermes slug. Updating an agent saves both fields together in profile.yaml; it does not rename its directory. The returned id remains stable, including when the default profile's display name changes.

curl -X POST -H "Authorization: Bearer fl_..." -H "Content-Type: application/json" \
  -d '{ "name": "researcher", "description": "Finds and summarizes sources" }' \
  https://your-opereo.example/api/hermes/$E/profiles

Identity

The agent's SOUL — its standing instructions.

Chat & sessions

POST /api/hermes/{e}/chat?profile={p} streams a conversation turn (AI SDK UI-message stream). Send { "messages": [...], "id": "<session id>" } — the id names the engine-side session, created on first use and resumed forever after.

Models

Providers

Environment

The agent's environment variables — the profile's .env on the box. Everything Hermes reads from the environment lives here: provider keys, tool credentials, platform tokens.

Names are UPPER_SNAKE_CASE. The gateway reads its environment once at start, so writes and deletes restart it — batch related keys into one PUT. channelManaged: true marks a platform credential owned by a channel (TELEGRAM_BOT_TOKEN, API_SERVER_KEY, …); connect those through Channels, which enables the platform alongside the value — a raw env write sets the token but leaves the platform off.

Reveals are throttled and audit-logged by the box: five per 30 seconds per engine. A sixth answers 424 with the box's message. Fine for a person, wrong for a loop.

curl -X PUT -H "Authorization: Bearer fl_..." -H "Content-Type: application/json" \
  -d '{ "values": { "FIRECRAWL_API_KEY": "fc-…", "EXA_API_KEY": "…" } }' \
  https://your-opereo.example/api/hermes/$E/profiles/$P/env

curl -X POST -H "Authorization: Bearer fl_..." \
  https://your-opereo.example/api/hermes/$E/profiles/$P/env/FIRECRAWL_API_KEY/reveal

Skills

Skill names may contain slashes (category/name) and go in the path as-is.

Install body — local content or a hub reference:

{ "name": "greeting", "description": "Says hi properly",
  "local": { "content": "---\nname: greeting\n---\n\nAlways greet warmly.", "files": [] },
  "hub": null }

The registry (search before you install):

Channels

Automations

Integrations

Engine access

Publishing & templates

An agent snapshots into a portable payload (identity, skills, automations, connected integrations and channels); publishing puts that payload on the marketplace; installing turns it back into a live agent.

Automation templates

Organization

Admin only — an API key counts as an admin.

API keys

Admin only. Only a hash is stored — the full key appears once, in the create response.

Your profile

PATCH /api/me — { firstName, lastName, imageUrl? } → { ok }. Session only: an API key is an organization credential, not a person, so this endpoint rejects it.