NexusAPI Developer Reference

REST API Documentation • Version 2.4 • May 2025 • Base URL: [Link]

NexusAPI provides a unified REST interface for accessing real-time logistics, inventory, and fulfillment data
across connected warehouse management systems. This reference covers authentication, rate limiting, all
endpoint specifications, request/response schemas, error codes, and SDK quickstarts for Python,
JavaScript, and Go.

1. Authentication
All API requests must include a valid API key transmitted via the Authorization header using the Bearer
scheme. API keys are generated from the NexusAPI Dashboard under Settings → API Keys. Keys are
scoped to one of three permission levels: read-only, read-write, and admin.

Authorization: Bearer nx_live_sk_v2_AbCdEfGhIjKlMnOpQrStUvWxYz0123456789

NOTE: Never expose API keys in client-side code, version control, or log files. Rotate compromised keys
immediately from the dashboard. Production keys are prefixed with nx_live_; sandbox keys with
nx_test_.

1.1 OAuth 2.0 (Enterprise)

Enterprise accounts may authenticate via OAuth 2.0 Client Credentials flow for machine-to-machine
integrations. Obtain a short-lived access token by posting your client_id and client_secret to the token
endpoint:

POST [Link] Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &client;_id=YOUR_CLIENT_ID
&client;_secret=YOUR_CLIENT_SECRET &scope;=logistics:read inventory:write

Tokens expire after 3600 seconds. Implement automatic refresh logic in your integration. Token
introspection is available at [Link]

2. Rate Limiting
Rate limits are enforced per API key on a sliding 60-second window. Exceeding the limit returns HTTP 429
with a Retry-After header indicating seconds until the window resets. Response headers on every
request include current quota status:

Header Description

X-RateLimit-Limit Maximum requests permitted in the current window

X-RateLimit-Remaining Requests remaining in the current window

 X-RateLimit-Reset Unix timestamp when the window resets

X-RateLimit-Tier Account tier (free / growth / enterprise)

Table 2.1. Rate limit response headers.

Plan Requests / 60s Burst Allowance Webhook Events/day

Free 60 80 1,000

Growth 500 750 100,000

Enterprise 5,000 8,000 Unlimited

Table 2.2. Rate limits by pricing tier.

3. Shipments Endpoint
The Shipments resource manages outbound logistics events. All timestamps are ISO 8601 UTC. Monetary
values are integers in the smallest currency unit (cents).

3.1 List Shipments

GET /shipments

Returns a paginated list of shipments for your account. Supports filtering by status, date range, carrier, and
destination country. Results are sorted by created_at descending by default.

Parameter Type Required Description

status string No Filter by status: pending | in_transit | delivered | exception | cancelled

created_after ISO 8601 No Return shipments created after this timestamp

created_before ISO 8601 No Return shipments created before this timestamp

carrier string No Filter by carrier code (e.g., DHL, FEDEX, UPS)

destination_country ISO 3166-1 No Two-letter country code

limit integer No Results per page. Default: 25. Max: 100

cursor string No Pagination cursor from previous response next_cursor field

Table 3.1. Query parameters for GET /shipments.

Example Request
curl -X GET '[Link] \ -H
'Authorization: Bearer nx_live_sk_v2_AbCdEf...' \ -H 'Accept: application/json'

Example Response (200 OK)

{ "object": "list", "data": [ { "id": "shp_01HZ7XKPQR3MNVW8YCBDGF2TE", "object":
"shipment", "status": "in_transit", "carrier": "DHL", "tracking_number": "1234567890",
"origin_country": "DE", "destination_country": "PL", "weight_grams": 1420,
"declared_value_cents": 8999, "created_at": "2025-04-28T09:14:22Z", "estimated_delivery":
"2025-05-02T18:00:00Z" } ], "has_more": true, "next_cursor": "cur_eyJpZCI6InNocF8wMUhaIn0"
 }

4. Error Reference
The API uses conventional HTTP response codes. Codes in the 2xx range indicate success; 4xx indicate
client errors; 5xx indicate server errors. All error responses include a machine-readable code and a
human-readable message.

HTTP Status Error Code Description

400 invalid_request Malformed request syntax or missing required parameter

401 unauthorized Missing or invalid API key or OAuth token

403 forbidden Key lacks permission for this operation or resource

404 not_found Resource does not exist or was permanently deleted

409 conflict Request conflicts with current resource state (e.g., duplicate)

422 unprocessable Request is well-formed but contains semantic errors

429 rate_limited Too many requests. Check Retry-After header

500 server_error Unexpected server-side error. Contact support with request ID

503 service_unavailable Temporary maintenance or overload. Retry with backoff

Table 4.1. HTTP error codes and NexusAPI error code mapping.

WARNING: Retry logic must implement exponential backoff with jitter for 429 and 5xx responses.
Aggressive retry without backoff will result in temporary IP-level blocking after 3 consecutive violations.
Recommended initial retry delay: 1s, max delay: 32s, max attempts: 6.

SDK libraries available on GitHub: Python (nexus-python), JavaScript/TypeScript (nexus-node), Go (nexus-go). OpenAPI 3.1
specification: [Link] | Status page: [Link] | Support: support@[Link]