Usage examples ​

All examples use curl. Put your key in an environment variable first so you don't paste it into every command:

bash
export ITEFY_KEY="itf_live_<id>_<secret>"
export ITEFY_API="https://api.itefy.com"

Health check (no auth) ​

bash
curl "$ITEFY_API/v1/ping"

Who am I ​

Confirm your key works and see which account and user it acts as:

bash
curl -H "Authorization: Bearer $ITEFY_KEY" \
  "$ITEFY_API/v1/whoami"

List items ​

Collections paginate with limit and offset; meta.pagination.next_offset is null on the last page:

bash
curl -H "Authorization: Bearer $ITEFY_KEY" \
  "$ITEFY_API/v1/items?limit=50&offset=0"
json
{
  "data": [
    { "id": 101, "name": "Cordless drill", "unique_id": "TOOL-001" }
  ],
  "meta": {
    "request_id": "req_…",
    "pagination": { "total": 128, "limit": 50, "offset": 0, "next_offset": 50 }
  }
}

Get a single item ​

bash
curl -H "Authorization: Bearer $ITEFY_KEY" \
  "$ITEFY_API/v1/items/101"

Create an item ​

Send a JSON body with Content-Type: application/json:

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Impact wrench", "unique_id": "TOOL-002" }' \
  "$ITEFY_API/v1/items"

The new item is returned under data, and the Location header points at its URL.

Change an item's condition ​

condition is one of operative, inoperative or discarded:

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "condition": "inoperative", "remarks": "Trigger sticking" }' \
  "$ITEFY_API/v1/items/101/condition"

Workflow: scan → check out → check in ​

The three calls behind a typical lending flow. First resolve a scanned QR label to the item:

bash
curl -H "Authorization: Bearer $ITEFY_KEY" \
  "$ITEFY_API/v1/items/lookup?qr=<scanned-value>"

Check the item out (iid takes one or more item ids; due_time must be at least 5 minutes in the future):

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Field work", "iid": [101], "due_time": "2026-08-07T16:00:00Z" }' \
  "$ITEFY_API/v1/checkouts"

Check it back in again (omit iid to return everything still out on the checkout):

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "remarks": "Returned in good condition" }' \
  "$ITEFY_API/v1/checkouts/55/checkin"

Workflow: report an issue ​

Create an issue on an item — autochange_condition: true also flips the items to Inoperative while the issue is open:

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lens jammed",
    "iid": [101],
    "deadline": "2026-08-01T12:00:00Z",
    "description": "Zoom ring stuck; unusable for shoots.",
    "autochange_condition": true
  }' \
  "$ITEFY_API/v1/issues"

Close it when resolved:

bash
curl -X POST \
  -H "Authorization: Bearer $ITEFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "closed" }' \
  "$ITEFY_API/v1/issues/12/status"

Handling errors ​

Non-2xx responses carry a machine-readable error.code:

json
{ "error": { "code": "invalid_api_key", "message": "Invalid or revoked API key.", "status": 401 } }

Branch on error.code (e.g. invalid_api_key, not_found, plan_upgrade_required, rate_limited) rather than the message text.

TIP

The full set of endpoints, parameters and schemas — with a Try it out button — is in the API reference.

Related articles