API Reference

One gateway, every shape. Pick your preferred API and start building.

Full-featured first-party API with block-based payloads, runs, tool loops, and live audio.

Key Concepts

Sessions, context modes, calls, runs, data layer access, and assessments define the shared gateway model across native and compatibility API shapes.

Sessions

universal

Every call — regardless of API shape — creates a session. Sessions are the universal continuity handle, grouping lineage, history, and observability.

Context Modes

default: stateful

Stateful keeps context server-side and appends new input. Stateless is caller-supplied full-context execution — durable, session-bound, and explicit.

Calls

all shapes

A call is one logical model invocation. Every API shape supports calls.

Runs

native only

A run is an orchestrated execution over one or more calls — with tool loops, checkpoints, interrupt, and resume.

Data Layer

native only

Structured queries over sessions, runs, and calls via explicit query sources, saved views, declared facets, and exports.

Assessments

native only

Machine quality scores attached to runs and calls, plus feedback signals and assessment profiles.

Base URL

All API shapes route through https://api.rhone.dev with shape-specific base paths.

https://api.rhone.dev/v1

Authentication

All requests require a bearer token in the Authorization header.

shell
1Authorization: Bearer rhone_sk_...

Endpoints

The native VAI surface includes sessions, calls, runs, tools, data layer, annotations, assessments, hosted history, and admin endpoints. Compatibility surfaces expose provider-shaped call endpoints plus shared gateway websocket transport.

Sessions

POST/v1/sessionsCreate a new session
GET/v1/sessions/{id}Get session details
PATCH/v1/sessions/{id}Update session defaults
POST/v1/sessions/{id}:set-instructionsSet session-scoped instructions
POST/v1/sessions/{id}:set-phaseSet the active phase
POST/v1/sessions/{id}:branchBranch a session (with optional transforms)
POST/v1/sessions/{id}:pausePause a session
POST/v1/sessions/{id}:resumeResume a paused session
POST/v1/sessions/{id}:snapshotCreate a named snapshot

Calls

POST/v1/callsCreate a blocking call
POST/v1/calls:streamCreate a streaming call (SSE)
GET/v1/calls/{id}Get call details

Runs

POST/v1/runsCreate a blocking run
POST/v1/runs:streamCreate a streaming run (SSE)
GET/v1/runs/{id}Get run details
POST/v1/runs/{id}:interruptInterrupt a running execution
POST/v1/runs/{id}:resumeResume an interrupted run
POST/v1/runs/{id}:cancelCancel a run

Tool Execution & Checkpoints

POST/v1/tool-executions/{id}:resultSubmit a tool result
GET/v1/tool-executions/{id}Get tool execution details
POST/v1/checkpoints/{id}:resolveResolve a checkpoint gate
POST/v1/checkpoints/{id}:cancelCancel a checkpoint

Browser

GET/v1/sessions/{id}/browserGet the session browser binding
GET/v1/sessions/{id}/browser/tabsList browser tabs for a session
POST/v1/sessions/{id}:enable-browserEnable a hosted or client-local browser binding
POST/v1/sessions/{id}:disable-browserDisable browser binding and optionally schedule provider cleanup
POST/v1/sessions/{id}/browser:handoffCreate a hosted browser handoff, optionally checkpoint-backed
POST/v1/sessions/{id}/browser:handoff:revokeRevoke the latest active browser handoff

WebSocket & Live Audio

GET/v1/wsNative WebSocket transport
GET/v1/liveLive audio WebSocket

Session Reads

GET/v1/sessionsList sessions
GET/v1/sessions/{id}/timelineSession history projection — all committed events
GET/v1/sessions/{id}/blocksSession continuity projection — active head
GET/v1/sessions/{id}/instructionsCurrent session instruction set
GET/v1/sessions/{id}/runsList runs in session
GET/v1/sessions/{id}/lineageSession lineage and branch graph
GET/v1/runs/{id}/timelineRun timeline with tool activity
GET/v1/runs/{id}/blocksAll durable blocks for a run
GET/v1/runs/{id}/effective-requestResolved request after routing

Data Layer

GET/v1/data/sourcesList query sources
GET/v1/data/sources/{source}Get source field catalog
POST/v1/data/sources/{source}/queryStructured query over a source
POST/v1/data/sources/{source}/aggregateAggregate report over a source
POST/v1/data/viewsCreate a saved view
GET/v1/data/views/{id}/resultsGet saved view results
POST/v1/data/facetsDeclare an indexed metadata facet
POST/v1/data/exportsCreate a data export
POST/v1/data/sinksCreate a data sink for continuous delivery
POST/v1/data/subscriptionsSubscribe to view/source changes

Annotations

POST/v1/annotationsCreate an annotation (label, review, note)
GET/v1/annotationsList annotations by target
GET/v1/annotations/{id}Get annotation details
PATCH/v1/annotations/{id}Update annotation (with if_revision)
DELETE/v1/annotations/{id}Delete an annotation

Assessments & Feedback

GET/v1/runs/{id}/assessmentsAssessment bundles for a run
GET/v1/runs/{id}/feedbackFeedback signals for a run
GET/v1/sessions/{id}/assessment-rollupAggregate assessment summary
POST/v1/feedback-signalsSubmit user feedback (thumbs, rating)
POST/v1/evals/assessments:importImport external assessment scores
POST/v1/evals/profilesCreate an assessment profile
GET/v1/evals/profilesList assessment profiles
POST/v1/evals/experimentsCreate a comparison experiment
GET/v1/evals/cost-summaryJudge model spend summary

