Skip to content

docs: fix broken SAT quick-start example in README#40

Open
dmchaledev wants to merge 1 commit into
mainfrom
claude/elegant-edison-8g9v6d
Open

docs: fix broken SAT quick-start example in README#40
dmchaledev wants to merge 1 commit into
mainfrom
claude/elegant-edison-8g9v6d

Conversation

@dmchaledev

Copy link
Copy Markdown
Contributor

Summary

The SAT "Quick Start" curl example in README.md was inconsistent with sat/openapi.yaml, so copy-pasting it would fail:

  • It targeted https://api.hailbytes.com/sat/v1/users, but SAT's spec (sat/openapi.yaml:31-33) declares a relative /api server — SAT is self-hosted and has no fixed public host, unlike ASM.
  • It POSTed to /users, but the spec's actual POST /users/ operation (sat/openapi.yaml:1184-1206) creates an admin/system user (requires modify_system permission) and has no requestBody schema defined, so the example's {"email": ..., "group_id": ...} payload was never documented anywhere.
  • The spec explicitly notes (sat/openapi.yaml:14-17) the API is unversioned under /api/, with a versioned alias at /api/v1/ — the README used neither shape consistently.

Fix

Replaced the example with the actual, documented way to enroll users in SAT: POST /groups/ (sat/openapi.yaml:899-917), whose request body matches the Group/Target schemas (sat/openapi.yaml:305-332) — a group with a targets array of {email, first_name, last_name, ...}. Also clarified that SAT is self-hosted, so the host is instance-specific rather than a fixed api.hailbytes.com domain.

Test plan

  • Verified POST /groups/ and its Group/Target schemas exist in sat/openapi.yaml and match the new example's payload shape
  • Confirmed the ASM example directly above was unaffected (it already matches asm/openapi.yaml's https://api.hailbytes.com/asm/v1 server)
  • No code/CI changes required; this is a docs-only fix

Generated by Claude Code

The SAT curl example pointed at a nonexistent https://api.hailbytes.com/sat/v1/users
endpoint with an undocumented request body. SAT is self-hosted with a relative
/api server and no /users/ requestBody schema in sat/openapi.yaml. Replace it
with the documented POST /groups/ operation, which matches the Group/Target
schemas and is how users are actually enrolled (as targets on a group).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants