Pathwize API

Items

Push the images, documents or prompts you want labeled, by URL or as a direct upload.

An item is one unit of work: one photo, one document, one prompt. You identify it with your own id, which comes back on every result so you can join it to your data. Items are deduplicated per task on that ID.

Push items by URL

POST/tasks/{task_id}/items

Send a JSON body with an items array (1 to 1,000 items). Each item needs a url we can fetch within 20 seconds. We copy the file into Pathwize storage right away, so the URL may expire afterwards (pre-signed URLs work well). Experts never access your servers.

curl https://www.gopathwize.com/api/v1/tasks/TASK_ID/items \
  -H "Authorization: Bearer pw_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2026-09-25-batch-07" \
  -d '{
    "items": [
      {
        "id": "werk-nord-2026-09-25-000871",
        "url": "https://storage.example.com/loads/2026-09-25/000871.jpg",
        "mime": "image/jpeg",
        "checksum": "sha256:9f3a...",
        "width": 4032,
        "height": 3024,
        "captured_at": "2026-09-25T07:12:04+02:00",
        "group": "werk-nord",
        "meta": { "site": "Werk Nord", "scale_kg": 12480 }
      }
    ]
  }'

Item fields

idstringrequired: Your identifier, unique within the task, up to 200 printable ASCII characters without spaces. Use something stable, for example werk-nord-2026-09-25-000871.
urlstringrequired: HTTPS (or HTTP) URL of the file. Required for JSON pushes; omitted for direct uploads.
mimestringrequired: image/jpeg, image/png, image/webp, application/pdf, text/plain or application/json. Must match what the URL serves.
checksumstring: sha256:<hex> of the file. We verify it after download and reject mismatches, which catches truncated or swapped files.
width, heightinteger: Pixel size of images. Lets us return box coordinates without decoding the file first.
captured_atstring: ISO 8601 timestamp when the item was captured. Used for queue order and daily reporting.
groupstring: Free grouping key (site, camera, customer), up to 100 characters. Results can be filtered and reported per group.
priorityinteger: 0 normal (default) or 1 urgent. Urgent items go to the front of the queue.
hintsobject: Up to 2 KB. model_label and model_confidence stay hidden (ordering and quality reports); label or regions are shown to experts as a pre-annotation to confirm or correct. See model hints.
metaobject: Up to 4 KB of your own data. Stored untouched and returned on every result.

Response

{
  "accepted": 996,
  "duplicates": 3,
  "rejected": [
    { "id": "werk-nord-2026-09-25-000902", "param": "items[41].mime", "message": "mime is required (for example image/jpeg)." }
  ]
}

accepted items were created, duplicates already existed (same ID, nothing changed) and rejected lists items that failed validation with the offending field. A request with at least one accepted item returns 201, otherwise 200. A rejected item never blocks the others.

Idempotency

Add an Idempotency-Key header (any string up to 255 characters, for example your batch ID) and retries of the same request return the original response instead of creating anything twice. Item IDs already protect against duplicates; the header additionally makes the response replayable after a network error.

Direct upload

POST/tasks/{task_id}/items

When your files are not reachable by URL, send one item per request as multipart/form-data with a file part and the item fields as form fields (hints and meta as JSON strings). Files up to 20 MB. For large volumes prefer URLs, which allow 1,000 items per request.

curl https://www.gopathwize.com/api/v1/tasks/TASK_ID/items \
  -H "Authorization: Bearer pw_live_..." \
  -F "file=@truck_000871.jpg;type=image/jpeg" \
  -F "id=werk-nord-2026-09-25-000871" \
  -F "group=werk-nord" \
  -F 'meta={"site":"Werk Nord","scale_kg":12480}'

Item lifecycle

Status	Meaning
`queued`	Accepted, file not copied yet. Usually seconds; at most a few minutes.
`ready`	File stored, waiting in the experts' queue.
`in_progress`	At least one expert is working on it.
`labeled`	All raters done. The result is available.
`flagged`	Done, but needs attention: low agreement, unreadable, or an expert raised a flag. The result carries the reason.
`failed`	We could not fetch or store the file. `error` says why. Fix the URL and push again with the same ID after deleting it, or use a new ID.

List items

GET/tasks/{task_id}/items

Query parameters

statusstring: Filter by one status from the table above.
sincestring: Only items created after this ISO 8601 timestamp.
starting_afterstring: Item ID to page from (exclusive). Items come in creation order.
limitinteger: 1 to 500, default 100.

curl "https://www.gopathwize.com/api/v1/tasks/TASK_ID/items?status=failed&limit=100" \
  -H "Authorization: Bearer pw_live_..."

Item object

{
  "id": "werk-nord-2026-09-25-000871",
  "status": "labeled",
  "mime": "image/jpeg",
  "checksum": "sha256:9f3a...",
  "width": 4032,
  "height": 3024,
  "captured_at": "2026-09-25T05:12:04.000Z",
  "group": "werk-nord",
  "priority": 0,
  "meta": { "site": "Werk Nord", "scale_kg": 12480 },
  "error": null,
  "created_at": "2026-09-25T05:14:40.201Z",
  "result": {
    "label": "Bauschutt",
    "labels_all": ["Bauschutt", "Bauschutt"],
    "agreement": 1.0,
    "raters": 2,
    "boxes": [],
    "note": null,
    "flags": [],
    "labeled_at": "2026-09-25T13:40:12.000Z"
  }
}