plnnrlydevelopers

Deze referentie is alleen in het Engels. Naar het Nederlandse REST API-overzicht

Diese Referenz gibt es nur auf Englisch. Zur deutschen REST-API-Übersicht

Cette référence existe uniquement en anglais. Aller à la présentation de l'API REST en français

Esta referencia solo está en inglés. Ir a la introducción de la API REST en español

Media

Media

A file attached to a record: the metadata of one upload (its name, type, size and the collection it belongs to) plus an on-demand signed download URL.

View as Markdown
Summary view
MediaList, 10 fields. What a list returns by default.
Detail view
Media, 10 fields. The default for a single read and for every write.
Write with
api:write:project_driveorapi:write:customer_driveorapi:write:organization_driveorapi:write:user_driveandproject_drive::create

Files are reached only inside their parent's collection, work-items/{work_item}/attachments or drive-items/{drive_item}/files. The API never streams bytes: uploading is a two-step flow, where you create an upload ticket on the parent, PUT the raw bytes to the ticket's own signed URL outside this API, then POST the ticket's id as upload_id to the collection. That way /api/v2 still accepts exactly one request content type, application/json.

Used by

GETList a drive item's files/drive-items/{drive_item}/filesMediaList
POSTAttach an uploaded file to a drive item/drive-items/{drive_item}/filesMedia
GETList a work item's attachments/work-items/{work_item}/attachmentsMediaList
POSTAttach an uploaded file to a work item/work-items/{work_item}/attachmentsMedia

Fields

Detail only
Only in the detail view.
Only with include
Only when you ask for it with include.
Server-assigned
Set by plnnrly, never by a request.
idinteger

Unique identifier.

namestring≤ 255

File name as uploaded.

mime_typestring or null≤ 255

IANA media type.

sizeinteger

Size in bytes.

diskstring≤ 255

Name of the storage location the file is kept in.

collectionstring≤ 255

Media collection the file belongs to.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Upload timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

urlstring or nullOn request

Signed download URL, requiring your bearer token. Request with ?include=url. Null only where your organisation's file storage cannot sign URLs, in which case the response carries a signed_url_unavailable warning and downloads are not available through the API.

url_expires_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullOn request

When url stops working. Always null in v2.0: the signed route the URL points at does not expire. Declared so a future bounded-TTL download path is an additive change.

Variants

MediaList 10 fields

What a collection returns, and what ?view=summary returns on a single record.

The same fields as the detail object.

MediaSummary 3 fields

The embedded form: what you get when another resource carries this one and you did not include it.

Leaves out: size, disk, collection, created_at, updated_at, url, url_expires_at

Columns deliberately not published

conversions_diskUsed only by plnnrly's file storage.
custom_propertiesUsed only by plnnrly's file storage.
file_nameStorage file name; use name.
generated_conversionsUsed only by plnnrly's file storage.
manipulationsUsed only by plnnrly's file storage.
model_idThe other half of that parent reference, withheld with it.
model_typeA file is only ever reached inside its parent's collection, so the parent is the path rather than a payload field.
order_columnThe file's position as arranged in plnnrly, which the API does not use.
responsive_imagesUsed only by plnnrly's file storage.
uuidA second identifier used only by plnnrly's file storage; id is the one to use.