Skip to main content
The Shared Job Context API gives every authorized employer team member and agent one evidence-backed operational view of a job. It projects current canonical OpenTrain records, preserves durable decisions and exceptions, and coordinates work with versioned action claims.
Shared context is a projection and coordination plane. Proposals, contracts, identity checks, assessments, Project To-dos, training, messages, payments, and provider records remain authoritative in their existing APIs.
Treat capability discovery as the release fence. Use this API only when GET /api/public/v1/capabilities reports job_operations as available. The matching agent packages for deterministic signals, typed policies, and the canonical guide projection are CLI/MCP 0.10.0+ and SDK 0.9.0+. Automatic synchronization, intents, proposals, and overlays require CLI/MCP 0.11.0+ or SDK 0.10.0+. Guided operational setup requires CLI/MCP 0.15.0+ or SDK 0.14.0+. The dynamic per-job Work Catalog, coordination modes, external attestations, action renewal and handoff, and shared work-presence projection require CLI/MCP 0.23.0+ or SDK 0.21.0+. The composite Agent Guide, Playbook reads and deltas, Playbook proposals, and human publication require CLI/MCP 0.26.0+ or SDK 0.24.0+. Older npm latest versions do not contain these operations.

​
Start every job-management session here

  1. GET /context for the current objective, workflow, readiness, bounded fresh-priority queue, evaluator health, effective-policy summary, Agent Guide digest, blockers, action claims, inconsistencies, and revisions. The bootstrap envelope’s sync.nextOperations then ends with job_operations.agent_guide.get: read GET /agent-guide once, and later fetch GET /playbook/delta only when recommendation.agent_guide_changed names it.
  2. In a writable session, POST /sweep with that revision. Continue with each response’s contextRevision while hasMore is true, then read context again. Read-only sessions do not sweep.
  3. Claim one coordinated action before working.
  4. Re-read the affected canonical record and latest authorized conversation immediately before a consequential write.
  5. Send the expected context or action revision and an idempotency key.
  6. Verify the canonical result, complete or release the action, then checkpoint or hand off.
The live-job guide explains the full operating loop.

​
Endpoints

Use the machine-readable OpenAPI document for final request and response schemas.

​
Context response

The response separates each value’s provenance: Per-person results keep raw gates separate from operative gates. A manual pass can change an operative assessment gate without erasing the failed raw item. Identity and eligible-location gates are non-waivable. Evidence references contain privacy-safe resource identity, not message bodies, answers, identity documents, fraud telemetry, contact details, or provider secrets.

​
Automatic synchronization envelopes

Covered Job Operations, messaging-management, and LMS responses add two top-level fields:
  • sync contains the current private-session delivery, conflicts, recommendations, next operations, and whether a full context read is required; and
  • syncCoverage identifies the exact operation and reports native, bridged, or intentionally none coverage.
The official CLI, MCP server, and SDK capture the server-issued credential and per-job token internally, present them on the next covered request, and redact them from agent-visible output. A custom HTTP client must implement the exact header and acknowledgement contract described by OpenAPI. Never put session credentials or signed sync tokens in prompts, logs, or ordinary application state. Synchronization is additive. It does not authorize a mutation or replace the canonical pre-action read. If sync.resyncRequired is true, read context again before continuing. If syncCoverage.coverage is none, do not claim that the operation refreshed shared context. GET /sync/poll provides a bounded real-time wait. It avoids repeated full scans while another project manager is working, but canonical resources remain the final authority.

​
Guided operational setup

Covered responses recommend /setup automatically while the operating brief, typed workflow, or an applicable required operating choice is missing. The packet is read-only and never applies a proposed default. The agent declares a setup.* intent before presenting questions. An overlapping declaration can return the current winner, but that visible ID does not transfer ownership. Before prompting or writing, the winner verifies that the intent’s non-null sessionId equals the current synchronized response’s non-null sync.session.sessionId, with the same principal. It repeats that check on a fresh setup read immediately before approved writes. Use ordinary guarded /brief and /policies operations to apply the exact approved plan. A complete or explicitly deferred component becomes shared state for every authorized employer manager and agent. See Set Up Shared Job Operations for the driven agent workflow.

​
Dynamic per-job Work Catalog

OpenTrain does not define business work types. /work/definitions stores each job’s own versioned atomic-work vocabulary; /work/executions coordinates instances of that work. Covered responses expose sync.workCatalog and automatically recommend setup, review, or approval work, so a user does not have to discover the feature before their agent uses it. A durable ops:work-catalog-setup intent selects one setup session. Immediate ad hoc work can be provisional. Recurring evidence can produce an inactive INFERRED definition, but only a non-agent human job manager can approve its exact content and coordination digests. Activating the resulting decided version requires the exact immutable binding the caller just read. Each execution owns one coordinating action, whose claim lease is the single ownership authority. The human-only WORK_COORDINATION_MODE policy chooses whether this is advisory (OPEN), required with defined or provisional work (COORDINATED), or required with active defined work (MANAGED). An unreadable policy head fails closed. External systems are not silently treated as current. Record bounded evidence through an OBSERVED /observations request’s top-level externalAttestation; use ATTEST with a required expiry or INVALIDATE for a named predecessor. The generated guide’s externalCoverage projection is the safe read surface. See Dynamic Work Catalog for the agent behavior, flexible-definition model, duplicate review, and optional UI.

