Attach a supporting evidence document (multipart)

POST 
/api/v1/products/:id/documents

Required scope: document:write. A multipart WRITE. The HMAC signs the RAW FILE BYTES (see "HMAC for multipart" in the guide), since the body is binary. The file is magic-byte-validated (the real type must match the claimed MIME). Allowed: PDF, DOCX, XLSX, PNG, JPG. EP7 is the newest surface and is flag-gated like the rest.

Request

Responses

201

Document attached (verification Pending)

400

FILE_REQUIRED (no/empty file or filename) or MALFORMED_BODY.

401

401 — INVALID_SIGNATURE or SIGNING_NOT_CONFIGURED (or bearer auth failure).

403

403 — missing scope (FORBIDDEN_SCOPE) or module (FORBIDDEN_MODULE).

404

404 — not found OR owned by another tenant (NOT_FOUND; IDOR-safe).

409

PRODUCT_FROZEN — the product is not editable.

415

UNSUPPORTED_MEDIA_TYPE — validated type is not an allowed evidence format.

422

FILE_INVALID (magic-byte mismatch / too large), INVALID_METADATA, or STORAGE_LIMIT.

429

429 — RATE_LIMITED (per-key limit, reads and writes alike; fails closed, so a limiter outage also returns 429). A limiter-down 429 is deliberately indistinguishable from a quota 429. Carries Retry-After (seconds).

Response Headers

Retry-After

Seconds to wait before retrying (429 only).

RateLimit-Limit

Per-minute request ceiling for this key's tier.

RateLimit-Remaining

Requests left in the current window (floored at 0).

RateLimit-Reset

Seconds until the window resets.

502

UPLOAD_FAILED — transient storage error; retry (the request was NOT cached).

503

503 — the API is not enabled on this environment (FEATURE_DISABLED).