API documentation

This resource allows you to create, read, update, or delete voyages in Octopi.

Supported Formats

json

>>>

GET /api/v1/voyages.json
Returns the list of voyages

The voyages API endpoint allows querying for voyages. You can optionally pass in a page and/or per parameter

Supported Formats

json

Errors

Code	Description
400	Bad Request.
404	Voyage Not Found
422	Unprocessable Entity.
500	Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/voyages.json" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE"

  {
    "actions": {
        "index": {
            "method": "GET",
            "url": "https://app.octopi.co/api/v1/voyages.json"
        },
        "next": {
            "method": "GET",
            "url": "https://app.octopi.co/api/v1/voyages.json?page=2"
        },
        "previous": {
            "method": "GET",
            "url": "https://app.octopi.co/api/v1/voyages.json?page=1"
        },
        "last": {
            "method": "GET",
            "url": "https://app.octopi.co/api/v1/voyages.json?page=6"
        }
    },
    "voyages": [
        {
            "id": 1204,
            "number": "346",
            "status": "departed",
            "agent": {
              "name": "AGEMAR"
            },
            "stevedoring_company": {
                "name": "Cargo Handlers B'dos Ltd"
            },
            "stevedoring_supervisors": [
                {
                    "name": "Kirk Worrell"
                }
            ],
            "last_port_of_call": {
              "name": "Kingston",
              "locode": "JMKIN"
            },
            "next_port_of_call": {
              "name": "Port Everglades",
              "locode": "USPEF"
            },
            "captain": {
              "name": "John Doe"
            },
            "tax_date": "2017-12-12",
            "number_of_tug_boats": 4,
            "arrival_number_of_tug_boats": 2,
            "departure_number_of_tug_boats": 2,
            "estimated_time_of_anchorage": "2017-04-07T02:00:00.000Z",
            "actual_time_of_anchorage": "2017-04-07T07:42:00.000Z",
            "actual_time_of_pilot_boarded": "2017-04-07T09:06:00.000Z",
            "actual_time_of_berth": "2017-04-07T10:00:00.000Z",
            "actual_time_of_customs_clearance": "2017-04-07T12:10:00.000Z",
            "actual_time_of_departure": "2017-04-07T18:00:00.000Z",
            "closing_comments": null,
            "display_name": "CFS Pafilia 346",
            "actual_time_of_departure_pilot_boarded": null,
            "estimated_time_of_departure": null,
            "created_at": "2017-04-05T18:26:52.331Z",
            "updated_at": "2017-06-05T00:02:40.577Z",
            "vessel": {
                "name": "CFS Pafilia",
                "imo": "9322853",
                "call_sign": "6YRE8",
                "vessel_type": "Container",
                "loa": 100,
                "flag": "GA",
                "gross_tonnage": 100,
                "net_tonnage": 90
            },
            "assigned_berth_area": {
                "name": "NORTH PIER B1"
            },
            "assigned_yard_area": {
                "name": "SHED 2"
            },
            "discharge_terminal": {
                "name": "CPS Yard"
            },
            "arrival_pilot": {
                "name": null
            },
            "departure_pilot": {
                "name": null
            },
            "actions": {
                "show": {
                    "method": "GET",
                    "url": nil
                }
            },
            "flex_fields": [
              {
                "label": "Name",
                "value": "Octopi"
              }
            ]
        }
    ]
}

Params

Param name	Description
arrival_end optional	Filters out voyages that arrived after this date. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
arrival_start optional	Filters out voyages that arrived before this date. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ) Validations: Must be a String
departure_end optional	Filters out voyages that departed after this date. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ) Validations: Must be a String
departure_start optional	Filters out voyages that departed before this date. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ) Validations: Must be a String
number optional	Filter based on voyage number. Validations: Must be a String
page optional	The page number to be fetched. This value defaults to 0 Validations: Must be a number.
per optional	The number of items to be displayed. This value defaults to 10 and accepts a maximum of 100. Validations: Must be a number.
updated_at optional	Filters out voyages that where updated after this date. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ) Validations: Must be a String
vessel_name optional	Filter based on vessel name Validations: Must be a String

>>>

POST /api/v1/voyages.json
Creates a voyage

This API endpoint allows creating a voyage.

Supported Formats

json

Errors

