API Overview

Cargoman provides three APIs for different use cases:

Base URLs

For REST and GraphQL APIs, use the Authorization header:

curl https://packages.example.com/api/v1/packages \
  -H "Authorization: Bearer $ADMIN_TOKEN"

For Composer protocol, use HTTP Basic Auth with token as username:

composer config http-basic.packages.example.com token $CUSTOMER_TOKEN

All REST API responses are JSON:

{
  "data": { ... },
  "error": null
}

Errors include status code and message:

{
  "data": null,
  "error": {
    "code": "NOT_FOUND",
    "message": "Customer not found"
  }
}

Public endpoints are rate limited:

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

List endpoints support pagination:

GET /api/v1/packages?page=1&per_page=20

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3
  }
}