Skip to content

sat/openapi.yaml: several write endpoints are missing a requestBody schema #39

Description

@dmchaledev

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

  1. 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).
  2. Add a User schema to components/schemas and wire it into POST /users/.
  3. 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.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions