v1

latestOpenAPI 3.1.02026-07-13250151.3 KB
findings

Record a write-back finding against an intent: a contradiction that building the spec surfaced. The inverse of a decision — the next agent that pulls this intent reads open findings as 'the spec may be stale here' so the refinement loop converges instead of repeating a dead premise.

Rate-limited by the 'general' bucket (300/h sliding window, keyed user:<userId> or ip:<ip>). Findings are stored as a read-modify-write append on the intent's implementation_findings JSONB array (prior findings are preserved); the merged set is sanitized (capped length, malformed legacy rows dropped) before persisting. Every new finding is created with status 'open' and a server-assigned id + recordedAt (epoch ms); target, correction, and source are echoed back only when supplied. openCount is the number of findings still in status 'open' after the write.

post/api/v1/intents/{id}/findings

Path parameters

idstring required

id path parameter.

Query parameters

workspace_idstring

Required ONLY for cookie-session auth; identifies the target workspace. Ignored for API-key auth.

Request body

assumptionstring required

What the spec assumed or said before it was built. Non-empty after trim.

findingstring required

What building it actually revealed — the fact that contradicts the assumption. Non-empty after trim.

targetstring

Which part of the spec this contradicts: 'objective', 'outcome:<id>', 'constraint:<index>', 'edgeCase:<id>', 'check:<id>' (a verification check — recording this flips that check to failing), or plain prose. Non-empty after trim when provided.

correctionstring

Proposed correction to the intent, if any. Non-empty after trim when provided.

sourcestring

Provenance: where this came from, e.g. 'claude-code @ owner/repo'. Non-empty after trim when provided.

Response

Created — returns { intentId, finding, openCount }

object required