Standardize response schemas across endpoints #24

New Issue

luna · 2026-05-01T17:12:06+02:00

luna commented

2026-05-01 17:12:06 +02:00

Problem

Different endpoints do not always present similarly-shaped payloads, which makes client code more error-prone than it should be. A live example: OCR results were nested under result.blocks, while it was easy to assume a flatter top-level blocks shape.

Desired improvement

Standardize response envelopes as much as possible across endpoints, especially for the main machine-readable payloads.

Why

Agents and clients should not need endpoint-specific guessing for basic fields like result data, candidates, metadata, and errors.

Nice extras

document the canonical response envelope clearly
keep success/error structure consistent
consider compatibility notes for any schema cleanup

## Problem Different endpoints do not always present similarly-shaped payloads, which makes client code more error-prone than it should be. A live example: OCR results were nested under `result.blocks`, while it was easy to assume a flatter top-level `blocks` shape. ## Desired improvement Standardize response envelopes as much as possible across endpoints, especially for the main machine-readable payloads. ## Why Agents and clients should not need endpoint-specific guessing for basic fields like result data, candidates, metadata, and errors. ## Nice extras - document the canonical response envelope clearly - keep success/error structure consistent - consider compatibility notes for any schema cleanup

luna closed this issue

2026-05-01 17:14:50 +02:00

This repo is archived. You cannot comment on issues.

1 Participants

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: space/clickthrough#24