Skip to content
Hubtask

API reference · Hubtask API 0.1.0

imports

POST /imports

Import entries from another system into a hub

Takes a file somebody exported elsewhere - a CSV, a Trello board, a Google Tasks export, a Microsoft To Do dump - and lands its contents as collections under the named hub. One ingestion path: the file is converted into the same records a backup archive holds and applied through the restore in MERGE mode with skip, under identities derived from the source's own, so that importing the same file twice creates nothing the second time.

The file arrives first, through the media upload staged with usage: IMPORT; this operation names the object. The work is a job, and result_url points at the import, where the report is read once the job has finished. The object is deleted when the job ends, success or failure: a file somebody imported is not a file they attached.

Needs STRUCTURE on the hub, because an import creates collections there.

Headers

NameTypeRequiredDescription
Idempotency-Keystring (uuid) optionalA UUID; identical requests return the same result for 24 h.

Request body application/json — ImportRequest

NameTypeRequiredDescription
media_idstring (uuid) requiredThe uploaded file, staged with usage: IMPORT and confirmed.
kindImportKind
  • CSV
  • TRELLO
  • GOOGLE_TASKS
  • MICROSOFT_TODO
requiredThe system the file came from.
hub_idstring (uuid) requiredThe hub the imported collections land under.
mappingobject optionalFor CSV only: which column carries which field, by header name, where the header does not already say - title, notes, due, completed, labels, bucket, parent.

Responses

  • 202 The import was accepted; result_url is where its report will be JobRef
  • 403 An error per RFC 9457 Problem
  • 404 An error per RFC 9457 Problem
  • 422 An error per RFC 9457 Problem
Example bash 
curl -X POST "$HUBTASK_URL/imports" \  -H "Authorization: Bearer $HUBTASK_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{  "media_id": "018f6e2a-2b7c-7c1e-9b1a-3d5e6f7a8b9c",  "kind": "CSV",  "hub_id": "018f6e2a-2b7c-7c1e-9b1a-3d5e6f7a8b9c",  "mapping": {}}'

GET /imports/{importId}

An import and its report

What the import did: created, skipped, refused, each by entity, in the shape a restore reports, plus the rows the converter refused by number where the source had rows. Visible to whoever may read the hub it landed in.

Path parameters

NameTypeRequiredDescription
importIdstring (uuid) required

Responses

Example bash 
curl -X GET "$HUBTASK_URL/imports/{importId}" \  -H "Authorization: Bearer $HUBTASK_TOKEN"