Trail Asset Management API

This is the API documentation of Trail API.

Authentication

To use this API you have to get an API Token from the Trail service. Once you have the token, you can access the services below by adding the token into the request header:

Authorization: Basic <YOUR API TOKEN>

curl -H "Content-Type: application/json" -H "Authorization: Basic <YOUR API TOKEN>" https://guest.trail.fi/api/v1/items

Getting the Api key

Request the API key from your Trail administrator, or contact our support support@trail.fi.

Items ¶

Get Items
GET`/items{?search,page,per_page}`

Get a list of items.

Example URI

GET https://api.trail.fi/api/v1/items?search=&page=1&per_page=50

URI Parameters

HideShow

search

hash (optional)

Search parameters

For example search[free]=akg

page

integer (optional) Example: 1

Page number

per_page

integer (optional) Example: 50

Number of results per page

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 39,
      "identity": "I100115",
      "model": {
        "id": 510,
        "identity": "M100101",
        "name": "C414B-XLS",
        "manufacturer": "AKG"
      },
      "category": "Microphones",
      "department": null,
      "serial": "10341",
      "created_at": "2019-01-04T14:52:21Z",
      "updated_at": "2019-01-04T14:52:21Z",
      "location": {
        "location": {
          "id": 2,
          "code": "1001",
          "name": "Main Stage"
        }
      }
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 1,
    "per_page": 50,
    "total_entries": 4,
    "order_by": null,
    "order_direction": null
  }
}

Create New Item
POST`/items`

Create a new item using a title and an optional content body.

Example URI

POST https://api.trail.fi/api/v1/items

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "item": {
    "department": "Target department name",
    "category": "Model category name",
    "manufacturer": "Manufacturer name",
    "model": "Model name",
    "location": {
      "type": "location",
      "identity": "Location identity"
    },
    "serial": "",
    "current_user": "",
    "width": "",
    "length": "",
    "height": ""
  }
}

Response 201

Response 401

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    "authentication.api_key.user.no_privileges"
  ]
}

Item ¶

Get an Item
GET`/items/{id}`

Get a single item.

Example URI

GET https://api.trail.fi/api/v1/items/I100115

URI Parameters

HideShow

id: string (required) Example: I100115
The item id, identity or serial.

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": 39,
    "identity": "I100115",
    "model": {
      "id": 510,
      "identity": "M100101",
      "name": "C414B-XLS",
      "manufacturer": "AKG",
      "description": ""
    },
    "category": "Microphones",
    "department": null,
    "serial": "10341",
    "current_user": "",
    "description": "",
    "state": "in_use",
    "complete_state": "available",
    "statuses": [
      "available",
      "maintenance_overdue"
    ],
    "maintenance_suggestions": [
      {
        "id": 13,
        "from_time": null,
        "item_id": 39,
        "maintenance_plan_id": 1,
        "perform_at": "2025-07-16T03:00:00+03:00",
        "state": "planned",
        "to_time": null
      }
    ],
    "vendor": "",
    "created_at": "2019-01-04T14:52:21Z",
    "updated_at": "2019-01-04T14:52:21Z",
    "location": {
      "location": {
        "id": 2,
        "identity": "L100008",
        "code": "1001",
        "name": "Main Stage"
      }
    },
    "root_location": "1001 Main Stage",
    "root_location_id": 2,
    "customer_contact_id": null,
    "customer_contact_name": null,
    "purchased": "2024-07-16",
    "purchase_price": "770.0",
    "usage_started": null,
    "estimated_lifespan": 12,
    "estimated_lifespan_enddate": "2036-07-16"
  }
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    "api.v1.items.not_found"
  ]
}

Update an Item
PUT`/items/{id}`

Example URI

PUT https://api.trail.fi/api/v1/items/I100115

URI Parameters

HideShow

id: string (required) Example: I100115
The item id, identity or serial.

Request

HideShow

Headers

Content-Type: application/json

Body

