Assets

Assets is the register of what a team owns and manages: laptops, domains, licences, servers. Every asset has a type, and a type defines its own custom fields and statuses. This page covers the types, the fields and the assets themselves.

Two scopes: assets:read reads, assets:write registers and changes. Like every scope, they only narrow what the token's owner may do. The owner's rights decide the rest:

• The workspace must have Assets switched on, and the owner must be a member who may use it. A guest (a client) gets 403, and so does a workspace without Assets.
• Creating types and fields is for workspace administrators. Everything else (registering, changing, archiving, issuing, returning, renewing, relating) is for every member who can see the asset's type.
• A type can be visible to everybody, to the members of one team, or to administrators only. A type you cannot see is not in any list, and its assets and the type itself answer 404, never 403.
• A sensitive field is left out of every answer unless you are an administrator. When you write values, the stored value of a sensitive field stays untouched, whatever you send.

Identifiers#

An asset is addressed by its identifier: the prefix of its type, a dash and its number in that type, such as LAP-12. In this API the identifier goes where {asset} is. Matching ignores case (lap-12 works). Identifiers are unique per workspace. Types and fields are addressed by their numeric id.

An identifier that does not exist, or that belongs to a type you cannot see, is a 404. An archived asset still resolves.

The asset object#

{
  "id": 41,
  "identifier": "LAP-12",
  "name": "MacBook Pro 14",
  "url": "https://assets.polder.work/assets/41",
  "type": { "id": 3, "name": "Laptop", "prefix": "LAP", "icon": "laptop", "color": "#2563eb", "archived": false },
  "status": { "id": 7, "name": "In use", "color": "#16a34a", "category": "active" },
  "owner": { "key": "team:2", "type": "team", "id": 2, "name": "Engineering" },
  "holder": { "key": "user:5", "type": "user", "id": 5, "name": "Sanne" },
  "values": { "serial_number": "C02XL1ABC", "purchase_price": { "amount": 2199.0, "currency": "EUR" } },
  "nextDeadline": "2027-03-01",
  "archived": false,
  "updatedAt": "2026-10-20T09:14:00+00:00"
}

Note that this object uses camelCase (nextDeadline, updatedAt), unlike most of the Backlog API.

Custom fields#

Each type defines fields. A field has a stable key that is made from its label when you create it (Serial number becomes serial_number, a second one gets _2). Renaming a field later changes only its label, never the key. Values are stored and sent by key, in the shape the field type calls for:

A required field must be present. Sending null or an empty string clears a value. A date or datetime field can be marked expires: it then counts as a deadline, gets reminders and shows up in nextDeadline, expiring and renew.

Defaults apply when you create an asset: a field's default fills any value you leave out. A status can also require fields: moving an asset into that status (or creating it there) fails with 422 on status_id while a required field is empty. Adding a requirement does not lock assets already in the status.

List asset types#

Returns the active (non-archived) types you may see, in their set order, each with its statuses and fields.

curl https://backlog.polder.work/api/v1/workspaces/7/asset-types \
  -H "Authorization: Bearer $POLDER_TOKEN"

{
  "data": [
    {
      "id": 3,
      "name": "Laptop",
      "prefix": "LAP",
      "icon": "laptop",
      "color": "#2563eb",
      "archived": false,
      "description": null,
      "visibility": "workspace",
      "statuses": [
        { "id": 6, "name": "In stock", "color": "#9ca3af", "category": "planned" },
        { "id": 7, "name": "In use", "color": "#16a34a", "category": "active" },
        { "id": 8, "name": "Retired", "color": "#6b7280", "category": "closed" }
      ],
      "fields": [
        {
          "id": 11, "key": "serial_number", "label": "Serial number", "type": "text",
          "required": false, "options": null, "default": null, "help": null, "section": null,
          "showInList": true, "sensitive": false, "expires": false,
          "reminderDays": [], "renewMonths": null, "archived": false
        }
      ]
    }
  ]
}

Archived fields are not listed. Sensitive fields are listed for administrators only.

Get an asset type#

One type in the same shape as above. 404 if the type does not exist in this workspace, is archived, or is one you may not see.

Create an asset type#

Administrators only (403 otherwise). A new type comes with three starting statuses (in stock, in use, retired). The first type of a workspace also brings the standard relation kinds. Answers 201 with the type.

Body

curl https://backlog.polder.work/api/v1/workspaces/7/asset-types \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Laptop", "visibility": "team", "team_id": 3}'

Changing or archiving a type, and its statuses, are not part of the API; use the Assets screens.

Add a field to a type#

Administrators only. Answers 201 with the new field. The field is added at the end of the type.

Body

options by type

curl https://backlog.polder.work/api/v1/workspaces/7/asset-types/3/fields \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "Warranty ends", "type": "date", "expires": true, "reminder_days": [30, 7, 0], "renew_months": 12}'

{ "data": { "id": 14, "key": "warranty_ends", "label": "Warranty ends", "type": "date", "required": false, "sensitive": false, "expires": true } }

Marking a field as expiring rebuilds the deadlines of every active asset of the type.

Change a field#

Administrators only. Takes the same body as creating a field, with every field optional; only what you send changes. 404 if the field is not on this type.

