API Success Response Policy

Problem

Error responses use a common ApiError shape, but success responses vary between raw resources, { "ok": true }, and list envelopes.

Policy

Do not break existing v1/MCP/SDK contracts. Apply this policy to new endpoints first and migrate app-only endpoints opportunistically.

Response Shapes

ACK

Use for commands with no returned resource:

{ "ok": true }

Resource

Use direct resource objects when the endpoint naturally reads or mutates one resource:

{ "id": "...", "name": "..." }

Named Collection

Use named arrays when the collection name carries meaning:

{ "cards": [], "total": 0 }

Cursor Page

Use cursor envelope for paginated lists:

{ "items": [], "nextCursor": null }

Compatibility Rules

• v1 external contracts require changelog and compatibility review.
• App-only endpoints can migrate with frontend change in same PR.
• New routes must document which shape they use.
• Avoid wrapping every response in a generic envelope until clients agree on it.

Test Requirements

• Serializer tests for v1 resources.
• Route tests for cursor fields when pagination exists.
• Snapshot or schema tests for external SDK-facing responses.