Train_visits
This resource allows you to read, create, and update train visits in Octopi.

This resource allows you to read, create, and update train visits in Octopi.

Supported Formats

json
>>>

GET /api/v1/train_visits.json
Returns the list of train visits

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

Supported Formats

json

Errors

Code Description
400 Bad Request.
404 Not found.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/train_visits.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/train_visits.json" },
    "next":  { "method": "GET", "url": "https://app.octopi.co/api/v1/train_visits.json?page=2" },
    "previous": { "method": "GET", "url": "https://app.octopi.co/api/v1/train_visits.json?page=1" },
    "last": { "method": "GET", "url": "https://app.octopi.co/api/v1/train_visits.json?page=6" }
  },
  "train_visits": [
    {
      "id": 1,
      "visit_number": "ABC123",
      "visit_type": "inbound",
      "carrier": { "name": "Rail" },
      "notes": null,
      "estimated_time_of_arrival": "2026-05-01T10:00:00Z",
      "actual_time_of_arrival": null,
      "operation_started_at": null,
      "operation_completed_at": null,
      "created_at": "2026-04-01T08:00:00Z",
      "updated_at": "2026-04-01T08:00:00Z"
    }
  ]
}

Params

Param name Description
page
optional

The page number to be fetched. This value defaults to 1.

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.
visit_number
optional

Filter by visit number. Visit numbers are stored uppercase; this filter is case-sensitive.

Validations:

  • Must be a String
visit_type
optional

Filter by visit type. Valid values are ‘inbound’ or ‘outbound’.

Validations:

  • Must be a String
>>>

GET /api/v1/train_visits/:visit_number.json
Shows a train visit

The train visit API endpoint allows querying for one train visit.

Supported Formats

json

Errors

Code Description
400 Bad Request.
404 Not found.
500 Internal Server Error.

Examples

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

{
  "train_visit": {
    "id": 1,
    "visit_number": "ABC123",
    "visit_type": "inbound",
    "carrier": { "name": "Rail" },
    "notes": null,
    "estimated_time_of_arrival": "2026-05-01T10:00:00Z",
    "actual_time_of_arrival": null,
    "operation_started_at": null,
    "operation_completed_at": null,
    "created_at": "2026-04-01T08:00:00Z",
    "updated_at": "2026-04-01T08:00:00Z"
  }
}

Params

Param name Description
visit_number
required

The train visit number.

Validations:

  • Must be a String
>>>

POST /api/v1/train_visits.json
Creates a train visit

This API endpoint allows creating a train visit.

Supported Formats

json

Errors

Code Description
400 Bad Request.
404 Not found.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/train_visits.json" -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Token token=ADD TOKEN HERE" \
--data '{
    "train_visit": {
        "visit_number": "TV001",
        "visit_type": "inbound",
        "carrier_code": "MAERSKRAIL",
        "estimated_time_of_arrival": "2026-06-01T10:00:00Z"
    }
}'

{
  "train_visit": {
    "id": 1,
    "visit_number": "TV001",
    "visit_type": "inbound",
    "carrier": { "name": "Rail" },
    "notes": null,
    "estimated_time_of_arrival": "2026-06-01T10:00:00Z",
    "actual_time_of_arrival": null,
    "operation_started_at": null,
    "operation_completed_at": null,
    "created_at": "2026-05-01T08:00:00Z",
    "updated_at": "2026-05-01T08:00:00Z"
  }
}

Params

Param name Description
train_visit
required

A hash with train visit attributes.

Validations:

  • Must be a Hash
train_visit[visit_number]
required

The train visit number.

Validations:

  • Must be a String
train_visit[visit_type]
required

The visit type. Valid values are ‘inbound’ or ‘outbound’.

Validations:

  • Must be one of: inbound, outbound.
train_visit[carrier_code]
required

The carrier code (shipping line code).

Validations:

  • Must be a String
train_visit[notes]
optional , nil allowed

Notes.

Validations:

  • Must be a String
train_visit[estimated_time_of_arrival]
optional , nil allowed

Estimated time of arrival (inbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[actual_time_of_arrival]
optional , nil allowed

Actual time of arrival (inbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[estimated_time_of_departure]
optional , nil allowed

Estimated time of departure (outbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[actual_time_of_departure]
optional , nil allowed

Actual time of departure (outbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
>>>

PATCH /api/v1/train_visits/:visit_number.json
Updates a train visit

This API endpoint allows updating a train visit.

Supported Formats

json

Errors

Code Description
400 Bad Request.
404 Not found.
500 Internal Server Error.

Examples

curl "https://app.octopi.co/api/v1/train_visits/TV001.json" -X PATCH \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Token token=ADD TOKEN HERE" \
--data '{
    "train_visit": {
        "notes": "Updated notes",
        "estimated_time_of_arrival": "2026-06-02T10:00:00Z"
    }
}'

{
  "train_visit": {
    "id": 1,
    "visit_number": "TV001",
    "visit_type": "inbound",
    "carrier": { "name": "Rail" },
    "notes": "Updated notes",
    "estimated_time_of_arrival": "2026-06-02T10:00:00Z",
    "actual_time_of_arrival": null,
    "operation_started_at": null,
    "operation_completed_at": null,
    "created_at": "2026-05-01T08:00:00Z",
    "updated_at": "2026-05-01T09:00:00Z"
  }
}

Params

Param name Description
visit_number
required

The current train visit number, identifies the train visit to be updated.

Validations:

  • Must be a String
train_visit
required

A hash with train visit attributes to update.

Validations:

  • Must be a Hash
train_visit[visit_number]
optional , nil allowed

The new train visit number.

Validations:

  • Must be a String
train_visit[visit_type]
optional , nil allowed

The visit type. Valid values are ‘inbound’ or ‘outbound’.

Validations:

  • Must be one of: inbound, outbound.
train_visit[carrier_code]
optional , nil allowed

The carrier code (shipping line code).

Validations:

  • Must be a String
train_visit[notes]
optional , nil allowed

Notes.

Validations:

  • Must be a String
train_visit[estimated_time_of_arrival]
optional , nil allowed

Estimated time of arrival (inbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[actual_time_of_arrival]
optional , nil allowed

Actual time of arrival (inbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[estimated_time_of_departure]
optional , nil allowed

Estimated time of departure (outbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String
train_visit[actual_time_of_departure]
optional , nil allowed

Actual time of departure (outbound only). Date must be in ISO 8601 format (eg. ‘2024-06-09T09:30:00Z’).

Validations:

  • Must be a String