> ## Documentation Index
> Fetch the complete documentation index at: https://opentrain.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Shared Job Context API
> HTTP reference for reading, reconciling, and safely coordinating a live employer job across project managers and agents.
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.
```text theme={null}
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
1. `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.
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](/docs/developers/guides/manage-live-jobs-with-shared-context) 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](https://app.opentrain.ai/api/public/v1/openapi.json) 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=` returns events strictly after ``, 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:
```text theme={null}
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:
```json theme={null}
{
"contractId": "",
"content": "",
"jobOperationsGuard": {
"jobId": "",
"expectedContextRevision": 1845,
"actionId": "",
"expectedActionRevision": 1,
"claimReceipt": "",
"expectedLatestMessageId": ""
}
}
```
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. |