REST API Reference

Complete reference for the Cargoman REST API.

Customers

Create Customer

POST /api/v1/customers

{
  "name": "Acme Corp",
  "email": "dev@acme.com",
  "external_id": "stripe_cus_abc123"
}

List Customers

GET /api/v1/customers
GET /api/v1/customers?status=active&page=1&per_page=20

Get Customer

GET /api/v1/customers/{id}
GET /api/v1/customers/by-external/{external_id}

Update Customer

PATCH /api/v1/customers/{id}

{
  "name": "Acme Corporation",
  "email": "team@acme.com"
}

Delete Customer

DELETE /api/v1/customers/{id}

Suspend Customer

POST /api/v1/customers/{id}/suspend

{
  "reason": "Payment failed"
}

Reactivate Customer

POST /api/v1/customers/{id}/reactivate

Freeze Customer

POST /api/v1/customers/{id}/freeze

{
  "versions": [
    {"package": "vendor/package", "version": "2.0.0"}
  ]
}

---

Tokens

Regenerate Token

POST /api/v1/customers/{id}/token/regenerate

Response:

{
  "token": "tok_new_xyz",
  "created_at": "2024-01-15T10:30:00Z"
}

Revoke Token

DELETE /api/v1/customers/{id}/token

---

Package Access

List Customer Packages

GET /api/v1/customers/{id}/packages

Grant Package Access

POST /api/v1/customers/{id}/packages

{
  "package": "vendor/package",
  "constraint": "^2.0"
}

Update Package Access

PUT /api/v1/customers/{id}/packages

{
  "packages": [
    {"package": "vendor/core", "constraint": "*"},
    {"package": "vendor/addon", "constraint": "^1.0"}
  ]
}

Revoke Package Access

DELETE /api/v1/customers/{id}/packages/{package}

---

Packages

List Packages

GET /api/v1/packages

Add Package

POST /api/v1/packages

{
  "name": "vendor/package",
  "repository_url": "https://github.com/vendor/package.git",
  "type": "github"
}

Get Package

GET /api/v1/packages/{name}

Sync Package

POST /api/v1/packages/{name}/sync

Delete Package

DELETE /api/v1/packages/{name}

---

Bundles

Bundles group packages for easier access management.

List Bundles

GET /api/v1/bundles

Create Bundle

POST /api/v1/bundles

{
  "name": "enterprise",
  "packages": ["vendor/core", "vendor/analytics", "vendor/support"]
}

Update Bundle

PATCH /api/v1/bundles/{name}

Delete Bundle

DELETE /api/v1/bundles/{name}

---

Webhooks

GitHub Webhook

POST /api/webhooks/github

GitLab Webhook

POST /api/webhooks/gitlab

Bitbucket Webhook

POST /api/webhooks/bitbucket

---

Error Codes

Code	HTTP Status	Description
NOT_FOUND	404	Resource not found
VALIDATION_ERROR	400	Invalid request body
UNAUTHORIZED	401	Invalid or missing token
FORBIDDEN	403	Insufficient permissions
CONFLICT	409	Resource already exists
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error