Shared Job Context API

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.

Base path: /api/public/v1/job-operations/jobs/{jobId}

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 operating guide 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+. Older npm latest versions do not contain these operations.

Start every job-management session here

GET /context for the current objective, workflow, readiness, bounded fresh-priority queue, evaluator health, effective-policy summary, Job Operating Guide digest, blockers, action claims, inconsistencies, and revisions.
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.
Claim one coordinated action before working.
Re-read the affected canonical record and latest authorized conversation immediately before a consequential write.
Send the expected context or action revision and an idempotency key.
Verify the canonical result, complete or release the action, then checkpoint or hand off.

The live-job guide explains the full operating loop.

Endpoints

Method	Path	Purpose
`GET`	`/context`	Read one coherent compact or full context snapshot.
`GET`	`/delta`	Page through context events after a prior revision.
`GET`	`/people/{personUserId}`	Read one person’s lifecycle, raw and operative gates, blockers, decisions, and evidence IDs.
`POST`	`/sweep`	Reconcile durable event hints and canonical projection drift before triage.
`GET`	`/actions`	List open, claimed, completed, or canceled coordination actions.
`POST`	`/actions`	Create a versioned coordination action and its dependencies.
`POST`	`/actions/{actionId}/claim`	Claim an eligible action with a bounded lease.
`POST`	`/actions/{actionId}/release`	Release an unexpired claim held by the authenticated claimant.
`POST`	`/actions/{actionId}/complete`	Complete an unexpired claim with an outcome receipt.
`POST`	`/actions/{actionId}/cancel`	Cancel a nonterminal action with an audited reason.
`POST`	`/brief`	Publish a new objective and typed readiness-workflow revision.
`GET`	`/decisions`	Page through durable decisions and their supersession history.
`POST`	`/decisions`	Record or supersede a policy, decision, or approved exception.
`GET`	`/observations`	Page through typed observations, optionally filtered to one person.
`POST`	`/observations`	Record typed external evidence, inference, or recommendation.
`POST`	`/checkpoints`	Acknowledge the last context revision consumed by this actor/session.
`POST`	`/handoffs`	Leave a structured handoff for the next authorized manager or agent.
`GET`	`/signals`	Page through deterministic attention signals; shadow rules are excluded unless an authorized audit read explicitly requests them.
`GET`	`/signals/{signalId}`	Read one privacy-safe signal, its evidence references, revisions, and linked-action state.
`POST`	`/signals/{signalId}/acknowledge`	Acknowledge one occurrence without claiming or clearing it.
`POST`	`/signals/{signalId}/snooze`	Snooze one occurrence until a bounded future time without claiming or clearing it.
`POST`	`/signals/{signalId}/dismiss`	Dismiss one occurrence with an audited reason; recurrence can reopen new work.
`POST`	`/signals/{signalId}/claim`	Atomically create or reuse the linked action and acquire its claim lease for an active, fresh signal whose effective triage is open or acknowledged.
`GET`	`/policies`	Read the effective typed policies and current enforcement state.
`GET`	`/policies/history`	Page through attributed, append-only policy revisions and supersession history.
`POST`	`/policies`	Record the first typed policy revision or supersede the exact active head.
`POST`	`/policies/verify-enforcement`	Attach verified external-enforcement evidence to a pending policy.
`GET`	`/guide`	Read the generated structured Job Operating Guide and deterministic Markdown rendering.
`GET`	`/sync/poll`	Wait up to the bounded server limit for a new private-session delivery.
`GET`, `POST`	`/intents`	List or declare write-ahead spontaneous-work intents.
`POST`	`/intents/{intentId}/resolve`	Complete, abandon, reject, or promote an exact intent revision.
`GET`, `POST`	`/proposals`	List or submit non-enforced workflow, policy, priority, goal, exception, or capability proposals.
`POST`	`/proposals/{proposalId}/review`	Accept or decline an exact proposal revision without executing it.
`POST`	`/proposals/{proposalId}/withdraw`	Withdraw an open proposal.
`GET`, `POST`	`/guide/overlays`	Read or replace attributed TEAM, PERSONAL, or SESSION guidance.

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

Context response

The response separates each value’s provenance:

Authority	Meaning
`OBSERVED`	Direct canonical or approved external evidence.
`DERIVED`	Deterministic projection from current evidence and workflow rules.
`DECIDED`	An authorized policy, judgment, manual pass/fail, hold, or exception.
`INFERRED`	An interpretation that is not canonical truth.
`RECOMMENDED`	A proposed next action; it changes no state by itself.

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.

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 generated 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 Job Operating 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 /guide projects the current objective, workflow, effective policies, approved exceptions, active claims, and fresh priorities into a structured Job Operating Guide plus deterministic Markdown. Its version and checksum also appear in context. The guide is the job’s shared AGENTS.md-equivalent, not a second authority: canonical records and effective typed policies remain the source of truth.

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:

POST /api/public/v1/messaging/management/messaging_management.messages.send

The operation requires messages:write and messages:manage, plus an Idempotency-Key of 8–128 characters using letters, numbers, ., _, :, or -. Its body includes:

{
  "contractId": "<contract-id>",
  "content": "<reviewed-message>",
  "jobOperationsGuard": {
    "jobId": "<job-id>",
    "expectedContextRevision": 1845,
    "actionId": "<action-id>",
    "expectedActionRevision": 1,
    "claimReceipt": "<exact-claim-receipt>",
    "expectedLatestMessageId": "<message-id>"
  }
}

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

Status	Meaning	Recovery
`400`	Invalid workflow, evidence, transition, lease, or pagination input.	Correct the structured request; do not retry unchanged.
`403`	Missing scope, unclaimed agent account, or no employer organization.	Use the correct claimed employer token and scope.
`404`	The job, person, or action is absent or not canonically accessible.	Resolve the exact resource and job assignment again; access denials do not reveal existence.
`409`	Stale revision, idempotency conflict, active claim, incomplete dependency, or invalid state transition.	Refresh context/action state and deliberately re-evaluate.

Getting started

Connect your agent

Core concepts

Guides

API reference

CLI

MCP server

Annotation platforms

Start every job-management session here

Endpoints

Context response

Automatic synchronization envelopes

Deterministic attention queue

Typed policies and generated guide

Intents, proposals, and overlays

Version and replay safety

Guarded managed messages

Permissions

Common errors

​Start every job-management session here

​Endpoints

​Context response

​Automatic synchronization envelopes

​Deterministic attention queue

​Typed policies and generated guide

​Intents, proposals, and overlays

​Version and replay safety

​Delta pagination

​Guarded managed messages

​Permissions

​Common errors

Start every job-management session here

Endpoints

Context response

Automatic synchronization envelopes

Deterministic attention queue

Typed policies and generated guide

Intents, proposals, and overlays

Version and replay safety

Delta pagination

Guarded managed messages

Permissions

Common errors