Back to top

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

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",
      "native_identity": "I100115",
      "created_at": "2019-01-04T14:52:21Z",
      "updated_at": "2019-01-04T14:52:21Z",
      "manufacturer": "AKG",
      "images": [
        {
          "id": 90,
          "url": "https://example.com/images/90/large.jpg",
          "thumbnail_url": "https://example.com/images/90/small.jpg",
          "created_at": "2019-01-04T14:52:21Z",
          "updated_at": "2019-01-04T14:52:21Z"
        }
      ],
      "item_type": {
        "id": 1,
        "name": "Device",
        "class_name": "ItemType"
      },
      "model": {
        "id": 510,
        "identity": "M100101",
        "name": "C414B-XLS",
        "manufacturer": "AKG"
      },
      "category": "Microphones",
      "model_category": {
        "id": 12,
        "name": "Microphones",
        "class_name": "ModelCategory"
      },
      "department": "Audio",
      "serial": "10341",
      "current_user": "",
      "current_location": "collected",
      "can_have_contents": false,
      "description": "",
      "model_description": "",
      "state": "in_use",
      "statuses": [
        "available"
      ],
      "custom_statuses": [
        {
          "status": "custom_status_42",
          "custom_status_id": 42,
          "text": "Missing",
          "colour": "red",
          "tooltip": "Inventory could not find this item",
          "automation_assigned": true
        }
      ],
      "location": {
        "location": {
          "id": 2,
          "identity": "L100008",
          "code": "1001",
          "name": "Main Stage"
        }
      },
      "root_location": "1001 Main Stage",
      "root_location_id": 2,
      "customer_contact_id": 72,
      "customer_contact_name": "Example Productions",
      "vendor": "Example Vendor",
      "purchased": "2024-07-16",
      "price": "770.0",
      "purchase_price": "770.0",
      "usage_started": "2024-07-20",
      "total_cost": 920,
      "total_maintenance_hours": 2.5,
      "investment": "automatic",
      "estimated_lifespan": 12,
      "common_estimated_lifespan": 10,
      "calculated_estimated_lifespan": 12,
      "estimated_lifespan_enddate": "2036-07-16",
      "lifespan_estimation_date": "2036-07-16",
      "lended_by": {
        "id": 7,
        "name": "Alex Example",
        "class_name": "User",
        "username": "alex",
        "email": "alex@example.com"
      },
      "reserved_by": null
    }
  ],
  "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
