Skip to main content

API Overview

Cargoman provides three APIs for different use cases:

APIPurposeAuthentication
Composer ProtocolPackage installationCustomer token
REST APIManagement operationsAdmin token or CMA token
GraphQL APIFlexible queriesAdmin token or CMA token

Base URLs​

  • Composer: https://packages.example.com
  • REST API: https://packages.example.com/api/v1
  • GraphQL: https://packages.example.com/graphql

Authentication​

Admin Token​

For REST and GraphQL APIs, use the Authorization header with your admin token:

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

The ADMIN_TOKEN is the root token set via environment variable during setup and has full owner-level access.

CMA Token​

CMA (Cargoman Management Admin) tokens are per-user credentials created in the admin UI. They work identically to the root admin token in the Authorization header:

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

CMA tokens have three permission levels:

LevelPermissions
OwnerFull access + team management (create/revoke other CMA tokens)
AdminManage packages, customers, tokens, collections, and settings
ViewerRead-only access to all resources

See Admin Credentials for details on creating and managing CMA tokens.

Customer Token​

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

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

Response Format​

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"
  }
}

Rate Limiting​

Public endpoints are rate limited:

  • Default: 100 requests per 60 seconds
  • Composer downloads: Unlimited for authenticated users

Rate limit headers are included in responses:

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

Pagination​

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
  }
}

Next Steps​