Quick start

This walkthrough starts with read requests. You need a customer API token from Settings → API Access, cURL, and at least one asset to follow the detail and timeline examples. A Read Only token works for steps 1–3. The final step writes a note and requires assets:events.

1. Set your token#

In a Bash terminal, read the token without displaying it or putting its value in your command history:

read -rsp "AssetCenter API token: " ASSETCENTER_API_TOKEN
export ASSETCENTER_API_TOKEN
printf '\n'
export ASSETCENTER_API_URL="https://my.assetcenter.app/api/v1"

Use server-side secret storage in a deployed integration. Never embed the token in browser JavaScript or a public repository.

2. List your assets#

curl --fail-with-body "$ASSETCENTER_API_URL/assets?per_page=25" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json"

A successful request returns 200, with records in data and pagination information in links and meta. An organization with no assets returns an empty data array. Use the app or create an asset before continuing. Lists are ordered by ID, newest first; follow links.next to fetch additional pages.

3. Read a record and its history#

Replace 123 with an ID returned by the list. The numeric record ID is different from the asset tag printed on a label.

export ASSET_ID=123
curl --fail-with-body "$ASSETCENTER_API_URL/assets/$ASSET_ID" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json"

curl --fail-with-body "$ASSETCENTER_API_URL/assets/$ASSET_ID/timeline?per_page=25" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json"

Details return one object under data. Timeline results are paginated and include event IDs, dates, types, descriptions, and related records. Related information is limited by your token’s read permissions.

4. Add a note#

This creates a real timeline note. Use a token with assets:events and an asset intended for your integration test. Set a new UUID as the idempotency key. If uuidgen is unavailable, set this variable to a unique 8–128 character value containing letters, numbers, dots, underscores, colons, or hyphens.

export IDEMPOTENCY_KEY="$(uuidgen)"
curl --fail-with-body --request POST "$ASSETCENTER_API_URL/assets/$ASSET_ID/notes" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{"description":"Inventory verified by our integration."}'

Expect 201 Created, with data.asset_id, asset_event_ids, and the current state. If the request times out, retry the same command with the same key and body. A replay returns the original result and Idempotency-Replayed: true. Generate a new key for the next distinct action.

Continue building#

Use the endpoint pages for exact permissions, fields, responses, and workflow constraints. Read errors and rate limits before scheduling requests, and idempotency before implementing retries. For a 401, check the token; for a 403, check the required permission and the creator’s administrator access.