docs: fix broken SAT quick-start example in README#40
Open
dmchaledev wants to merge 1 commit into
Open
Conversation
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The SAT "Quick Start" curl example in
README.mdwas inconsistent withsat/openapi.yaml, so copy-pasting it would fail:https://api.hailbytes.com/sat/v1/users, but SAT's spec (sat/openapi.yaml:31-33) declares a relative/apiserver — SAT is self-hosted and has no fixed public host, unlike ASM./users, but the spec's actualPOST /users/operation (sat/openapi.yaml:1184-1206) creates an admin/system user (requiresmodify_systempermission) and has norequestBodyschema defined, so the example's{"email": ..., "group_id": ...}payload was never documented anywhere.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 theGroup/Targetschemas (sat/openapi.yaml:305-332) — a group with atargetsarray of{email, first_name, last_name, ...}. Also clarified that SAT is self-hosted, so the host is instance-specific rather than a fixedapi.hailbytes.comdomain.Test plan
POST /groups/and itsGroup/Targetschemas exist insat/openapi.yamland match the new example's payload shapeasm/openapi.yaml'shttps://api.hailbytes.com/asm/v1server)Generated by Claude Code