From d67502eaecb40129fced0428619288144350e3d3 Mon Sep 17 00:00:00 2001
From: "bert.hausmans" <bert@hausmans.nl>
Date: Thu, 23 Apr 2026 17:21:15 +0200
Subject: [PATCH] docs(api): refresh Form Builder public API surface notes

Updates API.md and S3a discovery doc to reflect submitter-details
handling and the draft/submit split.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 dev-docs/API.md                           | 30 ++++++++++++++++++-----
 dev-docs/discovery/S3a-public-form-api.md |  7 ++++++
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/dev-docs/API.md b/dev-docs/API.md
index ec8508f7..5001f774 100644
--- a/dev-docs/API.md
+++ b/dev-docs/API.md
@@ -784,16 +784,34 @@ S2c contract for the unauthenticated portal. Six endpoints at
 `PublicFormTokenResolver` (7-day grace window on
 `public_token_previous`; BACKLOG FORM-04 makes this configurable).
 
-All errors use the standardised envelope:
+### Error envelope
+
+All public form endpoints return errors with this envelope:
 
 ```json
-{ "message": "Human text", "code": "MACHINE_CODE", "errors"?: {"values.slug": ["..."]} }
+{
+  "message": "Human-readable message",
+  "code": "MACHINE_READABLE_CODE",
+  "errors": { "field_name": ["validation message"] }
+}
 ```
 
-Codes: `SCHEMA_NOT_FOUND` (404), `TOKEN_EXPIRED` (410),
-`TOKEN_REVOKED` (410), `SCHEMA_UNPUBLISHED` (410),
-`SUBMISSION_ALREADY_SUBMITTED` (409), `RATE_LIMITED` (429, carries
-`Retry-After`), `VALIDATION_FAILED` (422).
+`errors` is only present on 422 validation failures (Laravel
+FormRequest shape).
+
+Codes:
+
+| Code                          | HTTP | Meaning                                        |
+| ----------------------------- | ---- | ---------------------------------------------- |
+| `TOKEN_EXPIRED`               | 410  | public token past grace window                 |
+| `TOKEN_REVOKED`               | 410  | token rotated without grace                    |
+| `SCHEMA_UNPUBLISHED`          | 410  | schema exists but not published                |
+| `SCHEMA_NOT_FOUND`            | 404  | public token does not resolve                  |
+| `SUBMISSION_ALREADY_SUBMITTED`| 409  | submit on finalised submission                 |
+| `RATE_LIMITED`                | 429  | includes `Retry-After` header                  |
+
+Authoritative source: `api/app/Exceptions/FormBuilder/PublicFormApiException.php`
+and its concrete subclasses.
 
 ### `GET /public/forms/{public_token}`
 
diff --git a/dev-docs/discovery/S3a-public-form-api.md b/dev-docs/discovery/S3a-public-form-api.md
index d0bfa99b..8d778950 100644
--- a/dev-docs/discovery/S3a-public-form-api.md
+++ b/dev-docs/discovery/S3a-public-form-api.md
@@ -1,5 +1,12 @@
 # Discovery — Public Form Builder API surface (S3a prep)
 
+> **Superseded 2026-04-18**
+> Written against commit 79d834c (S2b + S0.5) for S3a discovery.
+> S2c standardised the error envelope to `{ message, code, errors? }`
+> — see /dev-docs/API.md § Public Form Endpoints for the current
+> contract. Route inventory and response shapes below remain
+> accurate; only the error envelope changed.
+
 > **Purpose:** ground a follow-up S3a frontend prompt in the exact shapes
 > the current backend exposes. Written by inspecting code + hitting the
 > live endpoints against the S0.5-seeded dev token, not from ARCH or