HideShow
Headers
Content-Type: application/json
Body
{
  "data": {
    "id": 39,
    "identity": "I100115",
    "native_identity": "I100115",
    "created_at": "2019-01-04T14:52:21Z",
    "updated_at": "2019-01-04T14:52:21Z",
    "manufacturer": "AKG",
    "images": [
      {
        "id": 90,
        "url": "https://example.com/images/90/large.jpg",
        "thumbnail_url": "https://example.com/images/90/small.jpg",
        "created_at": "2019-01-04T14:52:21Z",
        "updated_at": "2019-01-04T14:52:21Z"
      }
    ],
    "item_type": {
      "id": 1,
      "name": "Device",
      "class_name": "ItemType"
    },
    "model": {
      "id": 510,
      "identity": "M100101",
      "name": "C414B-XLS",
      "manufacturer": "AKG",
      "description": ""
    },
    "category": "Microphones",
    "model_category": {
      "id": 12,
      "name": "Microphones",
      "class_name": "ModelCategory"
    },
    "department": "Audio",
    "serial": "10341",
    "current_user": "",
    "current_location": "collected",
    "can_have_contents": false,
    "description": "",
    "model_description": "",
    "state": "in_use",
    "complete_state": "available",
    "statuses": [
      "available",
      "maintenance_overdue"
    ],
    "custom_statuses": [
      {
        "status": "custom_status_42",
        "custom_status_id": 42,
        "text": "Missing",
        "colour": "red",
        "tooltip": "Inventory could not find this item",
        "automation_assigned": true
      }
    ],
    "maintenance_suggestions": [
      {
        "id": 13,
        "from_time": "2025-07-16T03:00:00+03:00",
        "item_id": 39,
        "maintenance_plan_id": 1,
        "perform_at": "2025-07-16T03:00:00+03:00",
        "state": "planned",
        "to_time": "2025-07-16T05:00:00+03:00"
      }
    ],
    "vendor": "",
    "location": {
      "location": {
        "id": 2,
        "identity": "L100008",
        "code": "1001",
        "name": "Main Stage"
      }
    },
    "root_location": "1001 Main Stage",
    "root_location_id": 2,
    "customer_contact_id": 72,
    "customer_contact_name": "Example Productions",
    "purchased": "2024-07-16",
    "price": "770.0",
    "purchase_price": "770.0",
    "usage_started": "2024-07-20",
    "total_cost": 920,
    "total_maintenance_hours": 2.5,
    "common_renewal_price": "850.0",
    "investment": "automatic",
    "purchase_investment": {
      "id": 8,
      "name": "INV-2024-12 Audio equipment renewal",
      "class_name": "Investment"
    },
    "purchase": {
      "id": 44,
      "name": "Audio equipment purchase",
      "class_name": "Purchase"
    },
    "estimated_lifespan": 12,
    "condition": 4,
    "condition_description": "Good condition",
    "estimated_lifespan_enddate": "2036-07-16"
  }
}
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",
    "native_identity": "I100115",
    "created_at": "2019-01-04T14:52:21Z",
    "updated_at": "2019-01-04T14:52:21Z",
    "manufacturer": "AKG",
    "images": [
      {
        "id": 90,
        "url": "https://example.com/images/90/large.jpg",
        "thumbnail_url": "https://example.com/images/90/small.jpg",
        "created_at": "2019-01-04T14:52:21Z",
        "updated_at": "2019-01-04T14:52:21Z"
      }
    ],
    "item_type": {
      "id": 1,
      "name": "Device",
      "class_name": "ItemType"
    },
    "model": {
      "id": 510,
      "identity": "M100101",
      "name": "C414B-XLS",
      "manufacturer": "AKG",
      "description": ""
    },
    "category": "Microphones",
    "model_category": {
      "id": 12,
      "name": "Microphones",
      "class_name": "ModelCategory"
    },
    "department": "Audio",
    "serial": "10341",
    "current_user": "",
    "current_location": "collected",
    "can_have_contents": false,
    "description": "",
    "model_description": "",
    "state": "in_use",
    "complete_state": "available",
    "statuses": [
      "available",
      "maintenance_overdue"
    ],
    "custom_statuses": [
      {
        "status": "custom_status_42",
        "custom_status_id": 42,
        "text": "Missing",
        "colour": "red",
        "tooltip": "Inventory could not find this item",
        "automation_assigned": true
      }
    ],
    "maintenance_suggestions": [
      {
        "id": 13,
        "from_time": "2025-07-16T03:00:00+03:00",
        "item_id": 39,
        "maintenance_plan_id": 1,
        "perform_at": "2025-07-16T03:00:00+03:00",
        "state": "planned",
        "to_time": "2025-07-16T05:00:00+03:00"
      }
    ],
    "vendor": "",
    "location": {
      "location": {
        "id": 2,
        "identity": "L100008",
        "code": "1001",
        "name": "Main Stage"
      }
    },
    "root_location": "1001 Main Stage",
    "root_location_id": 2,
    "customer_contact_id": 72,
    "customer_contact_name": "Example Productions",
    "purchased": "2024-07-16",
    "price": "770.0",
    "purchase_price": "770.0",
    "usage_started": "2024-07-20",
    "total_cost": 920,
    "total_maintenance_hours": 2.5,
    "common_renewal_price": "850.0",
    "investment": "automatic",
    "purchase_investment": {
      "id": 8,
      "name": "INV-2024-12 Audio equipment renewal",
      "class_name": "Investment"
    },
    "purchase": {
      "id": 44,
      "name": "Audio equipment purchase",
      "class_name": "Purchase"
    },
    "estimated_lifespan": 12,
    "condition": 4,
    "condition_description": "Good condition",
    "estimated_lifespan_enddate": "2036-07-16"
  }
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "errors": [
    "api.v1.items.item_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",
    "native_identity": "I100115",
    "created_at": "2019-01-04T14:52:21Z",
    "updated_at": "2019-01-04T14:52:21Z",
    "manufacturer": "AKG",
    "images": [
      {
        "id": 90,
        "url": "https://example.com/images/90/large.jpg",
        "thumbnail_url": "https://example.com/images/90/small.jpg",
        "created_at": "2019-01-04T14:52:21Z",
        "updated_at": "2019-01-04T14:52:21Z"
      }
    ],
    "item_type": {
      "id": 1,
      "name": "Device",
      "class_name": "ItemType"
    },
    "model": {
      "id": 510,
      "identity": "M100101",
      "name": "C414B-XLS",
      "manufacturer": "AKG",
      "description": ""
    },
    "category": "Microphones",
    "model_category": {
      "id": 12,
      "name": "Microphones",
      "class_name": "ModelCategory"
    },
    "department": "Audio",
    "serial": "10341",
    "current_user": "",
    "current_location": "collected",
    "can_have_contents": false,
    "description": "",
    "model_description": "",
    "state": "in_use",
    "complete_state": "available",
    "statuses": [
      "available",
      "maintenance_overdue"
    ],
    "custom_statuses": [
      {
        "status": "custom_status_42",
        "custom_status_id": 42,
        "text": "Missing",
        "colour": "red",
        "tooltip": "Inventory could not find this item",
        "automation_assigned": true
      }
    ],
    "maintenance_suggestions": [
      {
        "id": 13,
        "from_time": "2025-07-16T03:00:00+03:00",
        "item_id": 39,
        "maintenance_plan_id": 1,
        "perform_at": "2025-07-16T03:00:00+03:00",
        "state": "planned",
        "to_time": "2025-07-16T05:00:00+03:00"
      }
    ],
    "vendor": "",
    "location": {
      "location": {
        "id": 2,
        "identity": "L100008",
        "code": "1001",
        "name": "Main Stage"
      }
    },
    "root_location": "1001 Main Stage",
    "root_location_id": 2,
    "customer_contact_id": 72,
    "customer_contact_name": "Example Productions",
    "purchased": "2024-07-16",
    "price": "770.0",
    "purchase_price": "770.0",
    "usage_started": "2024-07-20",
    "total_cost": 920,
    "total_maintenance_hours": 2.5,
    "common_renewal_price": "850.0",
    "investment": "automatic",
    "purchase_investment": {
      "id": 8,
      "name": "INV-2024-12 Audio equipment renewal",
      "class_name": "Investment"
    },
    "purchase": {
      "id": 44,
      "name": "Audio equipment purchase",
      "class_name": "Purchase"
    },
    "estimated_lifespan": 12,
    "condition": 4,
    "condition_description": "Good condition",
    "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

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. Matches any selected state. An omitted or empty array imposes no reservation-state restriction.

  • search[sales_states_filter] (array, optional) - Filter by sales states. Matches any selected sales state. When both state filter arrays are nonempty, reservations must match both groups (AND between groups, OR within each group). An omitted or empty array imposes no additional sales-state restriction; the organization setting to hide lost reservations by default still applies.

  • 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
  }
}