openapi: 3.1.0 info: title: Foremerge local JSON API version: 0.7.0 description: >- Local-first semantic coordination API above Git. Successful responses use an ok/data envelope. All versioned routes require bearer authentication when the daemon is started with its default authenticated configuration. servers: - url: http://127.0.0.1:47811 description: Default loopback daemon security: - bearerAuth: [] paths: /healthz: get: operationId: health summary: Check process liveness without touching SQLite or Git security: [] responses: "200": $ref: "#/components/responses/Success" default: $ref: "#/components/responses/Error" /readyz: get: operationId: readiness summary: Run a bounded, non-waiting coordinator-store reachability check security: [] responses: "200": $ref: "#/components/responses/Success" "503": $ref: "#/components/responses/Error" default: $ref: "#/components/responses/Error" /v1/audit/event-chain: get: operationId: auditEventChain summary: Verify a stable event-log prefix through a paged read-only connection parameters: - name: page_size in: query schema: type: integer minimum: 1 maximum: 10000 default: 1000 responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/events: get: operationId: listEvents summary: Read append-only semantic events parameters: - name: after_seq in: query schema: type: integer format: int64 default: 0 - name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/graph: get: operationId: getGraph summary: Read the materialized semantic graph responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/status: get: operationId: getStatus summary: Read one consistent coordinator status snapshot description: >- The snapshot carries as_of_event, the ledger's latest event seq read in the same transaction as every section. responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/work: get: operationId: queryWork summary: Query intents, owners, claims, ChangeSets, and conflicts parameters: - name: agent_id in: query schema: type: string - name: status in: query schema: type: string - name: scope in: query description: A KIND:KEY semantic scope schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 500 default: 50 responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/work/{id}/start: post: operationId: startWork summary: Transition a claimed intent to IN_PROGRESS description: >- The response data is the updated intent and includes an open_conflicts snapshot (count and ids of OPEN or COORDINATING conflicts touching it, and as_of_event, the ledger event seq they were read at) captured at the transition. parameters: - $ref: "#/components/parameters/IntentId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AgentAction" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/work/{id}/discard: post: operationId: discardWork summary: Discard speculative work while preserving history parameters: - $ref: "#/components/parameters/IntentId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DiscardAction" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/agents/register: post: operationId: registerAgent summary: Register an agent/model/worktree session requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RegisterAgentRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/agents: get: operationId: listAgents summary: List registered coding agents responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/agents/{id}/inbox: get: operationId: getAgentInbox summary: Read durable coordination messages for an agent parameters: - $ref: "#/components/parameters/AgentId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/intents: post: operationId: publishIntent summary: Publish intent and return pre-code conflicts plus related work to assess description: >- The response data may carry warnings, advisory strings about the intent itself: no scopes declared, or a symbol key such as CheckoutController.checkout whose class the matching alias drops. They never refuse the publish. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PublishIntentRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/intents/{id}: get: operationId: getIntent summary: Read one intent, its agent, and current open conflicts description: >- open_conflicts carries count, ids and as_of_event, the ledger event seq the ids were read at. parameters: - $ref: "#/components/parameters/IntentId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/assessments: post: operationId: recordAssessment summary: Record what this agent concluded about one related intent description: > Foremerge states which scopes overlap and how the declared operations relate. Whether that is a conflict, a duplicate or a dependency is a judgement about intent, which the agent doing the work records here. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RecordAssessmentRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/intents/{id}/assessments: get: operationId: listAssessments summary: Read every assessment recorded for one intent parameters: - $ref: "#/components/parameters/IntentId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/claims: post: operationId: claimWork summary: Create leased advisory semantic claims description: >- The response data carries claims, warnings (overlap conflicts) and advisory_only, plus scope_warnings when a claimed symbol key loses its class to canonicalization. requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ClaimWorkRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/conflicts: get: operationId: listConflicts summary: List persisted conflicts parameters: - name: status in: query schema: type: string responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/conflicts/check: post: operationId: checkConflicts summary: Compare a persisted or provisional intent with active work description: >- intent_id alone reads the stored OPEN or COORDINATING conflicts, with stable cfl_ ids. intent_id with non-empty scopes, or intent text with scopes, compares in memory and returns fresh eph_ ids on every call, which coordinate and resolve refuse. The report carries conflicts, checked_intents, blocking, policy, ephemeral (true for the in-memory comparison) and as_of_event (the ledger's latest event seq, read in the same transaction as the findings). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ConflictCheckRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/conflicts/{id}/detections: get: operationId: listConflictDetections summary: List immutable observations for one stable conflict identity parameters: - $ref: "#/components/parameters/ConflictId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/conflicts/{id}/resolve: post: operationId: resolveConflict summary: Resolve a conflict and record its decision rationale parameters: - $ref: "#/components/parameters/ConflictId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ResolveConflictRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets: post: operationId: publishChangeSet summary: Publish a provisional ChangeSet or revision description: >- The response data is the persisted ChangeSet. Its provenance.git object records the resolved candidate commit, base_ref, base_resolution (caller_supplied, first_parent, root_commit, shallow_boundary, or unborn_worktree), and diff_hash over the actual patch bytes. The response also carries an open_conflicts snapshot (count and ids of OPEN or COORDINATING conflicts touching the intent at that moment, and the as_of_event they were read at). requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/PublishChangeSetRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets/{id}: get: operationId: getChangeSet summary: Read one ChangeSet and its Git/provenance state parameters: - $ref: "#/components/parameters/ChangeSetId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets/{id}/validation-attempts: get: operationId: listValidationAttempts summary: List authoritative and stale immutable validation attempts parameters: - $ref: "#/components/parameters/ChangeSetId" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets/{id}/validate: post: operationId: validateChangeSet summary: Run a trusted named check against the recorded fingerprint parameters: - $ref: "#/components/parameters/ChangeSetId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CheckValidationRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets/{id}/accept: post: operationId: acceptChangeSet summary: Apply validation, freshness, dependency, conflict, and Git gates parameters: - $ref: "#/components/parameters/ChangeSetId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AcceptRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/changesets/{id}/commit: post: operationId: recordCommit summary: Record an integration commit containing the accepted candidate description: >- The commit must have the accepted commit in its history or, after a squash or rebase merge, hold every change the candidate made; otherwise the call fails with TARGET_DIVERGED. The response data is the committed ChangeSet, whose provenance.integration.method is ancestor or content. parameters: - $ref: "#/components/parameters/ChangeSetId" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/RecordCommitRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" /v1/coordinate: post: operationId: coordinateWithAgent summary: Store a durable directed coordination message requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CoordinateRequest" responses: "200": $ref: "#/components/responses/Success" "401": $ref: "#/components/responses/Unauthorized" default: $ref: "#/components/responses/Error" components: securitySchemes: bearerAuth: type: http scheme: bearer description: Token stored under the repository's Foremerge runtime directory. parameters: AgentId: name: id in: path required: true schema: type: string IntentId: name: id in: path required: true schema: type: string ConflictId: name: id in: path required: true schema: type: string ChangeSetId: name: id in: path required: true schema: type: string responses: Success: description: Successful operation content: application/json: schema: $ref: "#/components/schemas/SuccessEnvelope" Unauthorized: description: Missing or invalid bearer token content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" Error: description: Invalid request, missing entity, state violation, or internal failure content: application/json: schema: $ref: "#/components/schemas/ErrorEnvelope" schemas: SuccessEnvelope: type: object required: [ok, data] properties: ok: type: boolean const: true data: {} ErrorEnvelope: type: object required: [ok, error] properties: ok: type: boolean const: false error: type: object required: [code, message] properties: code: type: string message: type: string Scope: type: object required: [kind, key] properties: kind: type: string enum: [symbol, api, schema, config, infra, test, migration, env, file, component, contract, domain] key: type: string minLength: 1 Operation: type: string description: > What an intent does to one scope. add, extend and modify preserve what other work depends on; replace, remove, rename and migrate do not. enum: [add, extend, modify, replace, remove, rename, migrate] ScopeClaim: type: object description: > A scope together with the operation the declaring intent performs on it. Declared by the caller rather than inferred from the summary. required: [kind, key, operation] properties: kind: type: string enum: [symbol, api, schema, config, infra, test, migration, env, file, component, contract, domain] key: type: string minLength: 1 operation: $ref: '#/components/schemas/Operation' inferred: type: boolean description: > True when the operation was recovered from prose instead of declared, which happens only for CLI callers. An inferred operation never produces an asserted conflict. Interaction: type: string description: How two declared operations on one scope relate. enum: [destructive_vs_additive, divergent_rewrite, shared_contract] ScopeOverlapView: type: object required: [scope, your_operation, their_operation, interaction, asserted] properties: scope: $ref: '#/components/schemas/Scope' your_operation: $ref: '#/components/schemas/Operation' their_operation: $ref: '#/components/schemas/Operation' interaction: $ref: '#/components/schemas/Interaction' asserted: type: boolean RelatedWork: type: object description: > Another agent's active intent that touches this one. Foremerge states what overlaps; the caller decides what it means and records that with POST /v1/assessments. required: [intent_id, agent_id, agent, task, summary, status, overlap, asserted] properties: intent_id: { type: string } agent_id: { type: string } agent: { type: string } task: { type: string } summary: { type: string } status: { type: string } overlap: type: array items: $ref: '#/components/schemas/ScopeOverlapView' why_surfaced: type: string asserted: type: boolean RecordAssessmentRequest: type: object required: [agent_id, intent_id, related_intent_id, verdict, rationale, action] properties: agent_id: { type: string } intent_id: { type: string } related_intent_id: { type: string } verdict: type: string enum: [conflicts, compatible, duplicate, depends_on] rationale: type: string minLength: 1 action: type: string enum: [proceeding, rescoping, waiting, abandoning] Assessment: type: object required: [id, agent_id, intent_id, related_intent_id, verdict, rationale, action, created_at] properties: id: { type: string } agent_id: { type: string } intent_id: { type: string } related_intent_id: { type: string } verdict: type: string enum: [conflicts, compatible, duplicate, depends_on] rationale: { type: string } action: type: string enum: [proceeding, rescoping, waiting, abandoning] created_at: { type: string } RegisterAgentRequest: type: object required: [name] properties: name: type: string minLength: 1 model: type: [string, "null"] capabilities: type: array items: type: string default: [] worktree: type: [string, "null"] PublishIntentRequest: type: object required: [agent_id, task, summary] properties: agent_id: type: string task: type: string minLength: 1 summary: type: string minLength: 1 rationale: type: [string, "null"] scopes: type: array items: $ref: "#/components/schemas/ScopeClaim" default: [] depends_on: type: array items: type: string default: [] metadata: type: object default: {} ClaimWorkRequest: type: object required: [agent_id, intent_id, scopes] properties: agent_id: type: string intent_id: type: string scopes: type: array minItems: 1 items: $ref: "#/components/schemas/Scope" reason: type: [string, "null"] lease_seconds: type: integer minimum: 60 maximum: 86400 default: 3600 ConflictCheckRequest: type: object properties: agent_id: type: [string, "null"] intent_id: type: [string, "null"] intent: type: [string, "null"] description: >- Free-form intent text. An id-shaped value (int_ followed by 32 hexadecimal characters) is rejected with INVALID_INPUT; pass ids as intent_id. scopes: type: array items: $ref: "#/components/schemas/ScopeClaim" default: [] anyOf: - required: [intent_id] properties: intent_id: type: string minLength: 1 - required: [intent] properties: intent: type: string minLength: 1 ResolveConflictRequest: type: object required: [agent_id, resolution, rationale] properties: agent_id: type: string resolution: type: string minLength: 1 rationale: type: string minLength: 1 TestEvidence: type: object required: [command, status] properties: command: type: string status: type: string summary: type: [string, "null"] DecisionInput: type: object required: [title, rationale] properties: title: type: string rationale: type: string alternatives: type: array items: type: string default: [] PublishChangeSetRequest: type: object required: [agent_id, intent_id, summary] properties: agent_id: type: string intent_id: type: string summary: type: string minLength: 1 files: type: array items: type: string default: [] symbols: type: array items: type: string default: [] contracts: type: array items: type: string default: [] dependencies: type: array items: type: string default: [] tests: type: array items: $ref: "#/components/schemas/TestEvidence" default: [] decisions: type: array items: $ref: "#/components/schemas/DecisionInput" default: [] provenance: type: object default: {} git_ref: type: [string, "null"] base_ref: type: [string, "null"] description: >- Optional true diff base commit for provenance. When omitted the base is derived from the candidate commit's first parent. A base that resolves to the candidate itself is rejected with INVALID_INPUT. worktree: type: [string, "null"] CheckValidationRequest: type: object description: >- Names a check from the repository's trusted registry, configured with `foremerge checks set`. The registry supplies the argument vector and timeout; raw commands are rejected. The check runs in the ChangeSet's recorded worktree, which the request cannot change. required: [check] additionalProperties: false properties: check: type: string minLength: 1 maxLength: 64 pattern: "^[A-Za-z0-9][A-Za-z0-9._-]*$" AcceptRequest: type: object properties: git_ref: type: [string, "null"] allow_high_conflicts: type: boolean default: false allow_unverified: type: boolean default: false description: >- Accept work Foremerge did not verify, or verified as failing, regardless of the configured acceptance policy. Requires override_reason. The outcome is recorded on the ChangeSet as UNVERIFIED rather than as a check that passed. This and allow_high_conflicts are operator overrides: the CLI and this API accept them, MCP rejects them. override_reason: type: [string, "null"] description: >- Required when unresolved HIGH conflicts are explicitly overridden, and when allow_unverified is set. RecordCommitRequest: type: object required: [git_ref] properties: git_ref: type: string CoordinateRequest: type: object required: [from_agent_id, to_agent_id, message] properties: from_agent_id: type: string to_agent_id: type: string message: type: string minLength: 1 conflict_id: type: [string, "null"] changeset_id: type: [string, "null"] AgentAction: type: object required: [agent_id] properties: agent_id: type: string DiscardAction: type: object required: [agent_id, reason] properties: agent_id: type: string reason: type: string minLength: 1 description: >- Must be non-empty; an empty or whitespace-only reason is rejected with INVALID_INPUT.