Code	Description
400	Bad Request.
404	Voyage Not Found
422	Unprocessable Entity.
500	Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/voyages.json" -X POST     -H "Accept: application/json"     -H "Content-Type: application/json"     -H "Authorization: Token token=ADD TOKEN HERE"     --data '{
    "voyage": {
        "number": "NB 010",
        "vessel_name": "GRETA",
        "discharge_destination_type": "Terminal",
        "discharge_destination_id": 91
    }
}'

{
    "voyage": {
        "id": 345749,
        "number": "NB 010",
        "status": "unknown",
        "last_port_of_call": {
            "name": null,
            "locode": null
        },
        "next_port_of_call": {
            "name": null,
            "locode": null
        },
        "captain": {
            "name": null
        },
        "agent": {
            "name": null
        },
        "stevedoring_company": {
            "name": null
        },
        "stevedoring_supervisors": [],
        "number_of_tug_boats": 0,
        "arrival_number_of_tug_boats": null,
        "departure_number_of_tug_boats": 0,
        "estimated_time_of_anchorage": null,
        "actual_time_of_anchorage": null,
        "actual_time_of_pilot_boarded": null,
        "actual_time_of_berth": null,
        "actual_time_of_customs_clearance": null,
        "actual_time_of_departure": null,
        "closing_comments": null,
        "display_name": "GRETA NB 010",
        "actual_time_of_departure_pilot_boarded": null,
        "estimated_time_of_departure": null,
        "created_at": "2023-08-09T13:30:27Z",
        "updated_at": "2023-08-09T13:30:27Z",
        "berth_end_position": 0.0,
        "berth_start_position": 0.0,
        "block_receiving_export_past_cut_off": null,
        "departed_last_port_on": null,
        "et_of_berth": null,
        "cancelled": false,
        "ship": {
            "name": "GRETA",
            "imo": null,
            "call_sign": "6YRH2",
            "vessel_type": "Container",
            "loa": "",
            "flag": null,
            "gross_tonnage": 0,
            "net_tonnage": 0
        },
        "vessel": {
            "name": "GRETA",
            "imo": null,
            "call_sign": "6YRH2",
            "vessel_type": "Container",
            "loa": "",
            "flag": null,
            "gross_tonnage": 0,
            "net_tonnage": 0
        },
        "assigned_berth_area": {
            "name": null
        },
        "assigned_yard_area": {
            "name": null
        },
        "discharge_terminal": {
            "name": "Terminal Name"
        },
        "discharge_destination": {
            "name": "Terminal Name"
        },
        "arrival_pilot": {
            "name": null
        },
        "departure_pilot": {
            "name": null
        },
        "tax_date": null,
        "time_labour_ashore": null,
        "time_labour_onboard": null,
        "flex_fields": []
    }
}

Params

Param name	Description
voyage required	A hash with voyage attributes. Validations: Must be a Hash
voyage[discharge_destination_id] required	The discharge destination ID. Validations: Must be a number.
voyage[discharge_destination_type] required	The discharge destination type. Valid values are Terminal, Berth Area, or Port. Validations: Must be one of: `Terminal`, `Berth Area`, `Port`.
voyage[number] required	The voyage number. Validations: Must be a String
voyage[vessel_name] required	The vessel (ship) name. Notice this param is case sensitive. Validations: Must be a String
voyage[agent_id] optional , nil allowed	Agent ID. Validations: Must be a Integer
voyage[arrival_pilot_id] optional , nil allowed	Arrival pilot ID. Validations: Must be a Integer
voyage[assigned_berth_area_id] optional , nil allowed	Assigned berth area ID. Validations: Must be a Integer
voyage[assigned_yard_area_id] optional , nil allowed	Assigned yard area ID. Validations: Must be a Integer
voyage[at_berth_departure] optional , nil allowed	Actual time of berth departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_anchorage] optional , nil allowed	Actual time of anchorage. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_berth] optional , nil allowed	Actual time of berth. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_customs_clearance] optional , nil allowed	Actual time of customs clearance. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_departure] optional , nil allowed	Actual time of departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_departure_pilot_boarded] optional , nil allowed	Actual time the departure pilot boarded. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_pilot_boarded] optional , nil allowed	Actual time the pilot boarded. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[berth_end_position] optional , nil allowed	Berth end position. Validations: Must be a Float
voyage[berth_start_position] optional , nil allowed	Berth start position. Validations: Must be a Float
voyage[block_receiving_export_past_cut_off] optional , nil allowed	Block receiving export cargo after the cut off time. Validations: Must be a String
voyage[cancelled] optional , nil allowed	Cancelled. Validations: Must be a String
voyage[captain] optional , nil allowed	Captain. Validations: Must be a String
voyage[departed_last_port_on] optional , nil allowed	Departed last port date. Validations: Must be a String
voyage[departure_pilot_id] optional , nil allowed	Departure pilot ID. Validations: Must be a Integer
voyage[et_of_anchorage] optional , nil allowed	Estimated time of anchorage. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[et_of_berth] optional , nil allowed	Estimated time of berth. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[et_of_departure] optional , nil allowed	Estimated time of departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[last_port_of_call_id] optional , nil allowed	Last port of call ID. Validations: Must be a Integer
voyage[next_port_of_call_id] optional , nil allowed	Next port of call ID. Validations: Must be a Integer
voyage[receiving_cut_off_time] optional , nil allowed	Receiving cut off time. Validations: Must be a String
voyage[stevedoring_company_id] optional , nil allowed	Stevedoring company ID. Validations: Must be a Integer
voyage[tax_date] optional , nil allowed	Tax date. Validations: Must be a String
voyage[time_labour_ashore] optional , nil allowed	Time labour ashore. Validations: Must be a String
voyage[time_labour_onboard] optional , nil allowed	Time labour onboard. Validations: Must be a String
voyage[flex_fields] optional , nil allowed	An array of hashes, where each hash contains a flex field’s canonical name and the corresponding value to be set on the container. Validations: Must be an array of Hash