{
  "item": {
    "department": "Target department name",
    "category": "Model category name",
    "manufacturer": "Manufacturer name",
    "model": "Model name",
    "location": {
      "type": "location",
      "identity": "Location identity"
    },
    "serial": "",
    "current_user": "",
    "width": "",
    "length": "",
    "height": ""
  }
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": {
    "id": 39,
    "identity": "I100115",
    "model": {
      "id": 510,
      "identity": "M100101",
      "name": "C414B-XLS",
      "manufacturer": "AKG",
      "description": ""
    },
    "category": "Microphones",
    "department": null,
    "serial": "10341",
    "current_user": "",
    "description": "",
    "state": "in_use",
    "complete_state": "available",
    "statuses": [
      "available",
      "maintenance_overdue"
    ],
    "maintenance_suggestions": [
      {
        "id": 13,
        "from_time": null,
        "item_id": 39,
        "maintenance_plan_id": 1,
        "perform_at": "2025-07-16T03:00:00+03:00",
        "state": "planned",
        "to_time": null
      }
    ],
    "vendor": "",
    "created_at": "2019-01-04T14:52:21Z",
    "updated_at": "2019-01-04T14:52:21Z",
    "location": {
      "location": {
        "id": 2,
        "identity": "L100008",
        "code": "1001",
        "name": "Main Stage"
      }
    },
    "root_location": "1001 Main Stage",
    "root_location_id": 2,
    "customer_contact_id": null,
    "customer_contact_name": null,
    "purchased": "2024-07-16",
    "purchase_price": "770.0",
    "usage_started": null,
    "estimated_lifespan": 12,
    "estimated_lifespan_enddate": "2036-07-16"
  }
}

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    "api.v1.items.invalid_request"
  ]
}

Delete an Item
DELETE`/items/{id}{?delete_reason,delete_description,permanently}`

Delete a single item

Example URI

DELETE https://api.trail.fi/api/v1/items/I100115?delete_reason=lost&delete_description=Lost during reservation&permanently=false

URI Parameters

HideShow

id: string (required) Example: I100115
The item id or identity.
delete_reason: string (optional) Example: lost
Choices: broken lost other redundant renewed sold wrong stolen recycled scrapped
delete_description: string (optional) Example: Lost during reservation
permanently: boolean (optional) Default: false Example: false
If true, the item will be permanently deleted. Do not specify if you want to soft delete the item.

Response 200

Response 404

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    "authentication.api_key.user.no_privileges"
  ]
}

Locations ¶

Group of all location-related resources.

Locations ¶

Get Locations
GET`/locations{?search,page,per_page}`

Get a list of locations.

Example URI

GET https://api.trail.fi/api/v1/locations?search=&page=1&per_page=50

URI Parameters

HideShow

search

array (optional)

Search parameters

For example search[free]=warehouse

page

integer (required) Example: 1

Page number

per_page

integer (required) Example: 50

Number of results per page

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 1,
      "identity": "L100007",
      "code": "K2001",
      "name": "Warehouse",
      "description": null,
      "ancestry": null
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 1,
    "per_page": 50,
    "total_entries": 4,
    "order_by": null,
    "order_direction": null
  }
}

Departments ¶

Group of all departments accessible for the user.

Departments ¶

Get Departments
GET`/departments`

Get a list of departments.

Example URI

GET https://api.trail.fi/api/v1/departments

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 1,
      "identity": "L100007",
      "code": "K2001",
      "name": "Warehouse",
      "description": null,
      "ancestry": null,
      "created_at": "2019-01-27T14:57:29+02:00",
      "updated_at": "2019-01-27T14:57:29+02:00"
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 1,
    "per_page": 50,
    "total_entries": 4,
    "order_by": null,
    "order_direction": null
  }
}

Models ¶

Group of all model-related resources.

Models ¶

Get Models
GET`/models{?search,page,per_page}`

Get a list of models.

Example URI

GET https://api.trail.fi/api/v1/models?search=&page=1&per_page=50

URI Parameters

HideShow

search

array (optional)

Search parameters

For example search[free]=warehouse

page

integer (required) Example: 1

Page number

per_page

integer (required) Example: 50

Number of results per page

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 1,
      "identity": "M100008",
      "manufacturer": "Manufacturer name",
      "name": "Model name",
      "description": null
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 1,
    "per_page": 50,
    "total_entries": 4,
    "order_by": null,
    "order_direction": null
  }
}

Reservations ¶

Get Reservations
GET`/reservations{?search}`

Get a list of reservations.

Example URI

GET https://api.trail.fi/api/v1/reservations?search=

URI Parameters

HideShow

search

hash (optional)

Search parameters

