hanzoai/openapi
2
0
Fork 0
Code Issues Pull Requests Actions Releases Activity

openapi: V8 · Open Edition — capabilities manifest + drop eval/operative dups (#26)

Browse Source 
- capabilities.yaml: THE registry — 8 domains, one capability = one name = one /v1/<name>
  = one spec. core + internal + collapsed + pending + review. merge.py's grouping source.
- info.version 1.0.0 -> 8.0.0 everywhere (routes stay /v1 — the contract is immutable;
  8.0.0 is the platform generation). Title carries 'V8 · Open Edition'.
- drop eval/ (pure dup of evals) + operative/ (computer-using-agent split: bot = the CUA,
  visor = the VM it runs on). hanzo.yaml regenerated.
This commit is contained in:
zeekay
2026-07-08 08:54:17 -07:00
committed by GitHub
parent 56ca5383e3
commit 4ab317f95f
72 changed files with 155 additions and 3330 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin/openapi.yaml
+1 -1
View File
@@ -15,7 +15,7 @@ info:
Reads use the `/v1` envelope `{ status, msg, data, data2 }` — `data` is the
payload, `data2` the total for list endpoints.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
affiliates/openapi.yaml
+1 -1
View File
@@ -35,7 +35,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
agents/openapi.yaml
+1 -1
View File
@@ -25,7 +25,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
ai/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service. API keys (`hk-...`) minted on hanzo.id
are accepted on these routes as well.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
analytics/openapi.yaml
+1 -1
View File
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: Hanzo Analytics API
version: 1.0.0
version: 8.0.0
description: Web analytics API for tracking website traffic, events, sessions, and generating reports.
contact:
name: Hanzo AI
app/openapi.yaml
+1 -1
View File
@@ -15,7 +15,7 @@ info:
`dist/`) or queues a git/CI build.
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
authors/openapi.yaml
+1 -1
View File
@@ -33,7 +33,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service. Admin routes require a global-admin
identity (fail-closed).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
authz/openapi.yaml
+1 -1
View File
@@ -44,7 +44,7 @@ info:
iam derives from the JWT.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
auto/openapi.yaml
+1 -1
View File
@@ -17,7 +17,7 @@ info:
for full schema definitions and detailed endpoint documentation.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
automations/openapi.yaml
+1 -1
View File
@@ -9,7 +9,7 @@ info:
in-process tasks engine; connector actions are also exposed as MCP tools at
`/v1/automations/mcp`. Every flow runs in the OWNER org's namespace; the org
is always server-derived from the validated principal, never a request body.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
base/openapi.yaml
+1 -1
View File
@@ -17,7 +17,7 @@ info:
`site_drafts` collection keyed by `(org, slug)`.
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
billing/openapi.yaml
+1 -1
View File
@@ -10,7 +10,7 @@ info:
another tenant's wallet. Bodies + status codes are forwarded from commerce
verbatim (e.g. `402` on `gpu-charge` when a card is required or prepaid is
insufficient).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
bot/openapi.yaml
+1 -1
View File
@@ -13,7 +13,7 @@ info:
pgvector for semantic skill search.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
capabilities.yaml
+84
View File
@@ -0,0 +1,84 @@
# capabilities.yaml — the ONE registry of Hanzo public capabilities.
#
# One and one way, by construction:
# • every openapi/<name>/openapi.yaml MUST appear here exactly once, in exactly
# one domain — merge.py FAILS the build on an orphan spec, an unlisted spec,
# or a name in two domains. Orthogonality is a build invariant, not a hope.
# • the route IS the identity: one capability = one name = one /v1/<name> = one
# <name>/openapi.yaml. No svc suffix, no singular/plural twins, no facade.
# • merge.py emits x-tagGroups from `domains` so Redoc/Scalar render the eight
# movements automatically. Docs + SDKs derive from hanzo.yaml — never hand-kept.
#
# version: the API path stays /v1 (the compatibility contract, immutable). The
# release/generation is V8 — info.version: 8.0.0 on hanzo.yaml + every spec.
edition: "V8 · Open Edition"
version: "8.0.0"
domains:
- id: identity
title: "Identity & Trust"
role: "who you are · what you may touch · where secrets live"
services: [iam, authz, kms, security, did, zt, guard]
- id: intelligence
title: "Intelligence"
role: "models · agents · evaluation — the mind of the cloud"
services: [ai, ml, engine, agents, evals, prompts, functions, exec, graph]
- id: data
title: "Data"
role: "the stores every capability writes to and reads from"
services: [storage, base, db, kv, vector]
- id: streams
title: "Streams"
role: "messaging · durable tasks · async orchestration"
services: [pubsub, mq, stream, tasks, notify, automations, flow, auto]
- id: observability
title: "Observability"
role: "see everything — telemetry · analytics · usage"
services: [o11y, analytics]
- id: commerce
title: "Commerce"
role: "the economy — meter · price · bill · reward"
services: [commerce, billing, pricing, plan, product, crm, referrals, affiliates, licensing, treasury, wallets]
- id: platform
title: "Platform"
role: "the cloud fabric — deploy · provision · route · host"
services: [cloud, platform, paas, provisioning, gateway, visor, edge, dns, registry, nexus]
- id: applications
title: "Applications"
role: "the user-facing surfaces built on all of the above"
services: [console, projects, git, team, templates, integrations, bot, chat, kb, search, websearch, authors, sites, tracker, framework]
# Core — governance that owns no single domain.
core: [admin, plugin]
# Internal — power the music, are not instruments. Excluded from /v1, SDKs, docs.
internal: [principal, goja, mpc, controlplane, metrics, audit]
# Collapsed — resolved duplicates / consolidations. merge.py asserts these have
# NO spec dir (they were removed), and records where the capability now lives.
collapsed:
eval: evals # pure dup — same /v1/evals
observe: o11y + console/settings # /v1/o11y facet → o11y; /v1/settings → console
operative: bot + visor # computer-using-agent split: bot = the CUA (@hanzo/bot), visor = the VM it runs on
s3: storage # renamed: storage is the capability, s3 the implementation
plans: plan # singular canonical
plugins: plugin
# Not-yet-scored — LIVE surfaces missing a spec. Author these to complete the set.
pending: [team, wallets, treasury, usage, fleet]
# Braids under review — same concern, different names? Verify before merging;
# do NOT silently consolidate (would lose capability). merge.py warns, not fails.
review:
app_vs_projects: "app (hanzo.app builds/deploys) vs projects (buildable/deployable sites) — likely ONE concern; fold app→projects?"
do_is_a_provider: "do (DigitalOcean VPCs/LBs) is a PROVIDER, not a capability — fold into provisioning/platform?"
workflow_cluster: "auto (Hanzo Auto engine) · automations (connector pieces) · flow — three workflow surfaces; decomplect to one?"
retrieval_cluster: "search vs kb (semantic) vs vector (store) — overlapping retrieval; is search distinct from kb?"
chat/openapi.yaml
+1 -1
View File
@@ -6,7 +6,7 @@ info:
MCP integration, agents, assistants, and RAG.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
cloud/openapi.yaml
+1 -1
View File
@@ -2,7 +2,7 @@ openapi: 3.1.0
info:
title: Hanzo Cloud API
description: Hanzo Cloud Backend API — AI model management, inference, and usage tracking.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
commerce/openapi.yaml
+1 -1
View File
@@ -24,7 +24,7 @@ info:
Tokens can be obtained via the OAuth2 password grant flow at `/auth`.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
console/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
Project-scoped API keys support project-level endpoints (traces, observations, scores, etc.).
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
crm/openapi.yaml
+1 -1
View File
@@ -8,7 +8,7 @@ info:
proxy to a NestJS backend. Tenant isolation is enforced server-side on every
request from the validated bearer owner claim; one tenant can never read or
mutate another's records.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
db/openapi.yaml
+1 -1
View File
@@ -19,7 +19,7 @@ info:
- Usage-based billing (compute CU-hours, storage GB-hours, data transfer)
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
did/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
- Full identity change history and audit trail
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
dns/openapi.yaml
+1 -1
View File
@@ -19,7 +19,7 @@ info:
- Full DNS record type support (A, AAAA, CNAME, MX, TXT, SRV, NS, SOA, CAA)
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
do/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
Fail-closed: absent `DO_API_TOKEN` the surface mounts but every op returns
503; it never fabricates a resource.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
edge/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
- Built-in metrics and log tailing
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
engine/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
- **Serve**: Model serving endpoint management with autoscaling
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
eval/openapi.yaml
-1186
View File
File diff suppressed because it is too large Load Diff
evals/openapi.yaml
+1 -1
View File
@@ -20,7 +20,7 @@ info:
Backends are pluggable: the native Hanzo engine is the default; DigitalOcean
GenAI evaluations can be selected as an alternate backend per run.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
exec/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
AUTH: this surface is called server-side by the chat node process with a
shared service key on the `X-API-Key` header (NOT a user JWT — the gateway
bypasses these paths). An unset key fails closed (503); a wrong key is 401.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
flow/openapi.yaml
+1 -1
View File
@@ -11,7 +11,7 @@ info:
Integrates with the Hanzo ecosystem (Hanzo MQ, Hanzo KV).
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
framework/openapi.yaml
+1 -1
View File
@@ -15,7 +15,7 @@ info:
Everything is org-scoped: the org is the validated tenant, so one org's
schema and data are invisible to another.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
functions/openapi.yaml
+1 -1
View File
@@ -10,7 +10,7 @@ info:
its triggers, deployments, secrets, invocations, and metrics. Tenant
isolation is enforced server-side from the validated bearer `owner` claim
(HIP-0026).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
gateway/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
- DNS proxy routes
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
git/openapi.yaml
+1 -1
View File
@@ -13,7 +13,7 @@ info:
`.../git-receive-pack`) speak the native Git wire protocol so
`git clone` / `git fetch` / `git push` work against
`https://api.hanzo.ai/v1/git/<org>/<repo>.git`.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
graph/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
fabricates a row. An unreachable upstream surfaces an honest 502; a
reachable-but-empty upstream returns an empty list. Every route requires a
validated IAM principal (HIP-0026).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
guard/openapi.yaml
+1 -1
View File
@@ -19,7 +19,7 @@ info:
- **PTY Wrapper** (guard-wrap): wraps CLI tools with filtering
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
hanzo.yaml
+2 -1410
View File
File diff suppressed because it is too large Load Diff
iam/openapi.yaml
+1 -1
View File
@@ -2,7 +2,7 @@ openapi: 3.1.0
info:
title: Hanzo IAM API
description: Hanzo IAM — Identity and Access Management (OAuth2, OIDC, SAML, Web3)
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
integrations/openapi.yaml
+1 -1
View File
@@ -11,7 +11,7 @@ info:
(events + slash commands) and the per-user account-link browser flow — those
legs authenticate INSIDE the handler (HMAC-signed body / `__Host-` cookies +
state), not with a bearer token.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
kb/openapi.yaml
+1 -1
View File
@@ -15,7 +15,7 @@ info:
Every route is org-scoped to the validated tenant — a caller can only search or
connect its own knowledge.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
kms/openapi.yaml
+1 -1
View File
@@ -10,7 +10,7 @@ info:
secrets, PKI, integrations, and audit logging.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
kv/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
- Append-only streams for event sourcing
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
merge.py
+2 -2
View File
@@ -127,7 +127,7 @@ def main():
out = {
"openapi": "3.1.0",
"info": {
"title": "Hanzo Cloud — Unified API",
"title": "Hanzo Cloud — Unified API (V8 · Open Edition)",
"description": (
"The single unified OpenAPI surface for ALL Hanzo services, "
"aggregated from the per-service specs. Every route is "
@@ -135,7 +135,7 @@ def main():
"canonical categories (see CAPABILITIES.md). Regenerated by "
"merge.py — edit the per-service <svc>/openapi.yaml, not this file."
),
"version": "1.0.0",
"version": "8.0.0",
"contact": {"name": "Hanzo AI", "url": "https://hanzo.ai", "email": "[email protected]"},
"license": {"name": "Proprietary"},
},
ml/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
- Direct deployment to Hanzo Cloud
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
mq/openapi.yaml
+1 -1
View File
@@ -65,7 +65,7 @@ info:
multi-tenancy, IAM integration, and KMS-managed secrets.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
email: [email protected]
nexus/openapi.yaml
+1 -1
View File
@@ -3,7 +3,7 @@ info:
title: Hanzo Nexus API
description: Hanzo Nexus is a knowledge base and RAG (Retrieval-Augmented Generation) platform. It provides document management,
vector embeddings, semantic search, and AI-powered question answering across organizational knowledge stores.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
notify/openapi.yaml
+1 -1
View File
@@ -52,7 +52,7 @@ info:
token authenticates every Hanzo service.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
o11y/openapi.yaml
+1 -1
View File
@@ -19,7 +19,7 @@ info:
- **Alerts**: Rule-based alerting with multi-channel notifications
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
observe/openapi.yaml
+1 -1
View File
@@ -25,7 +25,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
operative/openapi.yaml
-665
View File
@@ -1,665 +0,0 @@
openapi: 3.1.0
info:
title: Hanzo Operative API
description: 'Hanzo Operative is a computer-use agent that allows Claude to interact with
a desktop environment via screenshot, mouse, keyboard, bash, and file-editing
tools. It runs inside a Docker container with X11/Xvfb and exposes a Streamlit
UI for human interaction, an HTTP API for configuration, and WebSocket-based
VNC for live desktop viewing.
The API provides endpoints for managing agent sessions, executing computer-use
tasks, retrieving screenshots, and configuring the operative environment.
'
version: 1.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
email: [email protected]
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://operative.hanzo.ai
description: Operative Production
- url: https://api.hanzo.ai
description: Hanzo Gateway (via api.hanzo.ai/v1/operative/*)
security:
- BearerAuth: []
tags:
- name: Sessions
description: Manage operative agent sessions
- name: Tasks
description: Submit and monitor computer-use tasks
- name: Computer
description: Direct computer interaction (screenshot, mouse, keyboard)
- name: Tools
description: Tool execution (bash, file editor)
- name: Configuration
description: Environment and agent configuration
paths:
/v1/operative/sessions:
post:
operationId: createSession
summary: Create a new operative session
description: 'Creates a new agent session with the specified model, provider, and
configuration. Returns a session ID for subsequent interactions.
'
tags:
- Sessions
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
responses:
'201':
description: Session created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
get:
operationId: listSessions
summary: List all active sessions
tags:
- Sessions
parameters:
- name: status
in: query
schema:
type: string
enum:
- active
- completed
- failed
- name: limit
in: query
schema:
type: integer
default: 20
- name: offset
in: query
schema:
type: integer
default: 0
responses:
'200':
description: List of sessions
content:
application/json:
schema:
type: object
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/Session'
total:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
/v1/operative/sessions/{sessionId}:
parameters:
- $ref: '#/components/parameters/SessionId'
get:
operationId: getSession
summary: Get session details
tags:
- Sessions
responses:
'200':
description: Session details
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteSession
summary: Terminate and delete a session
tags:
- Sessions
responses:
'204':
description: Session terminated
'404':
$ref: '#/components/responses/NotFound'
/v1/operative/sessions/{sessionId}/messages:
parameters:
- $ref: '#/components/parameters/SessionId'
post:
operationId: sendMessage
summary: Send a message to the operative agent
description: 'Sends a user message to the agent, which triggers the sampling loop.
The agent will process the message, potentially use tools (computer,
bash, editor), and return a response with any tool results.
'
tags:
- Tasks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageRequest'
responses:
'200':
description: Agent response with tool results
content:
application/json:
schema:
$ref: '#/components/schemas/AgentResponse'
'404':
$ref: '#/components/responses/NotFound'
get:
operationId: getMessages
summary: Get conversation history for a session
tags:
- Tasks
responses:
'200':
description: Conversation messages
content:
application/json:
schema:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
/v1/operative/sessions/{sessionId}/screenshot:
parameters:
- $ref: '#/components/parameters/SessionId'
get:
operationId: takeScreenshot
summary: Take a screenshot of the current desktop
tags:
- Computer
responses:
'200':
description: Screenshot captured
content:
application/json:
schema:
$ref: '#/components/schemas/ScreenshotResult'
image/png:
schema:
type: string
format: binary
/v1/operative/sessions/{sessionId}/computer:
parameters:
- $ref: '#/components/parameters/SessionId'
post:
operationId: computerAction
summary: Execute a computer action
description: 'Execute a direct computer interaction action such as mouse clicks,
keyboard input, scrolling, or taking a screenshot.
'
tags:
- Computer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ComputerActionRequest'
responses:
'200':
description: Action result with optional screenshot
content:
application/json:
schema:
$ref: '#/components/schemas/ToolResult'
/v1/operative/sessions/{sessionId}/bash:
parameters:
- $ref: '#/components/parameters/SessionId'
post:
operationId: executeBash
summary: Execute a bash command
tags:
- Tools
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BashRequest'
responses:
'200':
description: Command output
content:
application/json:
schema:
$ref: '#/components/schemas/ToolResult'
/v1/operative/sessions/{sessionId}/edit:
parameters:
- $ref: '#/components/parameters/SessionId'
post:
operationId: editFile
summary: Execute a file editing command
tags:
- Tools
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EditRequest'
responses:
'200':
description: Edit result
content:
application/json:
schema:
$ref: '#/components/schemas/ToolResult'
/v1/operative/sessions/{sessionId}/reset:
parameters:
- $ref: '#/components/parameters/SessionId'
post:
operationId: resetSession
summary: Reset the session environment
description: 'Resets the desktop environment (kills Xvfb, tint2) and restarts all
services. Clears conversation state.
'
tags:
- Sessions
responses:
'200':
description: Session reset successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
/v1/operative/env-config.json:
get:
operationId: getEnvConfig
summary: Get environment configuration
description: Returns runtime endpoint configuration for the UI.
tags:
- Configuration
security: []
responses:
'200':
description: Environment configuration
content:
application/json:
schema:
$ref: '#/components/schemas/EnvConfig'
/health:
get:
operationId: getHealth
summary: Health check
tags:
- Configuration
security: []
responses:
'200':
description: Service is healthy
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: ok
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Bearer JWT issued by Hanzo IAM (https://hanzo.id). Discovery: https://hanzo.id/.well-known/openid-configuration.
Obtain via /v1/iam/auth/login, /oauth/token, or the API key UI on hanzo.id.'
parameters:
SessionId:
name: sessionId
in: path
required: true
schema:
type: string
format: uuid
description: Unique session identifier
responses:
BadRequest:
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
CreateSessionRequest:
type: object
required:
- provider
properties:
provider:
type: string
enum:
- anthropic
- bedrock
- vertex
description: API provider to use
model:
type: string
description: Model name (defaults to provider default)
example: claude-3-7-sonnet-20250219
apiKey:
type: string
description: API key for the provider (if not set via env)
systemPromptSuffix:
type: string
description: Extra instructions appended to the system prompt
toolVersion:
type: string
enum:
- computer_use_20241022
- computer_use_20250124
default: computer_use_20250124
description: Tool version to use
maxTokens:
type: integer
default: 128000
description: Maximum output tokens
thinkingBudget:
type: integer
description: Token budget for thinking (null to disable)
onlyNMostRecentImages:
type: integer
default: 1
description: Number of recent screenshots to send to model
tokenEfficientToolsBeta:
type: boolean
default: false
description: Enable token-efficient tools beta flag
displayWidth:
type: integer
default: 1024
description: Virtual display width in pixels
displayHeight:
type: integer
default: 768
description: Virtual display height in pixels
Session:
type: object
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- active
- completed
- failed
provider:
type: string
enum:
- anthropic
- bedrock
- vertex
model:
type: string
toolVersion:
type: string
messageCount:
type: integer
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
SendMessageRequest:
type: object
required:
- content
properties:
content:
type: string
description: User message text
AgentResponse:
type: object
properties:
messages:
type: array
items:
$ref: '#/components/schemas/Message'
toolResults:
type: array
items:
$ref: '#/components/schemas/ToolResult'
Message:
type: object
properties:
role:
type: string
enum:
- user
- assistant
- tool
content:
oneOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/ContentBlock'
timestamp:
type: string
format: date-time
ContentBlock:
type: object
properties:
type:
type: string
enum:
- text
- tool_use
- tool_result
- thinking
- image
text:
type: string
thinking:
type: string
id:
type: string
description: Tool use ID
name:
type: string
description: Tool name (computer, bash, str_replace_editor)
input:
type: object
description: Tool input parameters
toolUseId:
type: string
description: Reference to the tool_use block
content:
type: string
description: Tool result content
isError:
type: boolean
base64Image:
type: string
format: byte
description: Base64-encoded PNG screenshot
ComputerActionRequest:
type: object
required:
- action
properties:
action:
type: string
enum:
- key
- type
- mouse_move
- left_click
- left_click_drag
- right_click
- middle_click
- double_click
- triple_click
- screenshot
- cursor_position
- left_mouse_down
- left_mouse_up
- scroll
- hold_key
- wait
description: The computer action to perform
text:
type: string
description: Text for key/type actions, modifier key for scroll
coordinate:
type: array
items:
type: integer
minItems: 2
maxItems: 2
description: '[x, y] pixel coordinates for mouse actions'
scrollDirection:
type: string
enum:
- up
- down
- left
- right
description: Scroll direction (for scroll action)
scrollAmount:
type: integer
description: Number of scroll clicks
duration:
type: number
description: Duration in seconds (for hold_key, wait actions)
key:
type: string
description: Modifier key to hold during click actions
BashRequest:
type: object
properties:
command:
type: string
description: Bash command to execute
restart:
type: boolean
default: false
description: Restart the bash session
EditRequest:
type: object
required:
- command
- path
properties:
command:
type: string
enum:
- view
- create
- str_replace
- insert
- undo_edit
description: Editor command to execute
path:
type: string
description: Absolute file path
fileText:
type: string
description: File content (for create command)
oldStr:
type: string
description: String to find (for str_replace command)
newStr:
type: string
description: Replacement string (for str_replace and insert commands)
insertLine:
type: integer
description: Line number to insert at (for insert command)
viewRange:
type: array
items:
type: integer
minItems: 2
maxItems: 2
description: '[startLine, endLine] range to view'
ToolResult:
type: object
properties:
output:
type: string
description: Standard output text
error:
type: string
description: Error message if the tool failed
base64Image:
type: string
format: byte
description: Base64-encoded PNG screenshot
system:
type: string
description: System message (e.g. tool restart notice)
ScreenshotResult:
type: object
properties:
base64Image:
type: string
format: byte
description: Base64-encoded PNG of the current desktop
width:
type: integer
height:
type: integer
EnvConfig:
type: object
properties:
APP_ENDPOINT:
type: string
example: operative-app.hanzo.ai
VNC_ENDPOINT:
type: string
example: operative-vnc.hanzo.ai
Error:
type: object
properties:
status:
type: string
example: error
message:
type: string
code:
type: string
paas/openapi.yaml
+1 -1
View File
@@ -21,7 +21,7 @@ info:
- Tekton CI/CD pipelines
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
plan/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
gateway-minted identity (`X-Org-Id`, HIP-0026) as the tenant so a reseller
org sees its own catalog overrides; an anonymous or forged org falls back to
the public `hanzo` default. Responses are the bundle's catalog JSON.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
platform/openapi.yaml
+1 -1
View File
@@ -8,7 +8,7 @@ info:
\ deployment orchestration,\n authenticated via Bearer JWT.\n\n## Authentication\n\nAll endpoints (except those marked\
\ public) require:\n\n- Bearer JWT issued by Hanzo IAM (https://hanzo.id) in the\n `Authorization` header, or\n- Session\
\ cookie established via the platform web UI after IAM login.\n"
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
plugin/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
pricing/openapi.yaml
+1 -1
View File
@@ -1,7 +1,7 @@
openapi: 3.1.0
info:
title: Hanzo Pricing API
version: 1.0.0
version: 8.0.0
description: 'Unified pricing API for the Hanzo AI platform. Serves real-time pricing
for AI models (376+), cloud VM plans, GPU tiers, subscription plans,
product/openapi.yaml
+1 -1
View File
@@ -40,7 +40,7 @@ info:
unset key fails closed with HTTP 503.
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
projects/openapi.yaml
+1 -1
View File
@@ -24,7 +24,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
prompts/openapi.yaml
+1 -1
View File
@@ -9,7 +9,7 @@ info:
every query. Creating a prompt whose name already exists appends a new
version — real, inspectable history. The store holds template text + taxonomy
only, never a secret.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
provisioning/openapi.yaml
+1 -1
View File
@@ -38,7 +38,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
pubsub/openapi.yaml
+1 -1
View File
@@ -25,7 +25,7 @@ info:
- WebSocket transport for browser clients
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
referrals/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
Authentication: Bearer JWT issued by Hanzo IAM (`https://hanzo.id`). The same
token authenticates every Hanzo service. The customer routes are scoped to the
caller's org server-side; the `/v1/admin/referrals*` routes require global-admin.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
registry/openapi.yaml
+1 -1
View File
@@ -17,7 +17,7 @@ info:
- Storage quota management per project
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
s3/openapi.yaml
+1 -1
View File
@@ -23,7 +23,7 @@ info:
- OIDC SSO via hanzo.id for console access
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
search/openapi.yaml
+1 -1
View File
@@ -31,7 +31,7 @@ info:
- Webhooks for event notifications
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
security/openapi.yaml
+1 -1
View File
@@ -7,7 +7,7 @@ info:
the engine runs its detection ruleset over them in memory (raw content is
never stored), and persists a per-org scan summary plus redacted findings.
Every route is tenant-scoped to the caller's validated org.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
stream/openapi.yaml
+1 -1
View File
@@ -25,7 +25,7 @@ info:
- Horizontal scaling behind load balancer
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
tasks/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
(the engine JSON API, `/mcp`, `/events`) is identity-gated — a request
without a gateway-validated principal (X-User-Id) is refused (403). The
engine is resolved lazily, so requests before it is live return 503.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
templates/openapi.yaml
+1 -1
View File
@@ -9,7 +9,7 @@ info:
catalog with no external dependency. Reference content, not org data — a user
forks a template into a project via the deploy flow, not by mutating this
catalog.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
tracker/openapi.yaml
+1 -1
View File
@@ -9,7 +9,7 @@ info:
(`KEY-<number>`). Tenant isolation is enforced server-side on every
request from the validated bearer `owner` claim (HIP-0026) — never a
client-supplied header.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
vector/openapi.yaml
+1 -1
View File
@@ -17,7 +17,7 @@ info:
- Hybrid search (vector + keyword)
'
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
visor/openapi.yaml
+1 -1
View File
@@ -8,7 +8,7 @@ info:
compute). Every resource is scoped to the caller's org from the validated IAM
owner claim; a caller only ever reads or mutates their OWN tenant's compute.
A Bot is a composition: a `kind=bot` machine plus an agent binding.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
websearch/openapi.yaml
+1 -1
View File
@@ -12,7 +12,7 @@ info:
AUTH: both surfaces require the shared service key (KMS-sourced) and fail
closed — search via the `X-API-Key` header, scrape via `Authorization:
Bearer`. An unset key returns 503; a missing/mismatched key returns 401.
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai
zt/openapi.yaml
+1 -1
View File
@@ -9,7 +9,7 @@ info:
filtered to the caller's org by the `org-<org>` role attribute from the
validated IAM owner claim. Fail-closed: absent the ZT service credential the
routes mount but every op returns 503 (never a fabricated resource).
version: 1.0.0
version: 8.0.0
contact:
name: Hanzo AI
url: https://hanzo.ai