diff --git a/docs/api-docs/api-reference/introduction.mdx b/docs/api-docs/api-reference/introduction.mdx index 831c5976..104cae8c 100644 --- a/docs/api-docs/api-reference/introduction.mdx +++ b/docs/api-docs/api-reference/introduction.mdx @@ -35,6 +35,12 @@ Replace `YOUR_API_KEY` with the raw key value from the [developer portal](https: The full API key value is only shown once, right after you create it. Copy the complete token from that screen and store it in a secret manager before navigating away — after that, the value is masked and cannot be revealed again. If you lost the full value, create a new key, copy it immediately, then delete the older key. +### Restricted API access on Free plans + +Free-plan accounts can authenticate and create tracking requests, but read endpoints are gated. A valid key on a restricted account returns `401 Unauthorized` with `"You do not have permissions for using the API, except for creating tracking requests"` when you call any endpoint other than `POST /v2/tracking_requests`. + +To read tracking data (`GET /v2/shipments`, `GET /v2/containers`, `GET /v2/tracking_requests/{id}`, and other endpoints), your account needs full API access enabled. Full API access is not automatic on the Free plan. Contact [support@terminal49.com](mailto:support@terminal49.com) to enable a 7-day API trial, or see [Pricing](/api-docs/useful-info/pricing) for plans that include ongoing API read access. + ## Request and response format - The API follows the [JSON:API](https://jsonapi.org/) specification diff --git a/docs/api-docs/useful-info/entitlements.mdx b/docs/api-docs/useful-info/entitlements.mdx index 90fdd3d1..808e54da 100644 --- a/docs/api-docs/useful-info/entitlements.mdx +++ b/docs/api-docs/useful-info/entitlements.mdx @@ -17,6 +17,7 @@ Some Terminal49 features require account enablement beyond standard API access. | Surface | Entitlement | How to request access | Non-entitled behavior | | --- | --- | --- | --- | +| Read endpoints (`GET /v2/shipments`, `GET /v2/containers`, `GET /v2/tracking_requests/{id}`, and other GETs) | Full API access (paid plan or 7-day API trial) | Contact support@terminal49.com to enable the trial, or upgrade at [Pricing](/api-docs/useful-info/pricing) | `401 Unauthorized` with `You do not have permissions for using the API, except for creating tracking requests`. `POST /v2/tracking_requests` still works. | | Container Map GeoJSON API (`GET /v2/containers/{id}/map_geojson`) | Routing Data | Contact sales@terminal49.com | `403 Forbidden` with `Routing data feature is not enabled for this account` | | Vessel position and future-position endpoints | Routing Data / vessel positions | Contact sales@terminal49.com | `403 Forbidden` with `Routing data feature is not enabled for this account` | | MCP `get_container_route` tool | Routing Data | Contact sales@terminal49.com | The tool returns a feature-not-enabled response; use `get_container_transport_events` for historical milestones |