API Reference

REST API for the Techfleet Sync platform. Base URL: https://api.techfleet.dev/v1

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard under Settings → API Keys. Keys can be scoped to read-only or read-write.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Rate limits

100 req/min on Starter, 1,000 req/min on Pro, custom on Enterprise.

Versioning

The current stable API version is v1. Breaking changes are communicated 90 days in advance.

Device Catalog API

New

The world's most enriched device catalog — 5,300+ devices across 13 categories with normalized specs, model numbers, GTIN/UPC barcodes, and resale pricing. Built for AI agents and commerce platforms.

Base URL: https://sync.techfleet.dev/api/catalog

GET/api/catalog/devices

Search devices

Search the global device catalog by name, model number, or keyword. Returns normalized specs, match confidence, and data quality scores. Supports filtering by make, category, release date, and sorting by spec fields like battery, RAM, or display size.

QUERY PARAMETERS

q

string

Search query — device name, model number, or keyword. Uses full-text search with ranked results.

make

string

Filter by manufacturer (e.g. Apple, Samsung, Google).

category

string

Filter by category: Smartphones, Tablets, Laptops, Smartwatches, Audio, Gaming Consoles, VR Headsets, etc.

released_year

integer

Filter by release year (e.g. 2024).

released_from

string

ISO date. Only devices released on or after this date.

released_to

string

ISO date. Only devices released on or before this date.

sort_by

string

Sort by normalized spec field: battery_mah, ram_gb, display_size_in, weight_g, name, release_date.

order

string

Sort direction: asc or desc. Default: desc.

page

integer

Page number. Default: 1.

per_page

integer

Results per page. Default: 50, max: 200.

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/devices?q=iPhone+16+Pro&make=Apple&sort_by=battery_mah&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "data": [
    {
      "name": "iPhone 16 Pro Max",
      "slug": "iphone-16-pro-max",
      "make": "Apple",
      "category": "Smartphones",
      "image_url": "https://fdn2.gsmarena.com/vv/bigpic/apple-iphone-16-pro-max.jpg",
      "release_date": "2024-09-20",
      "match_certainty": 97,
      "match_type": "exact_name",
      "model_numbers": "A3089, A3290, A3291",
      "gtin": "0195949770272",
      "normalized_specs": {
        "display_size_in": 6.9,
        "ram_gb": 8,
        "battery_mah": 4685,
        "chipset": "Apple A18 Pro",
        "weight_g": 227,
        "os": "iOS 18",
        "fast_charge_w": 27,
        "storage_options_gb": [256, 512, 1024],
        "colors": ["Black Titanium", "White Titanium", "Natural Titanium", "Desert Titanium"]
      }
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 1 },
  "request_id": "req_a1b2c3d4e5f6"
}

GET/api/catalog/devices/:slug

Get device details

Returns full specifications, normalized numeric fields, model numbers, GTIN/UPC barcode, resale market pricing, and a data quality score for a single device. The data_quality_score (0-100) reflects how complete the device record is across all fields.

QUERY PARAMETERS

slug

string

requiredDevice slug (e.g. iphone-16-pro-max).

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/devices/iphone-16-pro-max" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "data": {
    "name": "iPhone 16 Pro Max",
    "slug": "iphone-16-pro-max",
    "make": "Apple",
    "category": "Smartphones",
    "image_url": "https://fdn2.gsmarena.com/vv/bigpic/apple-iphone-16-pro-max.jpg",
    "release_date": "2024-09-20",
    "model_numbers": "A3089, A3290, A3291",
    "gtin": "0195949770272",
    "data_quality_score": 95,
    "specs": { "Display Size": "6.9 inches", "RAM": "8 GB", ... },
    "normalized_specs": {
      "display_size_in": 6.9,
      "ram_gb": 8,
      "battery_mah": 4685,
      "chipset": "Apple A18 Pro",
      "weight_g": 227,
      "os": "iOS 18"
    },
    "pricing": {
      "avg_price_usd": 89900,
      "min_price_usd": 79900,
      "max_price_usd": 119900,
      "sources": 3,
      "last_updated": "2025-03-10T14:00:00Z"
    }
  },
  "request_id": "req_f6e5d4c3b2a1"
}

GET/api/catalog/autocomplete

Autocomplete device names

Returns instant suggestions as the user types. Optimized for speed (<100ms). Supports optional make and category filters. Ideal for search bars and AI agent type-ahead.

QUERY PARAMETERS

q

string

requiredSearch prefix (minimum 2 characters).

limit

integer

Max suggestions. Default: 10, max: 25.

make

string

Filter suggestions to a specific manufacturer.

category

string