The type of a field cannot change once any asset has a value for it (422 on type). Archive the field in the app and add a new one instead. The key never changes.

Answers 200 with the same short field shape as creating.

List relation kinds#

The kinds of relation the workspace has, to use as relation_type_id when you relate two assets. Empty until the first asset type exists.

{ "data": [ { "id": 1, "key": "runs_on", "name": "runs on", "inverse_name": "hosts", "hierarchical": true } ] }

hierarchical kinds refuse a loop (A part of B part of A).

List assets#

Assets of the types you may see, newest change first. Archived assets are left out unless you ask for them.

Query

curl "https://backlog.polder.work/api/v1/workspaces/7/assets?type=3&expiring=30&per_page=20" \
  -H "Authorization: Bearer $POLDER_TOKEN"

{
  "data": [ { "identifier": "LAP-12", "name": "MacBook Pro 14", "nextDeadline": "2026-11-14", "…": "…" } ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "last_page": 1 }
}

The order is fixed. There is no sort parameter in the API.

Get an asset#

One asset: everything in the asset object plus notes, deadlines and relations. {asset} is the identifier.

{
  "data": {
    "identifier": "LAP-12",
    "notes": "Bought with the Q3 batch.",
    "deadlines": [
      { "key": "warranty_ends", "label": "Warranty ends", "dueOn": "2026-11-14", "daysLeft": 17, "renewMonths": 12, "reminderDays": [30, 7, 0] }
    ],
    "relations": [
      { "label": "runs on", "asset": { "identifier": "SRV-1", "name": "Host 1", "url": "https://assets.polder.work/assets/9", "status": "In use" } }
    ],
    "…": "…"
  }
}

relations lists both directions; label is already worded from this asset's side ("runs on" or "hosts"). Related assets you may not see are left out.

Get the history of an asset#

Everything that happened to the asset, newest first, paged like a list (page, per_page).

{
  "data": [
    { "id": 310, "kind": "issued", "by": 5, "data": { "to": "user:5", "name": "Sanne", "condition": "good" }, "at": "2026-10-20T09:14:00+00:00" }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 12, "last_page": 1 }
}

by is the user id (or null for the system). kind includes created, updated (with data.changes, field by field as [old, new]), status, owner, issued, returned, renewed, related, unrelated, archived, restored, reminded, holder_left, commented, linked and unlinked. data depends on the kind.

Create an asset#

Registers an asset. It takes the next number of its type, so the identifier is in the answer. Goes through the same action as the app: values are validated, the history gets a created event, Flows and notifications hear about it. Answers 201 with the asset.

Body

curl https://backlog.polder.work/api/v1/workspaces/7/assets \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"asset_type_id": 3, "name": "MacBook Pro 14", "owner": "team:2", "holder": "user:5",
       "values": {"serial_number": "C02XL1ABC", "warranty_ends": "2027-03-01"}}'

Validation errors are 422 and name the field: values.warranty_ends for a field value, status_id for a missing required field.

Change an asset#

Only what you send changes.

The holder is not changed here; use issue and return. The history records what changed, with a separate status and owner event when those moved. Answers 200 with the asset.

Archive or restore an asset#

Assets are never deleted: the number stays taken and the history stays readable. Send {"restore": true} to bring an archived asset back. Both directions are idempotent.

{ "data": { "archived": true } }

Issue an asset#

Hands the asset to a member, a team or a customer. Whoever has it now gets it taken back first (without a returned event), the hand-over is written down with its condition, and the new party becomes the holder. Answers 200 with the asset.

curl https://backlog.polder.work/api/v1/workspaces/7/assets/LAP-12/issue \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to": "user:5", "condition": "good, with charger"}'

Return an asset#

Takes the asset back from its holder. Body is optional: condition (max 200) and note (max 2000). An asset nobody holds is not an error: nothing changes. Answers 200 with the asset.

Renew a deadline#

Moves a date field that runs out to its next date: the certificate was renewed, the warranty extended.

Reminders start over by themselves, and the history records renewed as well as the change. Answers 200 with the asset.

curl https://backlog.polder.work/api/v1/workspaces/7/assets/CRT-3/renew \
  -H "Authorization: Bearer $POLDER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"field": "expires_on", "to": "2027-01-01"}'

Relate two assets#

Links this asset to another one. Reading the relation as "asset kind with" gives the default direction: LAP-12 runs on SRV-1 is {asset} = LAP-12, with = SRV-1.

It is 422 to relate an asset to itself, to assets of different workspaces, or to loop a hierarchical kind. Relating the same pair twice is not an error and creates nothing new. Both assets get a related history event.

Answers 201 with the asset's relations, including the id you need to remove one:

{ "data": { "relations": [ { "id": 5, "label": "runs on", "asset": { "identifier": "SRV-1", "name": "Host 1", "url": "…", "status": "In use" } } ] } }

Note The relations in Get an asset carry no id. To remove a relation you need the id from the answer here.

Remove a relation#

{relation} is the relation id. 404 if it does not involve this asset, or if you may not see the asset on its other end. Both assets get an unrelated event.

{ "data": { "removed": true } }

Errors#

The same actions are available to assistants as the MCP tools list_asset_types, list_assets, get_asset, create_asset and update_asset.