Repository navigation
docs(api): document who can access vessel endpoints - #480
Conversation
Every /v2/vessels endpoint now requires Routing Data and returns only
vessels on the caller's actively tracked shipments. Document the 401,
403 and 404 responses, the nulled position fields in included vessels
and webhooks, the removed /vessels/{id}/location endpoint, and that the
map embed needs Routing Data for vessel positions. Regenerate Postman
and SDK types from the spec.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
github-actions
Bot
added
risk:unknown
Shadow risk calibration
Calibration result: agreement. Shadow risk never blocks or enables merge. Keep it in observation mode until roughly 50 pull requests have human-reviewed labels, then calibrate before considering any policy use. |
github-actions
Bot
added
risk:high
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a08880daab
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| }, | ||
| "operationId": "get-vessels-id", | ||
| "description": "Returns a vessel by id. <Note>`show_positions` is a paid feature. Please contact sales@terminal49.com.</Note>" | ||
| "description": "Returns a vessel by id, with its current position. Add `show_positions` to include its position history. <Note>Requires the Routing Data entitlement for API keys, including publishable keys. Without it, every vessel endpoint returns `403`. Only vessels on your account's actively tracked shipments are returned; any other vessel returns `404`. See [Entitlements and Paid Features](/api-docs/useful-info/entitlements#vessel-data-access).</Note>" |
There was a problem hiding this comment.
For callers on a free or paused plan, or those using an invalid key, this note promises that lacking Routing Data makes every vessel endpoint return 403, while the newly added access table specifies 401 for exactly those cases. Because this description is reused across all four vessel operations and their generated SDK/Postman documentation, it should say that 403 applies only when the caller has full API access but lacks Routing Data.
AGENTS.md reference: AGENTS.md:L60-L65
Useful? React with 👍 / 👎.
This branch was successfully deployed
1 participant
Why
The vessel endpoints now enforce Routing Data on every call and only return vessels on the caller's own actively tracked shipments. The docs still said vessel lookups were open and only
show_positionswas paid, and they still implied a standalone location endpoint existed. Integrators hitting the new403and404responses had nothing to read.What changed
401/403/404responses, what counts as "your" vessel, nulled position fields in included vessels and webhooks, and the removedGET /v2/vessels/{id}/location. The vessel row and the map-embed row in the overview table now match.401response (#/components/responses/Unauthorized), and the specific403description.sdks/typescript-sdk/src/generated/terminal49.tsfrom the spec.Verification
node tools/generate-postman.mjs --checkpasses.npm run agent-verify:quickpasses.git diff --checkis clean.main. The two errors come from existing paths (/vessels/{id}vs/vessels/{imo}, and acustom_fieldsexample).🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need.
The documentation and generated updates appear safe to merge.Summary
Documents Routing Data access and tracked-shipment limits for vessel endpoints.
Reviews (1) · Last reviewed commit: "docs(api): document who can access vesse..." · Reviewed by Greptile