Filter suggestions to a specific category.

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/autocomplete?q=iphone+16&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "suggestions": [
    { "name": "iPhone 16 Pro Max", "slug": "iphone-16-pro-max", "make": "Apple", "category": "Smartphones", "image_url": "...", "release_year": 2024 },
    { "name": "iPhone 16 Pro", "slug": "iphone-16-pro", "make": "Apple", "category": "Smartphones", "image_url": "...", "release_year": 2024 },
    { "name": "iPhone 16 Plus", "slug": "iphone-16-plus", "make": "Apple", "category": "Smartphones", "image_url": "...", "release_year": 2024 }
  ],
  "request_id": "req_1a2b3c4d"
}

GET/api/catalog/compare

Compare devices

Side-by-side comparison of 2-4 devices. Returns normalized specs for each device plus a diff object highlighting where specs differ. Perfect for AI agents evaluating trade-in alternatives or recommending upgrades.

QUERY PARAMETERS

slugs

string

requiredComma-separated device slugs (2-4). E.g. iphone-16-pro,samsung-galaxy-s25-ultra.

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/compare?slugs=iphone-16-pro-max,samsung-galaxy-s25-ultra" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "devices": [
    { "slug": "iphone-16-pro-max", "name": "iPhone 16 Pro Max", "make": "Apple", "normalized_specs": { "display_size_in": 6.9, "ram_gb": 8, "battery_mah": 4685 } },
    { "slug": "samsung-galaxy-s25-ultra", "name": "Samsung Galaxy S25 Ultra", "make": "Samsung", "normalized_specs": { "display_size_in": 6.9, "ram_gb": 12, "battery_mah": 5000 } }
  ],
  "diff": {
    "ram_gb": { "iphone-16-pro-max": 8, "samsung-galaxy-s25-ultra": 12 },
    "battery_mah": { "iphone-16-pro-max": 4685, "samsung-galaxy-s25-ultra": 5000 },
    "chipset": { "iphone-16-pro-max": "Apple A18 Pro", "samsung-galaxy-s25-ultra": "Snapdragon 8 Elite" }
  },
  "request_id": "req_cmp_9876"
}

GET/api/catalog/makes

List manufacturers

Returns all manufacturers in the catalog with device counts and official website URLs. Use make IDs or names to filter other catalog endpoints.

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/makes" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "data": [
    { "id": "bf444899-...", "name": "Apple", "slug": "apple", "device_count": 87, "website_url": "https://apple.com" },
    { "id": "18808264-...", "name": "Samsung", "slug": "samsung", "device_count": 943, "website_url": "https://samsung.com" }
  ],
  "request_id": "req_mk_1234"
}

GET/api/catalog/stats

Catalog coverage stats

Returns total device count, field coverage percentages (specs, images, model numbers, GTINs), breakdown by category and manufacturer, and last-updated timestamps. Useful for monitoring data quality.

EXAMPLE REQUEST

curl -X GET "https://sync.techfleet.dev/api/catalog/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "total_devices": 5358,
  "coverage": {
    "specs": 100.0,
    "images": 100.0,
    "model_numbers": 54.2,
    "gtin": 1.8
  },
  "by_category": [
    { "name": "Smartphones", "count": 3200 },
    { "name": "Tablets", "count": 450 }
  ],
  "by_make": [
    { "name": "Samsung", "count": 943 },
    { "name": "Apple", "count": 87 }
  ],
  "last_updated": "2026-04-08T06:00:00Z",
  "request_id": "req_st_5678"
}

Merchant API

Inventory, orders, and sales channel management for authenticated merchants.

GET/api/v1/inventory

List inventory

Returns a paginated list of your inventory items. Supports filtering by model, grade, carrier status, price range, and availability.

QUERY PARAMETERS

page

integer

Page number. Default: 1.

per_page

integer

Items per page. Default: 50, max: 200.

model

string

Filter by device model (e.g. iPhone 14 Pro).

grade

string

Filter by grade: A+, A, B, C, D.

carrier_locked

boolean

Filter by carrier lock status.

min_battery

integer

Minimum battery health percentage.

available

boolean

When true, returns only units not yet assigned to an order.

warehouse_id

string

Filter by specific warehouse location.

EXAMPLE REQUEST

curl -X GET "https://api.techfleet.dev/v1/inventory?grade=A&available=true&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

EXAMPLE RESPONSE

