Context
While auditing sat/openapi.yaml (#38 fixed the unambiguous cases — PUT /templates/{id}, PUT /pages/{id}, PUT /smtp/{id}, which were missing a requestBody despite their POST siblings already documenting one), a few more write operations are undocumented and need input from someone who knows the actual SAT API request shapes rather than a guess:
| Method |
Path |
operationId |
Notes |
| POST |
/users/ |
createUser |
No User schema exists anywhere in components/schemas. The README's quick-start example (POST /sat/v1/users with {"email": ..., "group_id": ...}) doesn't match this spec at all — see also the servers mismatch below. |
| POST |
/campaigns/{id}/submit-review |
submitReview |
May be body-less, or may take a comment/note field — unclear from the description alone. |
| POST |
/campaigns/{id}/approve |
approveCampaign |
Same as above. |
| POST |
/campaigns/{id}/reject |
rejectCampaign |
Likely needs at least a rejection reason field, but unconfirmed. |
| POST |
/webhooks/{id}/deliveries/{delivery_id}/replay |
(replay delivery) |
May be body-less. |
Separately spotted while investigating: servers block doesn't match the documented API
sat/openapi.yaml's servers entry is /api (a bare relative path), while the top-level README.md quick start documents https://api.hailbytes.com/sat/v1/... as the real endpoint.
- Because Redoc/the GitHub Pages docs site resolves relative server URLs against the page's own origin (
hailbytes.github.io), the interactive "Try it" console — and anyone copying the spec into a client generator — will produce requests to the wrong host entirely.
- Additionally, none of the actual
paths in sat/openapi.yaml include a /sat/v1 (or /users, without trailing slash) prefix — e.g. the spec defines /users/ while the README shows /sat/v1/users. These two sources of truth disagree and at least one of them is wrong.
Proposed fix
- Get the real base URL and confirm the correct
servers entry for sat/openapi.yaml (mirroring how asm/openapi.yaml already does this correctly: https://api.hailbytes.com/asm/v1).
- Add a
User schema to components/schemas and wire it into POST /users/.
- For the campaign approve/reject/submit-review and webhook replay actions, confirm with the SAT service owner whether they're body-less or take an optional payload (e.g. a reason/comment), and document accordingly.
- Update the README quick-start SAT example to match whatever the corrected spec says (correct path, correct base URL).
This mostly affects anyone trying to generate an SDK, MCP tool definitions, or a Postman collection from these specs, or trying to actually call the SAT API by copy-pasting the README example.
Context
While auditing
sat/openapi.yaml(#38 fixed the unambiguous cases —PUT /templates/{id},PUT /pages/{id},PUT /smtp/{id}, which were missing arequestBodydespite theirPOSTsiblings already documenting one), a few more write operations are undocumented and need input from someone who knows the actual SAT API request shapes rather than a guess:/users/createUserUserschema exists anywhere incomponents/schemas. The README's quick-start example (POST /sat/v1/userswith{"email": ..., "group_id": ...}) doesn't match this spec at all — see also theserversmismatch below./campaigns/{id}/submit-reviewsubmitReview/campaigns/{id}/approveapproveCampaign/campaigns/{id}/rejectrejectCampaign/webhooks/{id}/deliveries/{delivery_id}/replaySeparately spotted while investigating:
serversblock doesn't match the documented APIsat/openapi.yaml'sserversentry is/api(a bare relative path), while the top-levelREADME.mdquick start documentshttps://api.hailbytes.com/sat/v1/...as the real endpoint.hailbytes.github.io), the interactive "Try it" console — and anyone copying the spec into a client generator — will produce requests to the wrong host entirely.pathsinsat/openapi.yamlinclude a/sat/v1(or/users, without trailing slash) prefix — e.g. the spec defines/users/while the README shows/sat/v1/users. These two sources of truth disagree and at least one of them is wrong.Proposed fix
serversentry forsat/openapi.yaml(mirroring howasm/openapi.yamlalready does this correctly:https://api.hailbytes.com/asm/v1).Userschema tocomponents/schemasand wire it intoPOST /users/.This mostly affects anyone trying to generate an SDK, MCP tool definitions, or a Postman collection from these specs, or trying to actually call the SAT API by copy-pasting the README example.