J Jarvis OpenAPI reference v0.1.0

OpenAPI 3.1 communication binding

OpenAPI is the machine-readable Jarvis contract.

Jarvis uses OpenAPI 3.1.1 to define protocol operations, schemas, required headers, HostAuth, error envelopes, and examples. OpenAPI defines record exchange. It does not define a host runtime, SDK implementation, model router, tool executor, storage backend, or UI.

Open YAML Raw source

Version lines

info.version: 0.1.0

This is the OpenAPI artifact version. It identifies the published v0.1.0 document.

x-jarvis-protocol.version: v0.1

This is the Jarvis protocol line. Compatible implementations negotiate protocol behavior against this value.

Protocol operations

Worker and Actor refs

PUT /workers/{worker_id} registers Worker protocol references.

PUT /actors/{actor_id} registers Actor authority references.

WorkSession lifecycle

POST /work-sessions creates the genesis WorkSession.

GET /work-sessions/{work_session_id} reads WorkSession protocol state.

POST /work-sessions/{work_session_id}/events appends JarvisEvent records.

Control plane

POST /work-sessions/{work_session_id}/policy-decisions records PolicyDecision.

POST /work-sessions/{work_session_id}/requests records Request.

POST /work-sessions/{work_session_id}/reviews records Review.

POST /work-sessions/{work_session_id}/takeovers records Takeover.

Evidence and learning

POST /work-sessions/{work_session_id}/contributions records Contribution.

POST /work-sessions/{work_session_id}/learning-records records LearningRecord.

POST /work-sessions/{work_session_id}/memory-proposals and POST /work-sessions/{work_session_id}/skill-proposals record governed proposals.

GET /work-sessions/{work_session_id}/export exports EvidenceManifest.

Post-session feedback

POST /outcome-reports records external outcome feedback without mutating sealed WorkSession or EvidenceManifest records.

Protocol schemas

OpenAPI schemas define the portable protocol records that compatible implementations exchange and validate.

Worker Actor HumanWorker AgentWorker WorkSession JarvisEvent Policy PolicyDecision Request Review ApprovalScope Takeover Contribution EvidenceManifest LearningRecord MemoryProposal SkillProposal OutcomeReport ProtocolError

Security and headers

HostAuth

Every operation uses the HostAuth security scheme. Hosts own the actual authentication system. Jarvis records the protocol requirement.

ActorHeader

Jarvis-Actor-Id identifies the protocol Actor whose authority is checked and recorded.

WorkSession-scoped mutation

  • Jarvis-Protocol-Version
  • Jarvis-Actor-Id
  • Jarvis-Idempotency-Key
  • Jarvis-Request-Timestamp
  • Jarvis-Expected-WorkSession-Revision
  • Jarvis-Previous-Event-Hash

Genesis WorkSession mutation

  • Jarvis-Expected-WorkSession-Revision: 0
  • Jarvis-Previous-Event-Hash: hash:protocol-genesis
  • Accepted state starts as active at revision 1.

Non-WorkSession mutation

  • Jarvis-Protocol-Version
  • Jarvis-Actor-Id
  • Jarvis-Idempotency-Key
  • Jarvis-Request-Timestamp

Read and export

  • Jarvis-Protocol-Version
  • Jarvis-Actor-Id
  • Mutation-only headers are rejected as requirements for read operations.

Error envelope example

Protocol errors use a stable envelope so incompatible behavior is explicit and machine-checkable. 

{
  "error_id": "missing_expected_work_session_revision",
  "protocol_version": "v0.1",
  "object_type": "WorkSession",
  "field": "headers.Jarvis-Expected-WorkSession-Revision",
  "reason": "WorkSession-scoped mutation requires expected revision.",
  "remediation": "Retry with the current WorkSession revision.",
  "trace_id": "trace-example"
}

Rendered YAML

This frame renders the published site snapshot of docs/openapi/jarvis-openapi.yaml. The docs-site checker rejects drift between this snapshot and the source file.