{
  "data": [
    {
      "id": "inv_01h9xmk2n3p5r7t9",
      "imei": "352099001761481",
      "model": "iPhone 14 Pro",
      "storage": "256GB",
      "color": "Space Black",
      "grade": "A",
      "battery_health": 88,
      "carrier_locked": false,
      "carrier": null,
      "price": 54900,
      "currency": "USD",
      "warehouse_id": "wh_toronto_01",
      "available": true,
      "created_at": "2025-01-15T10:23:00Z",
      "updated_at": "2025-03-10T14:55:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 1842,
    "pages": 37
  }
}

GET/api/v1/products

List product catalog

Returns your aggregate product catalog — grouped by model/grade/storage combination with total available quantity and pricing statistics.

QUERY PARAMETERS

model

string

Filter by device model.

include_pricing

boolean

When true, includes min/max/avg pricing per SKU. Default: false.

EXAMPLE REQUEST

curl -X GET "https://api.techfleet.dev/v1/products?include_pricing=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "data": [
    {
      "sku": "APP-IP14P-256-A",
      "model": "iPhone 14 Pro",
      "storage": "256GB",
      "grade": "A",
      "quantity_available": 47,
      "quantity_total": 52,
      "pricing": {
        "min": 51900,
        "max": 57500,
        "avg": 54200,
        "currency": "USD"
      }
    }
  ],
  "meta": { "total": 214 }
}

GET/api/v1/orders

List orders

Returns a paginated list of your orders. Filter by status, date range, or buyer.

QUERY PARAMETERS

status

string

Filter by status: pending, confirmed, shipped, delivered, cancelled.

from

string

ISO 8601 date. Return orders created after this date.

to

string

ISO 8601 date. Return orders created before this date.

buyer_id

string

Filter by buyer ID.

EXAMPLE REQUEST

curl -X GET "https://api.techfleet.dev/v1/orders?status=confirmed&from=2025-03-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

EXAMPLE RESPONSE

{
  "data": [
    {
      "id": "ord_01h9xmk2n3p5r7t9",
      "status": "confirmed",
      "buyer_id": "buy_01h8abc123",
      "buyer_name": "PhoneVault Inc.",
      "line_items": [
        {
          "inventory_id": "inv_01h9xmk2n3p5r7t9",
          "imei": "352099001761481",
          "model": "iPhone 14 Pro",
          "grade": "A",
          "price": 54900
        }
      ],
      "total": 54900,
      "currency": "USD",
      "created_at": "2025-03-10T09:12:00Z"
    }
  ],
  "meta": { "total": 1203 }
}

POST/api/v1/orders

Create an order

Creates a new order, reserving the specified inventory items. Items are held for 15 minutes while the order is in 'pending' status. Confirming the order transitions it to 'confirmed' and locks the inventory.

REQUEST BODY

buyer_id

string

requiredID of the buyer placing the order.

line_items

array

requiredArray of {inventory_id, price} objects.

notes

string

Optional order notes.

EXAMPLE REQUEST

curl -X POST "https://api.techfleet.dev/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer_id": "buy_01h8abc123",
    "line_items": [
      { "inventory_id": "inv_01h9xmk2n3p5r7t9", "price": 54900 }
    ]
  }'

EXAMPLE RESPONSE

{
  "id": "ord_01h9xmk2n3p5r7t9",
  "status": "pending",
  "buyer_id": "buy_01h8abc123",
  "line_items": [
    {
      "inventory_id": "inv_01h9xmk2n3p5r7t9",
      "price": 54900,
      "reserved_until": "2025-03-10T09:27:00Z"
    }
  ],
  "total": 54900,
  "currency": "USD",
  "created_at": "2025-03-10T09:12:00Z"
}

POST/api/v1/channels/sync

Trigger a channel sync

Manually triggers an inventory sync to one or all connected sales channels. By default, syncs happen automatically when inventory changes. Use this endpoint to force a sync on demand.

REQUEST BODY

channel

string

Channel to sync: ebay, swappa, back_market, storefront. Omit to sync all channels.

inventory_ids

array

Array of inventory IDs to sync. Omit to sync all available inventory.

EXAMPLE REQUEST

curl -X POST "https://api.techfleet.dev/v1/channels/sync" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "ebay" }'

EXAMPLE RESPONSE

{
  "sync_id": "sync_01h9xmk2n3p5r7t9",
  "status": "queued",
  "channels": ["ebay", "swappa"],
  "inventory_count": 1842,
  "queued_at": "2025-03-10T09:12:00Z",
  "estimated_completion": "2025-03-10T09:12:45Z"
}

Error codes

400

Bad Request — Missing or invalid parameters.

401

Unauthorized — Invalid or missing API key.

403

Forbidden — Valid key but insufficient permissions for this operation.

404

Not Found — The requested resource does not exist.

409

Conflict — The action conflicts with current state (e.g. ordering an already-sold unit).

422

Unprocessable Entity — Request was well-formed but failed validation rules.

429

Rate Limited — Too many requests. See Retry-After header.

500

Internal Server Error — Unexpected server error. Retry with exponential backoff.