Ships
This resource allows you to create, read, and update vessels in Octopi.

This API allows you to create, read and update vessels in Octopi.

Supported Formats

json
>>>

GET /api/v1/vessels/:name
Returns information about a vessel

Returns information about the vessel. If the vessel recently completed a voyage, then it also returns information about that last voyage. Vessel can be identified by name or IMO number.

Supported Formats

json

Errors

Code Description
404 Not found.
500 Server crashed.

Examples

curl "https://app.octopi.co/api/v1/vessels/CFS%20Paceno.json" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN"
curl "https://app.octopi.co/api/v1/vessels/9403451.json" -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN"  

  {
   "vessel" : {
      "id" : 1234,
      "gross_tonnage" : 9957,
      "call_sign" : "6YSO4",
      "imo_number" : "9403451",
      "length_overall" : "148m × 23.25m",
      "actions" : {
         "show" : {
            "method" : "GET",
            "url" : "https://app.octopi.co/api/v1/vessels/CFS%20Paceno.json"
         }
      },
      "name" : "CFS Paceno"
   }
}

Params

Param name Description
name
required

Vessel name or IMO number.

Validations:

  • Must be a String
>>>

POST /api/v1/vessels
Creates a new vessel

This API endpoint allows you to create a new vessel.

Supported Formats

json

Errors

Code Description
404 Not found.
500 Server crashed.

Examples

curl "https://app.octopi.co/api/v1/vessels.json" -X POST -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN" -d '{"vessel": {"name": "CFS PACENO", "call_sign": "6YSO4", "imo": "9403451", "vessel_type": "container", "gross_tonnage": 9957}}'

{
  "vessel": {
    "id": 1234,
    "name": "CFS PACENO",
    "call_sign": "6YSO4",
    "imo_number": "9403451",
    "vessel_type": "container",
    "loa": "148m",
    "gross_tonnage": 9957,
    "actions": {
      "show": { "method": "GET", "url": "https://app.octopi.co/api/v1/vessels/CFS%20PACENO.json" },
      "update": { "method": "PUT", "url": "https://app.octopi.co/api/v1/vessels/1234.json" }
    }
  }
}

Params

Param name Description
vessel
required

Validations:

  • Must be a Hash
vessel[name]
required

The vessel name. Must be unique per organization.

Validations:

  • Must be a String
vessel[call_sign]
optional

The vessel call sign. Must be unique per organization.

Validations:

  • Must be a String
vessel[imo]
optional

The vessel IMO number. Must be 7 digits and unique per organization.

Validations:

  • Must be a String
vessel[vessel_type]
optional

The vessel type (e.g. container, general_cargo, dry_bulk, tanker).

Validations:

  • Must be a String
vessel[loa]
optional

The length overall (LOA) of the vessel.

Validations:

  • Must be a String
vessel[woa]
optional

The width overall (WOA) of the vessel.

Validations:

  • Must be a number.
vessel[gross_tonnage]
optional

The gross tonnage of the vessel.

Validations:

  • Must be a Integer
vessel[net_tonnage]
optional

The net tonnage of the vessel.

Validations:

  • Must be a Integer
vessel[teu_capacity]
optional

The TEU capacity of the vessel.

Validations:

  • Must be a number.
vessel[country_code]
optional

The country code of the vessel.

Validations:

  • Must be a String
vessel[scac]
optional

The SCAC code of the vessel.

Validations:

  • Must be a String
vessel[agent_name]
optional

The name of the vessel’s agent.

Validations:

  • Must be a String
vessel[max_draught]
optional

The maximum draught of the vessel.

Validations:

  • Must be a number.
vessel[has_cranes]
optional

Whether the vessel has cranes.

Validations:

  • Must be one of: true, false.
vessel[number_of_bays]
optional

The number of bays on the vessel.

Validations:

  • Must be a Integer
vessel[number_of_rows]
optional

The number of rows on the vessel.

Validations:

  • Must be a Integer
vessel[number_of_tiers_above]
optional

The number of tiers above deck. Must be greater than above_deck_first_tier.

Validations:

  • Must be a Integer
