Public API reference
REST endpoints for tenants integrating PulseCargo data with their own systems — ERP, BI tools, freight broker portals, customer-facing apps.
Overview
The PulseCargo public API exposes outbound endpoints under /api/v1/* with API-key authentication. The API is read-focused today: shipments, orders, containers, customs entries, invoices, and document metadata. Write endpoints are tier-gated and roll out per integration partner.
The Developer Portal — self-serve API key issuance, rate-limit visibility, and an OpenAPI spec download — is on the build roadmap. Today, API key issuance is admin-mediated through your tenant administrator.
Authentication
All API requests require a valid API key passed in the X-PulseCargo-Api-Key header. Keys are scoped one of two ways:
- Tenant API key — full read access across the tenant's data. Issued by tenant administrators via the admin surface.
- Client API key — scoped to a single client (one of the tenant's customers). Issued per the tenant's data-visibility configuration.
curl -H "X-PulseCargo-Api-Key: pcg_live_..." \
https://api.pulsecargo.ai/api/v1/shipmentsKeys are managed in TenantApiKeys and ClientApiKeys tables. Rotation is supported; revocation is immediate.
Rate limits
Default rate limits per API key:
- 60 requests per minute on the public status endpoint (
/api/public-status) — the only unauthenticated endpoint. - Per-tenant negotiated limits on authenticated endpoints. Default is generous; per-tier thresholds documented in the admin surface. Contact your tenant administrator to raise if needed.
Rate-limit response headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) ship on every response.
Endpoints (read)
| Method | Path | Description |
|---|---|---|
GET | /api/v1/shipments | List shipments. Filter by date range, lane, mode, status. |
GET | /api/v1/shipments/{id} | Single shipment with milestones, documents, charges. |
GET | /api/v1/orders | List purchase orders. Filter by date range, customer, status. |
GET | /api/v1/orders/{id} | Single PO with linked shipments and ASNs. |
GET | /api/v1/containers | Container search across shipments. |
GET | /api/v1/customs | Customs entry status. |
GET | /api/v1/invoices | Invoice list with audit-status flags. |
GET | /api/v1/invoices/{id} | Invoice detail with line items + audit exceptions. |
GET | /api/v1/documents | Document metadata. Download via signed URL. |
GET | /api/public-status | Unauthenticated platform status check. |
Endpoints (write — tier-gated)
Write endpoints are tier-gated and ship per integration partner agreement. Available today on Professional tier and above:
| Method | Path | Description |
|---|---|---|
POST | /api/v1/orders | Create a purchase order. Pushes to CargoWise via eAdaptor. |
PUT | /api/v1/orders/{id} | Update a purchase order. Last-write-wins with warning on conflict. |
POST | /api/v1/comments | Post a comment to a shipment / order / container thread. Surfaces in CW eAdaptor too. |
POST | /api/v1/products | Create a client product (Phase 2 in flight; CW Native schema). |
Write endpoints respect the same authentication, rate limits, and audit logging as read endpoints. Every successful write is recorded in the tenant audit log with timestamp, user / API key, source records, and outcome.
Webhooks
Outbound webhook delivery is supported for scheduled exports, SIEM event egress, and PayCargo vendor-payment events. See the webhook reference for payload schemas, retry policy, and signature verification.
Audit logging
Every API call is logged to OutboundApiLogs with timestamp, API key identifier, endpoint, response code, and source IP. Tenant administrators can query the log via the admin surface for compliance evidence (SOC 2 CC4.1 / CC7.2).
Versioning policy
The API is versioned in the URL path (/api/v1/*). Breaking changes ship under a new version. The previous version is supported for a minimum of 12 months after a successor version ships, with deprecation notices via response headers (Deprecation, Sunset).
Non-breaking additions (new fields, new endpoints, expanded enum values) ship within a major version without notice.
SDKs
Officially supported SDKs are not yet published. The OpenAPI spec ships with each release; clients can generate language-specific SDKs from it. SDK availability is on the build roadmap; if a specific language is blocking your integration, contact us to prioritize.
Need API access?
Tenant administrators issue API keys. If you need access, ask your tenant admin or contact us for a developer briefing.