​
Deterministic attention queue

OpenTrain evaluates supported conditions on the backend and ranks them using a deterministic score. The default actionable queue contains only signals whose condition is active, evaluator result is fresh, and rule is active rather than shadow. Stale or incomplete evaluator runs remain visible in context health and counts, but do not appear as current priorities. Condition, freshness, and triage are independent. Acknowledging, snoozing, or dismissing one occurrence does not clear its underlying condition. Only a successful evaluator run can clear it. Signal claim is the sole path that turns a finding into owned work, and it returns the linked action lease and signed claim receipt. Claim fails closed while a signal is stale, incomplete, live-snoozed, dismissed, or produced by a shadow rule. Refresh context and wait for a complete fresh evaluation instead of creating work from evaluator-health metadata. Priority indicates what may deserve investigation; it does not establish root cause or authorize a canonical mutation. Fetch the evidence-bearing canonical records before acting.

​
Typed policies and the Agent Guide

Job-wide workflow and agent-behavior rules are stored as typed, attributed, append-only policies. A policy update names the exact active decision it supersedes and records the approving user, recording user, recording agent, effective time, enforcement target, and evidence. Supported canonical enforcement changes are applied atomically with the policy record; external enforcement remains pending until separately verified. GUIDE is a publication target. A guide policy marked APPLIED is present in the shared Agent Guide; that status does not claim that another OpenTrain subsystem enforces the instruction. The TRAINING_PRODUCTION_GATE v1 payload contains only schemaVersion and basis. Record a first-production-task stop rule separately as an attributed OPERATING_RULE.first-production-task-limit guide policy. GET /agent-guide returns the Agent Guide: the canonical typed projection of the current objective, workflow, effective policies, approved exceptions, active claims, fresh priorities, and Work Catalog, plus the human-published Playbook (bounded Markdown sections with stable ids and content hashes), the open-proposal count, and the precedence list, under one contextRevision and checksum, with a deterministic Markdown rendering. The projection’s version and checksum also appear in every context read as the guide digest. GET /guide returns the projection alone and is kept for existing clients. The Agent Guide is the job’s shared AGENTS.md-equivalent, not a second authority: canonical records and effective typed policies remain the source of truth, and the Playbook is guidance beneath them. Agents change guidance only through POST /playbook/proposals; humans publish through POST /playbook/publish, which links accepted proposals only when the exact proposed section content landed. See Follow and Improve the Agent Guide for the request and response shapes.

​
Intents, proposals, and overlays

Use an intent before spontaneous work that has no shared action yet. Active intents have bounded leases and deterministic dedupe keys, so overlapping agents receive the current winner instead of performing duplicate work. Use a proposal when a manager wants a different job-wide workflow, policy, priority, goal, exception, or capability action. A proposal is attributed and reviewable but non-enforced. Accepting it records the review and can link a separately authorized decision, action, or brief revision; review never executes the proposal. Use overlays for flexible guidance that should not become policy. TEAM is owner-controlled shared guidance, PERSONAL belongs to one manager, and SESSION belongs to one private agent session. Overlay entries are attributed untrusted content. Typed-reference lint can flag stale or higher-authority references, but overlays never alter readiness, gates, or effective policy.

​
Version and replay safety

  • Every context-changing write carries the exact expectedContextRevision read by the caller. A mismatch returns 409; refresh and re-evaluate instead of blindly retrying.
  • Action transitions also carry expectedActionRevision.
  • Every mutation requires a stable idempotency key. Repeating the same key and payload converges; reusing a key with different intent returns 409.
  • Signal transitions also carry the exact expectedSignalRevision.
  • Claim leases expire. An expired claimant cannot release or complete the action; a later caller can reclaim it through the guarded claim path.
  • Action dependencies must be complete before a dependent action can be claimed.

​
Delta pagination

GET /delta?sinceRevision=<n> returns events strictly after <n>, plus hasMore, nextRevision, and the current context revision. Continue with nextRevision until hasMore is false, then acknowledge that revision with a checkpoint.

​
Guarded managed messages

When a message is part of claimed job-context work, use:
The operation requires messages:write and messages:manage, plus an Idempotency-Key of 8–128 characters using letters, numbers, ., _, :, or -. Its body includes:
Set expectedLatestMessageId to null only when the authorized conversation was observed empty. OpenTrain resolves the authorized Job Message or Proposal Message to its canonical job, validates the guard, and commits the message and context advance atomically. A teammate or AI trainer reply, context advance, action transition, expired lease, or mismatched receipt rejects the send before creating the message or notifications. POST /api/public/v1/messages remains the generic backward-compatible send endpoint. Its optional legacy guard is only a stale-message precondition. It does not attach or advance shared Job Operations context.

​
Permissions

Reads require jobs:read; supported coordination and context writes require jobs:write. The authenticated actor must also have canonical access to the exact job—organization membership alone does not bypass folder or direct-job assignment rules. Shared Job Context is an always-available baseline agent surface. It has no separate environment, account, or UI rollout flag; normal token scopes and job access still apply.

​
Common errors