>>>

GET /api/v1/voyages/:number.json
Shows a voyage

The voyage API endpoint allows querying for one voyage.

Supported Formats

json

Errors

Code	Description
400	Bad Request.
404	Voyage Not Found
422	Unprocessable Entity.
500	Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/voyages/:number.json" -X GET -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=ADD TOKEN HERE"

{
   "actions": {
      "index": {
          "method": "GET",
          "url": "https://app.octopi.co/api/v1/voyages.json"
      }
   },
   "voyage" : {
      "arrival_number_of_tug_boats" : null,
      "actual_time_of_anchorage" : "2017-10-16T04:00:00Z",
      "next_port_of_call" : {
         "name" : null,
         "locode" : null
      },
      "departure_pilot" : {
         "name" : null
      },
      "assigned_berth_area" : {
         "name" : null
      },
      "actual_time_of_departure" : "2017-10-20T04:00:00Z",
      "actual_time_of_berth" : null,
      "captain" : {
         "name" : null
      },
      "estimated_time_of_anchorage" : "2017-10-16T04:00:00Z",
      "display_name" : "BLUE H 45645",
      "last_port_of_call" : {
         "name" : null,
         "locode" : null
      },
      "discharge_terminal" : {
         "name" : "BLUE TERMINAL"
      },
      "vessel" : {
         "loa" : "",
         "gross_tonnage" : 0,
         "call_sign" : null,
         "vessel_type" : "Break Bulk",
         "net_tonnage" : 0,
         "flag" : null,
         "imo" : null,
         "name" : "BLUE H"
      },
      "arrival_pilot" : {
         "name" : null
      },
      "agent" : {
         "name" : null
      },
      "actual_time_of_departure_pilot_boarded" : null,
      "tax_date" : null,
      "departure_number_of_tug_boats" : 0,
      "number_of_tug_boats" : 0,
      "ship" : {
         "vessel_type" : "Break Bulk",
         "call_sign" : null,
         "loa" : "",
         "gross_tonnage" : 0,
         "flag" : null,
         "imo" : null,
         "name" : "BLUE H",
         "net_tonnage" : 0
      },
      "closing_comments" : null,
      "actual_time_of_pilot_boarded" : null,
      "updated_at" : "2018-03-05T00:32:50Z",
      "status" : "departed",
      "estimated_time_of_departure" : null,
      "id" : 167592,
      "created_at" : "2018-03-05T00:30:33Z",
      "actual_time_of_customs_clearance" : null,
      "number" : "45645",
      "assigned_yard_area" : {
         "name" : null
      },
      "flex_fields": [
        {
          "label": "Name",
          "value": "Octopi"
        }
      ]
   }
}

>>>

PATCH /api/v1/voyages/:voyage_number.json
Updates a voyage

The voyage API endpoint allows updating a voyage.

Supported Formats

json

Errors

Code	Description
400	Bad Request.
404	Voyage Not Found
422	Unprocessable Entity.
500	Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/voyages/:number.json"       -d '{"voyage": { "Captain": "Cook", "at_of_departure": "2024-12-05T18:41:17.422Z" }}'       -X PATCH -H "Accept: application/json"       -H "Content-Type: application/json"       -H "Authorization: Token token=YOURTOKEN"