vessel[number_of_tiers_below]
optional

The number of tiers below deck.

Validations:

  • Must be a Integer
vessel[above_deck_first_tier]
optional

The first tier above deck. Must be one of: 70, 72, 74, 76, 78, 80, 82, 84.

Validations:

  • Must be a Integer
vessel[bay_groups]
optional

The bay groups of the vessel. Array of bay group arrays e.g. [[1,3],[5],[7,9]].

Validations:

  • Must be an array of any type
>>>

PUT /api/v1/vessels/:id
Updates an existing vessel

This API endpoint allows you to update an existing vessel by its Octopi ID. Only pass the fields you want to change.

Supported Formats

json

Errors

Code Description
404 Not found.
500 Server crashed.

Examples

curl "https://app.octopi.co/api/v1/vessels/1234.json" -X PUT -H "Accept: application/json" -H "Content-Type: application/json" -H "Authorization: Token token=YOURTOKEN" -d '{"vessel": {"gross_tonnage": 10500}}'

{
  "vessel": {
    "id": 1234,
    "name": "CFS PACENO",
    "call_sign": "6YSO4",
    "imo_number": "9403451",
    "vessel_type": "container",
    "loa": "148m",
    "gross_tonnage": 10500,
    "actions": {
      "show": { "method": "GET", "url": "https://app.octopi.co/api/v1/vessels/CFS%20PACENO.json" },
      "update": { "method": "PUT", "url": "https://app.octopi.co/api/v1/vessels/1234.json" }
    }
  }
}

Params

Param name Description
id
required

The vessel’s Octopi ID (obtain via GET /api/v1/vessels/:name)

Validations:

  • Must be a Integer
vessel
required

Validations:

  • Must be a Hash
vessel[name]
optional

The vessel name. Must be unique per organization.

Validations:

  • Must be a String
vessel[call_sign]
optional

The vessel call sign. Must be unique per organization.

Validations:

  • Must be a String
vessel[imo]
optional

The vessel IMO number. Must be 7 digits and unique per organization.

Validations:

  • Must be a String
vessel[vessel_type]
optional

The vessel type (e.g. container, general_cargo, dry_bulk, tanker).

Validations:

  • Must be a String
vessel[loa]
optional

The length overall (LOA) of the vessel.

Validations:

  • Must be a String
vessel[woa]
optional

The width overall (WOA) of the vessel.

Validations:

  • Must be a number.
vessel[gross_tonnage]
optional

The gross tonnage of the vessel.

Validations:

  • Must be a Integer
vessel[net_tonnage]
optional

The net tonnage of the vessel.

Validations:

  • Must be a Integer
vessel[teu_capacity]
optional

The TEU capacity of the vessel.

Validations:

  • Must be a number.
vessel[country_code]
optional

The country code of the vessel.

Validations:

  • Must be a String
vessel[scac]
optional

The SCAC code of the vessel.

Validations:

  • Must be a String
vessel[agent_name]
optional

The name of the vessel’s agent.

Validations:

  • Must be a String
vessel[max_draught]
optional

The maximum draught of the vessel.

Validations:

  • Must be a number.
vessel[has_cranes]
optional

Whether the vessel has cranes.

Validations:

  • Must be one of: true, false.
vessel[number_of_bays]
optional

The number of bays on the vessel.

Validations:

  • Must be a Integer
vessel[number_of_rows]
optional

The number of rows on the vessel.

Validations:

  • Must be a Integer
vessel[number_of_tiers_above]
optional

The number of tiers above deck. Must be greater than above_deck_first_tier.

Validations:

  • Must be a Integer
vessel[number_of_tiers_below]
optional

The number of tiers below deck.

Validations:

  • Must be a Integer
vessel[above_deck_first_tier]
optional

The first tier above deck. Must be one of: 70, 72, 74, 76, 78, 80, 82, 84.

Validations:

  • Must be a Integer
vessel[bay_groups]
optional

The bay groups of the vessel. Array of bay group arrays e.g. [[1,3],[5],[7,9]].

Validations:

  • Must be an array of any type