canonical: https://jentic.com/apis/carus.com/carus # Carus Cargo Self-Service API The Cargo Self-Service API books and manages freight on Carus ferry departures. It searches availability for a departure and journey, creates and reads bookings, and manages cargo units on a booking. It also lists reference data such as departures, journeys, and ports. Authentication uses OAuth2, and the flow is built for cargo customers arranging space on scheduled sailings. ## For AI agents Search cargo availability on Carus ferry departures, create and read bookings, manage cargo units on a booking, and list departures, journeys, and ports. ## Scope Does not track shipments after sailing, handle customs filing, or cover parcel carriers. Use for searching, booking, and managing Carus ferry cargo only. ## Capabilities - Search cargo availability for a departure and journey - Create and read bookings on a departure - Create, update, and remove cargo units on a booking - List scheduled departures and their journeys - List reference data such as ports and journeys ## Use cases ### AI agent cargo booking An AI agent in a freight-planning workflow can check space and book cargo on a sailing on demand. Through Jentic the agent searches by intent and the OAuth2 token never enters its prompt context, so a logistics assistant can search availability and create a booking without a hand-built integration. Example prompt: Use Jentic to search 'search cargo availability', call POST `/cargo-self-service/v1/availability-search/departures/{departureCode}/{journeyCode}`, then POST `/cargo-self-service/v1/departures/{departureCode}/{journeyCode}/bookings` to book the space. ### Booking management After a booking is made, plans change and the cargo units on it need updating. The agent reads a booking by its code and adds, updates, or removes units, keeping the booked cargo accurate up to sailing. Example prompt: Read a booking via GET `/cargo-self-service/v1/bookings/{bookingCode}`, then create a unit with POST `/cargo-self-service/v1/units` and update it with PUT `/cargo-self-service/v1/units/{vehicleUnitNumber}.` ### Departure planning A planning agent surfaces which sailings are available for a route before booking. It lists departures and reads a specific departure and journey, giving a scheduling assistant the options to present to a customer. Example prompt: List sailings via GET `/cargo-self-service/v1/departures`, then read one with GET `/cargo-self-service/v1/departures/{departureCode}/{journeyCode}.` ### Reference data lookup Building a valid booking needs reference data like ports and journeys. The agent lists the ports Carus serves and the available journeys, so a routing workflow composes bookings against real codes rather than guessing. Example prompt: List ports with GET `/cargo-self-service/v1/ports` and journeys with GET `/cargo-self-service/v1/journeys` to build a valid booking. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/cargo-self-service/v1/availability-search/departures/{departureCode}/{journeyCode}` | Search cargo availability for a departure and journey | | GET | `/cargo-self-service/v1/departures/{departureCode}/{journeyCode}/bookings` | List bookings on a departure | | POST | `/cargo-self-service/v1/departures/{departureCode}/{journeyCode}/bookings` | Create a booking on a departure | | GET | `/cargo-self-service/v1/bookings/{bookingCode}` | Read a booking by code | | PUT | `/cargo-self-service/v1/bookings/{bookingCode}` | Update a booking by code | | GET | `/cargo-self-service/v1/units` | List cargo units | | POST | `/cargo-self-service/v1/units` | Create a cargo unit | | PUT | `/cargo-self-service/v1/units/{vehicleUnitNumber}` | Update a cargo unit | | GET | `/cargo-self-service/v1/departures` | List scheduled departures | | GET | `/cargo-self-service/v1/ports` | List ports | ## Key resources - **Units** — Cargo units on a booking - **Bookings** — Freight bookings on a departure - **Departures** — Scheduled sailings and their journeys - **Ports** — The ports Carus serves ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 60 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 88 / 100 - Developer Experience & Jentic Compatibility: 64 / 100 - AI-Readiness & Agent Experience: 52 / 100 - Agent Usability: 94 / 100 - Security: 35 / 100 - AI Discoverability: 58 / 100 - **View full report:** https://jentic.com/apis/carus.com/carus/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Cargo Self-Service API by hand means running its OAuth2 flow against api-prod-rec.carus.com and encoding the availability, booking, and unit calls yourself. Through Jentic you install once, import it from the API Directory, store the credential once, and your agent calls it. - **Permission scoping:** The API puts the departure, journey, and booking codes in the URL path (`/cargo-self-service/v1/bookings/{bookingCode}`), so a rule can pin your agent to a route or booking. You choose the operations it may call, so creating or updating a booking is not included unless you add it. - **Credential handling:** Your Carus OAuth2 token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'search cargo availability' or 'create a booking', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **AfterShip** — AfterShip tracks shipments across carriers after a booking is made - **ShipEngine** — ShipEngine rates, labels, and books parcel and freight shipments across carriers - **Shippo** — Shippo rates and buys shipping labels across many carriers ## FAQ ### Is there a Cargo Self-Service API MCP server? You don't need an MCP server to give your agent Carus. Jentic connects it directly from the API Directory: import it, store your credential once, and your agent calls the availability, booking, and unit operations. That keeps your agent's context free of an extra server's tool definitions. ### What authentication does the Cargo Self-Service API use? It authenticates with OAuth2, per its OpenAPI spec. Through Jentic the token is stored encrypted by your own instance and injected at call time, so it never reaches the agent's context. ### Can I book cargo on a ferry departure with the Cargo Self-Service API? Yes. POST `/cargo-self-service/v1/availability-search/departures/{departureCode}/{journeyCode}` checks space, and POST `/cargo-self-service/v1/departures/{departureCode}/{journeyCode}/bookings` creates the booking on that sailing. ### How do I search cargo availability through Jentic? Search Jentic for 'search cargo availability', load the input schema, and execute POST `/cargo-self-service/v1/availability-search/departures/{departureCode}/{journeyCode}.` To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the Cargo Self-Service API? Yes. Write a rule that allows only the availability-search and booking-read operations under a departure and journey code, so the agent can quote space and read bookings and nothing else, and every call it makes is logged. Creating or updating a booking stays out unless you add those operations.