For example search[free]=customer name for free text search
search[customer] (string, optional) - Search by customer name or contact
search[before] (date, optional) - Filter reservations that start before this date (ISO 8601 format). Returns reservations with start date less than the specified date.
search[after] (date, optional) - Filter reservations that end after this date (ISO 8601 format). Returns reservations with end date greater than the specified date. If not specified and before is also empty, defaults to current date to show current and future reservations.
search[location] (string, optional) - Free text search for location name. Finds the first matching location and filters reservations by that location.
search[item_department_ids] (array of integers, optional) - Filter by item department IDs. Returns reservations containing items from any of the specified departments. Example: search[item_department_ids][]=1&search[item_department_ids][]=2
search[model_category_path_ids] (array of integers, optional) - Filter by model category path IDs (includes subcategories). Example: search[model_category_path_ids][]=5&search[model_category_path_ids][]=6
search[reservable_location_path_ids] (array of integers, optional) - Filter by reservable location path IDs (includes sublocations)
search[model_ids] (array of integers, optional) - Filter by model IDs
search[states_filter] (array, optional) - Filter by reservation states
search[sales_states_filter] (array, optional) - Filter by sales states
search[order] (string, optional) - Field to order by
search[direction] (string, optional) - Order direction (asc or desc)
search[page] (integer, optional) - Page number for pagination
search[per_page] (integer, optional) - Number of results per page

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 123,
      "name": "Production Setup",
      "start": "2026-06-15T08:00:00Z",
      "end": "2026-06-20T18:00:00Z",
      "created_at": "2026-06-10T10:30:00Z",
      "state": "confirmed",
      "location": {
        "id": 5,
        "code": "MAIN",
        "name": "Main Warehouse"
      },
      "reserver_name": "John Doe",
      "reserver_email": "john.doe@example.com",
      "models_without_items": [
        {
          "id": 42,
          "name": "LED Panel",
          "manufacturer": "Arri",
          "quantity": 4
        }
      ],
      "items": [
        {
          "id": 150,
          "identity": "CAM-001",
          "native_identity": "I100234",
          "model_id": 78,
          "model_name": "Sony FX6"
        }
      ]
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 5,
    "per_page": 50,
    "total_entries": 234,
    "order_by": null,
    "order_direction": null
  }
}

Response 400

HideShow

Headers

Content-Type: application/json

Body

{
  "errors": [
    "authentication.api_key.user.no_privileges"
  ]
}

Model Categories ¶

Group of all model category-related resources.

Model Categories ¶

Get Model Categories
GET`/model_categories{?search,page,per_page}`

Get a list of model categories.

Example URI

GET https://api.trail.fi/api/v1/model_categories?search=&page=1&per_page=50

URI Parameters

HideShow

search

array (optional)

Search parameters

For example search[free]=microphones

page

integer (required) Example: 1

Page number

per_page

integer (required) Example: 50

Number of results per page

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "data": [
    {
      "id": 1,
      "identity": "L100007",
      "code": "K2001",
      "name": "Warehouse",
      "description": null,
      "ancestry": null,
      "created_at": "2019-01-27T14:57:29+02:00",
      "updated_at": "2019-01-27T14:57:29+02:00"
    }
  ],
  "metadata": {
    "page": 1,
    "total_pages": 1,
    "per_page": 50,
    "total_entries": 4,
    "order_by": null,
    "order_direction": null
  }
}

Authentication ¶

Getting the Api key ¶

Items ¶

Items ¶

Get ItemsGET/items{?search,page,per_page}

Example URI

Headers

Body

Create New ItemPOST/items

Example URI

Headers

Body

Headers

Body

Item ¶

Get an ItemGET/items/{id}

Example URI

Headers

Body

Headers

Body

Update an ItemPUT/items/{id}

Example URI

Headers

Body

Headers

Body

Headers

Body

Delete an ItemDELETE/items/{id}{?delete_reason,delete_description,permanently}

Example URI

Headers

Body

Locations ¶

Locations ¶

Get LocationsGET/locations{?search,page,per_page}

Example URI

Headers

Body

Departments ¶

Departments ¶

Get DepartmentsGET/departments

Example URI

Headers

Body

Models ¶

Models ¶

Get ModelsGET/models{?search,page,per_page}

Example URI

Headers

Body

Reservations ¶

Reservations ¶

Get ReservationsGET/reservations{?search}

Example URI

Headers

Body

Headers

Body

Model Categories ¶

Model Categories ¶

Get Model CategoriesGET/model_categories{?search,page,per_page}

Example URI

Headers

Body

Authentication

Getting the Api key

Get Items
GET`/items{?search,page,per_page}`

Create New Item
POST`/items`

Get an Item
GET`/items/{id}`

Update an Item
PUT`/items/{id}`

Delete an Item
DELETE`/items/{id}{?delete_reason,delete_description,permanently}`

Get Locations
GET`/locations{?search,page,per_page}`

Get Departments
GET`/departments`

Get Models
GET`/models{?search,page,per_page}`

Get Reservations
GET`/reservations{?search}`

Get Model Categories
GET`/model_categories{?search,page,per_page}`