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