This resource allows you to create, read, update, or delete voyages in Octopi.
The voyages API endpoint allows querying for voyages. You can optionally pass in a page and/or per parameter
| Code | Description |
|---|---|
| 400 | Bad Request. |
| 404 | Voyage Not Found |
| 422 | Unprocessable Entity. |
| 500 | Internal Server Error. |
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"
}
]
}
]
}
| 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:
|
|
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:
|
|
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:
|
|
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:
|
|
number optional |
Filter based on voyage number. Validations:
|
|
page optional |
The page number to be fetched. This value defaults to 0 Validations:
|
|
per optional |
The number of items to be displayed. This value defaults to 10 and accepts a maximum of 100. Validations:
|
|
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:
|
|
vessel_name optional |
Filter based on vessel name Validations:
|
This API endpoint allows creating a voyage.
| Code | Description |
|---|---|
| 400 | Bad Request. |
| 404 | Voyage Not Found |
| 422 | Unprocessable Entity. |
| 500 | Internal Server Error. |
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": []
}
}
| Param name | Description |
|---|---|
|
voyage required |
A hash with voyage attributes. Validations:
|
|
voyage[discharge_destination_id] required |
The discharge destination ID. Validations:
|
|
voyage[discharge_destination_type] required |
The discharge destination type. Valid values are Terminal, Berth Area, or Port. Validations:
|
|
voyage[number] required |
The voyage number. Validations:
|
|
voyage[vessel_name] required |
The vessel (ship) name. Notice this param is case sensitive. Validations:
|
|
voyage[agent_id] optional , nil allowed |
Agent ID. Validations:
|
|
voyage[arrival_pilot_id] optional , nil allowed |
Arrival pilot ID. Validations:
|
|
voyage[assigned_berth_area_id] optional , nil allowed |
Assigned berth area ID. Validations:
|
|
voyage[assigned_yard_area_id] optional , nil allowed |
Assigned yard area ID. Validations:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
voyage[berth_end_position] optional , nil allowed |
Berth end position. Validations:
|
|
voyage[berth_start_position] optional , nil allowed |
Berth start position. Validations:
|
|
voyage[block_receiving_export_past_cut_off] optional , nil allowed |
Block receiving export cargo after the cut off time. Validations:
|
|
voyage[cancelled] optional , nil allowed |
Cancelled. Validations:
|
|
voyage[captain] optional , nil allowed |
Captain. Validations:
|
|
voyage[departed_last_port_on] optional , nil allowed |
Departed last port date. Validations:
|
|
voyage[departure_pilot_id] optional , nil allowed |
Departure pilot ID. Validations:
|
|
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:
|
|
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:
|
|
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:
|
|
voyage[last_port_of_call_id] optional , nil allowed |
Last port of call ID. Validations:
|
|
voyage[next_port_of_call_id] optional , nil allowed |
Next port of call ID. Validations:
|
|
voyage[receiving_cut_off_time] optional , nil allowed |
Receiving cut off time. Validations:
|
|
voyage[stevedoring_company_id] optional , nil allowed |
Stevedoring company ID. Validations:
|
|
voyage[tax_date] optional , nil allowed |
Tax date. Validations:
|
|
voyage[time_labour_ashore] optional , nil allowed |
Time labour ashore. Validations:
|
|
voyage[time_labour_onboard] optional , nil allowed |
Time labour onboard. Validations:
|
The voyage API endpoint allows querying for one voyage.
| Code | Description |
|---|---|
| 400 | Bad Request. |
| 404 | Voyage Not Found |
| 422 | Unprocessable Entity. |
| 500 | Internal Server Error. |
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"
}
]
}
}
The voyage API endpoint allows updating a voyage.
| Code | Description |
|---|---|
| 400 | Bad Request. |
| 404 | Voyage Not Found |
| 422 | Unprocessable Entity. |
| 500 | Internal Server Error. |
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"
| Param name | Description |
|---|---|
|
number required |
The voyage number, identifies the voyage to be updated. Validations:
|
|
voyage required |
A hash with voyage attributes. Validations:
|
|
voyage[discharge_destination_id] optional |
The discharge destination ID. Validations:
|
|
voyage[discharge_destination_type] optional |
The discharge destination type. Valid values are Terminal, Berth Area, or Port. Validations:
|
|
voyage[number] optional |
The voyage number. Validations:
|
|
voyage[vessel_name] optional |
The vessel (ship) name. Notice this param is case sensitive. Validations:
|
|
voyage[agent_id] optional , nil allowed |
Agent ID. Validations:
|
|
voyage[arrival_pilot_id] optional , nil allowed |
Arrival pilot ID. Validations:
|
|
voyage[assigned_berth_area_id] optional , nil allowed |
Assigned berth area ID. Validations:
|
|
voyage[assigned_yard_area_id] optional , nil allowed |
Assigned yard area ID. Validations:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
voyage[berth_end_position] optional , nil allowed |
Berth end position. Validations:
|
|
voyage[berth_start_position] optional , nil allowed |
Berth start position. Validations:
|
|
voyage[block_receiving_export_past_cut_off] optional , nil allowed |
Block receiving export cargo after the cut off time. Validations:
|
|
voyage[cancelled] optional , nil allowed |
Cancelled. Validations:
|
|
voyage[captain] optional , nil allowed |
Captain. Validations:
|
|
voyage[departed_last_port_on] optional , nil allowed |
Departed last port date. Validations:
|
|
voyage[departure_pilot_id] optional , nil allowed |
Departure pilot ID. Validations:
|
|
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:
|
|
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:
|
|
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:
|
|
voyage[last_port_of_call_id] optional , nil allowed |
Last port of call ID. Validations:
|
|
voyage[next_port_of_call_id] optional , nil allowed |
Next port of call ID. Validations:
|
|
voyage[receiving_cut_off_time] optional , nil allowed |
Receiving cut off time. Validations:
|
|
voyage[stevedoring_company_id] optional , nil allowed |
Stevedoring company ID. Validations:
|
|
voyage[tax_date] optional , nil allowed |
Tax date. Validations:
|
|
voyage[time_labour_ashore] optional , nil allowed |
Time labour ashore. Validations:
|
|
voyage[time_labour_onboard] optional , nil allowed |
Time labour onboard. Validations:
|