canonical: https://jentic.com/apis/octopi.co/octopi # Octopi API The Octopi API exposes the day-to-day records of a marine terminal operating system, covering the containers, cargo, vessels, and gate activity that move through a port. It reads and manages containers, bill of ladings, packing lists, voyages, vessel tallies, consignees, and truck appointments, so the physical state of the yard and gate is available as structured data. Reference lists such as container types, shipping lines, and event types back the core records, which keeps integrations aligned with how the terminal is configured. Terminal operators and logistics integrators use it to feed appointment status, container availability, and cargo details into planning, billing, and customer-facing systems. ## For AI agents Read and manage marine terminal records in Octopi: containers, bill of ladings, voyages, vessel tallies, consignees, invoices, and truck appointments. ## Scope Does not handle ocean carrier booking outside the terminal or last-mile parcel delivery. Use it to read and manage marine terminal records such as containers, cargo, voyages, and truck appointments only. ## Capabilities - List and inspect containers and their weights and types - Retrieve bill of ladings, line items, and packing lists - Look up voyages and vessel tallies for a call - Manage truck appointments and check appointment slots - Read consignees, freight forwarders, and related cargo records - Retrieve invoices and chargeable events for billing ## Use cases ### Container Availability Lookup A customer-service or planning agent queries GET /containers.json to check the status and location of containers in the yard. This replaces phone calls to the terminal with a direct read of container state for release and pickup decisions. Example prompt: Look up the current status of the containers on a given bill of lading and report which are available for pickup ### Cargo Detail Retrieval To confirm what is on a shipment, an agent reads GET /bill_of_ladings.json and its line items. This surfaces cargo descriptions, quantities, and consignee links so downstream billing and customs steps work from accurate data. Example prompt: Retrieve a bill of lading and list its line items for the consignee's records ### Truck Appointment Coordination A gate-scheduling agent reads GET /appointments and available slots, then manages appointments so trucks arrive when the terminal can serve them. This smooths gate flow and cuts turn-time compared with unscheduled arrivals. Example prompt: Find open appointment slots for tomorrow and book a truck appointment for a pickup ### Vessel and Voyage Tracking An operations agent reads GET /voyages.json and vessel tallies to see which vessels are calling and what has been worked. This keeps planning and customer updates aligned with the actual berth and discharge activity. Example prompt: List the voyages calling this week and report the tally progress for a named vessel ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/containers.json` | List containers in the terminal | | GET | `/bill_of_ladings.json` | List bill of ladings | | GET | `/voyages.json` | List voyages calling the terminal | | GET | `/appointments` | List truck appointments | | GET | `/invoices.json` | List invoices | ## Key resources - **Containers** — Containers with their types and weights in the terminal - **Bill of Ladings** — Bill of ladings with line items and packing lists - **Voyages and Vessels** — Voyages and vessel tallies for terminal calls - **Appointments** — Truck appointments and available appointment slots ## Why Jentic - **Setup:** Working with the Octopi API by hand means managing a bearer token, learning its container, cargo, voyage, and appointment endpoints, and handling errors against the terminal system yourself. Through Jentic you install once, import the API from the API Directory, store the token once, and your agent reads and manages terminal records. - **Permission scoping:** Octopi puts record numbers in the URL path, so scope by operation and resource: a support agent can be limited to read operations on containers and bill of ladings, while appointment changes and other writes stay out of its allowed set until you add them. - **Credential handling:** Your Octopi bearer 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 'check container status' or 'book a truck appointment', and Jentic returns the matching Octopi operation with its input schema so the agent calls the right endpoint. ## Related APIs - **Shippo external API** — Shippo handles parcel labels and rates; Octopi handles container and cargo movement at the port. - **AfterShip Tracking API** — AfterShip tracks parcels across carriers; Octopi tracks containers and voyages inside the terminal. - **ShipEngine API** — ShipEngine rates and labels outbound shipments; Octopi manages the upstream container terminal records. ## FAQ ### What does the Octopi API do? It exposes the records of a marine terminal operating system: containers, bill of ladings, packing lists, voyages, vessel tallies, consignees, invoices, and truck appointments. You read and manage the state of the yard and gate as structured data. ### What authentication does the Octopi API use? Requests carry a bearer token in the Authorization header. Through Jentic the token is held by your own instance and supplied at execution time, so the agent calls the API without ever reading the raw token. ### Can I check container status through the API? Yes. GET /containers.json lists containers with their types and weights, and you can follow a bill of lading to its line items. This gives an agent enough to answer availability and pickup questions directly. ### Can I manage truck appointments? Yes. GET /appointments lists existing appointments and there are endpoints for appointment slots, so a scheduling agent can find open times and coordinate gate arrivals against terminal capacity. ### What are the rate limits for the Octopi API? The OpenAPI specification does not declare rate limits. Read lists in reasonable pages and back off on error responses; confirm current limits with your Octopi account team. ### Do I need an MCP server to use the Octopi API with an agent? You do not. Jentic connects the API to your agent directly from the API Directory: import it, store your token once, and the agent calls the terminal operations without a separate server to run. ### Can I limit what my agent is allowed to do with the Octopi API? Yes. Because you run Jentic One yourself, you choose the allowed operations: an agent can be limited to listing containers, bill of ladings, and appointments while creating or cancelling appointments stays excluded, and the bearer credential stays with your instance.