Hosted History

GET/v1/history/sessionsList hosted session summaries
GET/v1/history/sessions:searchFull-text search over history
GET/v1/history/sessions/{id}Hosted session exact detail
GET/v1/history/sessions/{id}/entriesHosted entry window for UI rendering

Compliance Admin

POST/v1/admin/sessions/{id}:purgePermanently delete a session (cascading)
POST/v1/admin/blocks/{id}:redactRedact block content in place

Transport Modes

REST is the blocking path, SSE is the server-streaming path, and WebSocket provides bidirectional transport with gateway-shaped envelopes.

1curl https://api.rhone.dev/v1/calls
2  -H "Authorization: Bearer $VAI_API_KEY"
3  -H "Content-Type: application/json"

The rhone Extension Object

Compatibility surfaces use a top-level rhone object in request and response bodies for gateway-specific features.

Unregistered component

APIRhoneExtension

component
1The `rhone` extension object carries session continuity and context-mode metadata on compatibility surfaces.

Context Modes

Stateful execution is the default. Stateless execution is caller-supplied full-context execution and remains fully durable and session-bound.

stateful

default

Context is maintained server-side. Each new call in a session automatically includes prior history. Only send the new message — the gateway appends it to the active chain.

stateless

Caller-supplied full-context execution. Send full context with every request. The gateway executes from exactly your supplied payload and rebases the active head.

Stateful Continuation

When you provide a session_id, subsequent calls are stateful by default. You only need to send new input — the gateway has the full context.

1result, err := client.Calls.Execute(ctx, vai.CallCreateParams{
2    SessionID: vai.String("sess_123"),
3    Input:     "What should I do next?",
4})

Block Types

Native VAI requests and responses use typed blocks for every durable input and output.

TypeDirectionDescription
systeminputSystem prompt / instructions
inputinputUser input text
responseoutputModel response text
thinkingoutputModel reasoning (when enabled)
tool_calloutputTool invocation request
tool_resultinputTool execution result

WebSocket Protocol

All API shapes share the rhone.ws.v1 websocket subprotocol.

Subprotocols

  • rhone.ws.v1 — native + compat
  • vai.chain.v1 — chain-attached
  • vai.live.v1 — live audio

Operation Names

  • calls.create
  • openai.chat_completions.create
  • openai.responses.create
  • anthropic.messages.create
  • vertex.generate_content

Meta Events

  • rhone.accepted — session + call IDs
  • rhone.completed — stream done

Safety and Guardrails

Runtime safety is a first-class VAI extension exposed through capabilities.extensions.safety. It is distinct from human annotation, async assessment, and end-user feedback_signal: safety decisions are the synchronous runtime records that explain allow, warning, checkpoint, block, or quarantine outcomes.

Safety Profiles

Safety profiles are managed through:

text
1GET    /v1/safety/profiles
2POST   /v1/safety/profiles
3GET    /v1/safety/profiles/{id}
4PATCH  /v1/safety/profiles/{id}
5DELETE /v1/safety/profiles/{id}

Profiles support mode=enforce|monitor, stage policies, tool policies, capture policy, metadata, and versioning. Enforcement mode can alter control flow; monitor mode records decisions without blocking runtime execution.

Capture policy controls retained evidence. Default public evidence avoids raw vendor payloads and keeps refs, hashes, lengths, classifications, and optional minimal excerpts.

Safety Decisions

Safety decisions are immutable runtime attachment records. Exact reads are authoritative:

text
1GET /v1/safety/decisions/{id}

Attachment reads are available by parent:

text
1GET /v1/sessions/{id}/safety-decisions
2GET /v1/runs/{id}/safety-decisions
3GET /v1/tool-executions/{id}/safety-decisions
4GET /v1/assets/{id}/safety-decisions
5GET /v1/checkpoints/{id}/safety-decisions

When a later decision replaces an earlier active outcome, the prior decision is marked superseded and the replacement carries supersedes_id.

Checkpoints and Review

Safety uses normal checkpoint objects for human review. Resolving a safety checkpoint requires reviewer identity headers:

text
1X-VAI-Reviewer-ID: user_123
2X-VAI-Reviewer-Kind: human

review_note and review_labels on checkpoint resolution create review annotations tied to the checkpoint and safety decision.

Asset Quarantine and Release

Asset quarantine is represented as a safety decision with disposition quarantine at the asset admission stage. Releasing a quarantined asset requires reviewer identity and creates a follow-up allow decision plus review annotations.

Failure and Stop Semantics

Safety-controlled failures use stable stop reasons and error codes:

text
1safety_blocked
2safety.policy_denied
3safety.checkpoint_required
4safety.asset_quarantined
5safety.provider_unavailable

Use the safety decision attachment route first when investigating a blocked run, checkpointed tool execution, or quarantined asset.

Privacy Behavior

Safety decisions retain sanitized evidence according to capture policy. Raw prompts, raw model inputs, raw model outputs, raw tool payloads, and raw vendor moderation responses are not default public evidence. Use exact decision reads as the runtime source of truth; derived read models and query sources are for analytics.

See Safety & Guardrails for operator investigation guidance.