Skip to content
Hubtask

API reference · Hubtask API 0.1.0

media

POST /media

Request media upload

Stages an upload: declares what is coming - its purpose, size and claimed type - and receives where to put the bytes. The answer's upload object carries a URL the client PUTs the bytes to directly (presigned object storage, or this server's token-protected content route on a local-storage installation) and the moment it expires. The object stays PENDING until confirmed; abandoned stagings are cleaned up by the reconciliation job.

Headers

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

Request body application/json — MediaUploadRequest

NameTypeRequiredDescription
file_namestring, or null
  • maxLength: 255
optional
content_typestring, or null optionalThe claim.
sizeinteger (int64)
  • minimum: 1
requiredThe exact size in bytes.
usagestring
  • COVER
  • ATTACHMENT
  • IMPORT
requiredWhat the object is for.

Responses

  • 201 The staged object, upload target included MediaObject
  • 4XX An error per RFC 9457 Problem
Example bash 
curl -X POST "$HUBTASK_URL/media" \  -H "Authorization: Bearer $HUBTASK_TOKEN" \  -H "Idempotency-Key: $(uuidgen)" \  -H "Content-Type: application/json" \  -d '{  "file_name": "string",  "content_type": "string",  "size": 1,  "usage": "COVER"}'

GET /media/{mediaId}

Get media

The media object's record, with a download target when it is READY. Readable by its uploader, and by anybody who can read an entry it is attached to or covers.

Path parameters

NameTypeRequiredDescription
mediaIdstring (uuid) required

Responses

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

DELETE /media/{mediaId}

Delete media

Removes an unreferenced media object: the record now, the bytes through the reconciliation job. Refused while anything references it - detach it or clear the cover first. Only the uploader or an administrator may.

Path parameters

NameTypeRequiredDescription
mediaIdstring (uuid) required

Responses

  • 204 Removed
  • 4XX An error per RFC 9457 Problem
Example bash 
curl -X DELETE "$HUBTASK_URL/media/{mediaId}" \  -H "Authorization: Bearer $HUBTASK_TOKEN"

POST /media/{mediaId}:confirm

Confirm media upload

Seals the upload: the server reads the object's head back from storage, sniffs it, checks the size against what was declared and against the installation's limit, and marks the object READY with the judged content type - never the claim. A refusal removes the staged bytes. Idempotent: confirming a READY object succeeds and changes nothing, which is what makes an upload confirmed twice one media object.

Path parameters

NameTypeRequiredDescription
mediaIdstring (uuid) required

Headers

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

Responses

Example bash 
curl -X POST "$HUBTASK_URL/media/{mediaId}:confirm" \  -H "Authorization: Bearer $HUBTASK_TOKEN" \  -H "Idempotency-Key: $(uuidgen)"

PUT /media/{mediaId}:content

Upload media content

The upload target of a local-storage installation: the bytes, streamed, judged by the upload guard as they pass. On an object-storage installation the upload goes to the presigned URL instead and this route answers that the token is not one it minted.

Path parameters

NameTypeRequiredDescription
mediaIdstring (uuid) required

Query parameters

NameTypeRequiredDescription
tokenstring requiredThe capability: a signed, expiring token minted by requestMediaUpload or getMedia.

Request body application/octet-stream

Responses

  • 204 Stored, awaiting confirmation
  • 4XX An error per RFC 9457 Problem
Example bash 
curl -X PUT "$HUBTASK_URL/media/{mediaId}:content"

GET /media/{mediaId}:content

Download media content

The download target of a local-storage installation: the bytes, streamed, as a download - Content-Disposition: attachment and a sandboxing content security policy, never a rendering path for what somebody uploaded.

Path parameters

NameTypeRequiredDescription
mediaIdstring (uuid) required

Query parameters

NameTypeRequiredDescription
tokenstring requiredThe capability: a signed, expiring token minted by requestMediaUpload or getMedia.

Responses

  • 200 The bytes
  • 4XX An error per RFC 9457 Problem
Example bash 
curl -X GET "$HUBTASK_URL/media/{mediaId}:content"