Params

Param name	Description
number required	The voyage number, identifies the voyage to be updated. Validations: Must be a String
voyage required	A hash with voyage attributes. Validations: Must be a Hash
voyage[discharge_destination_id] optional	The discharge destination ID. Validations: Must be a number.
voyage[discharge_destination_type] optional	The discharge destination type. Valid values are Terminal, Berth Area, or Port. Validations: Must be one of: `Terminal`, `Berth Area`, `Port`.
voyage[number] optional	The voyage number. Validations: Must be a String
voyage[vessel_name] optional	The vessel (ship) name. Notice this param is case sensitive. Validations: Must be a String
voyage[agent_id] optional , nil allowed	Agent ID. Validations: Must be a Integer
voyage[arrival_pilot_id] optional , nil allowed	Arrival pilot ID. Validations: Must be a Integer
voyage[assigned_berth_area_id] optional , nil allowed	Assigned berth area ID. Validations: Must be a Integer
voyage[assigned_yard_area_id] optional , nil allowed	Assigned yard area ID. Validations: Must be a Integer
voyage[at_berth_departure] optional , nil allowed	Actual time of berth departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_anchorage] optional , nil allowed	Actual time of anchorage. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_berth] optional , nil allowed	Actual time of berth. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_customs_clearance] optional , nil allowed	Actual time of customs clearance. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_departure] optional , nil allowed	Actual time of departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_departure_pilot_boarded] optional , nil allowed	Actual time the departure pilot boarded. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[at_of_pilot_boarded] optional , nil allowed	Actual time the pilot boarded. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[berth_end_position] optional , nil allowed	Berth end position. Validations: Must be a Float
voyage[berth_start_position] optional , nil allowed	Berth start position. Validations: Must be a Float
voyage[block_receiving_export_past_cut_off] optional , nil allowed	Block receiving export cargo after the cut off time. Validations: Must be a String
voyage[cancelled] optional , nil allowed	Cancelled. Validations: Must be a String
voyage[captain] optional , nil allowed	Captain. Validations: Must be a String
voyage[departed_last_port_on] optional , nil allowed	Departed last port date. Validations: Must be a String
voyage[departure_pilot_id] optional , nil allowed	Departure pilot ID. Validations: Must be a Integer
voyage[et_of_anchorage] optional , nil allowed	Estimated time of anchorage. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[et_of_berth] optional , nil allowed	Estimated time of berth. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[et_of_departure] optional , nil allowed	Estimated time of departure. Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00ZZ). Validations: Must be a String
voyage[last_port_of_call_id] optional , nil allowed	Last port of call ID. Validations: Must be a Integer
voyage[next_port_of_call_id] optional , nil allowed	Next port of call ID. Validations: Must be a Integer
voyage[receiving_cut_off_time] optional , nil allowed	Receiving cut off time. Validations: Must be a String
voyage[stevedoring_company_id] optional , nil allowed	Stevedoring company ID. Validations: Must be a Integer
voyage[tax_date] optional , nil allowed	Tax date. Validations: Must be a String
voyage[time_labour_ashore] optional , nil allowed	Time labour ashore. Validations: Must be a String
voyage[time_labour_onboard] optional , nil allowed	Time labour onboard. Validations: Must be a String
voyage[flex_fields] optional , nil allowed	An array of hashes, where each hash contains a flex field’s canonical name and the corresponding value to be set on the container. Validations: Must be an array of Hash

Voyages This resource allows you to create, read, update, or delete voyages in Octopi.

Supported Formats

GET /api/v1/voyages.json Returns the list of voyages

Supported Formats

Errors

Examples

Params

POST /api/v1/voyages.json Creates a voyage

Supported Formats

Errors

Examples

Params

GET /api/v1/voyages/:number.json Shows a voyage

Supported Formats

Errors

Examples

PATCH /api/v1/voyages/:voyage_number.json Updates a voyage

Supported Formats

Errors

Examples

Params

Voyages
This resource allows you to create, read, update, or delete voyages in Octopi.

GET /api/v1/voyages.json
Returns the list of voyages

POST /api/v1/voyages.json
Creates a voyage

GET /api/v1/voyages/:number.json
Shows a voyage

PATCH /api/v1/voyages/:voyage_number.json
Updates a voyage