docs
CTRL K
GitHubDiscord
DevelopersAPI ReferenceLearnIntegrationsWebsiteGitHubDiscord
Skip to Content

Media

Upload and manage media assets.

Serve a media file

GET/api/v1/media/{media_uuid}/file
API tokenmedia:reador user session

Streams the media file's bytes after enforcing access (folder-aware). The storage path is never exposed to the client. Supports Range requests. Pass `download=true` to force a save-as instead of inline rendering.

Path parameters

media_uuidstringrequired

Query parameters

downloadboolean
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Create a media share link

POST/api/v1/media/{media_uuid}/share-link
API tokenmedia:createor user session

Mints a fresh random, revocable token each call. The link is NOT an access bypass — recipients still need access.

Path parameters

media_uuidstringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Serve a shared media file by token

GET/api/v1/media/shared/{token}/file
API tokenmedia:reador user session

Path parameters

tokenstringrequired

Query parameters

downloadboolean
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Create media

POST/api/v1/media/
API tokenmedia:createor user session

Create a media asset. For UPLOAD, send a multipart file. For EMBED, send a url.

Request bodymultipart/form-datarequired

org_idintegerrequired
namestringrequired
media_typeMediaTypeEnum

Kind of media asset. Extensible — add new embeddable kinds here.

UPLOADEMBED
descriptionstring | null
urlstring | null
publicboolean
folder_uuidstring | null
filefile | null

Returns

MediaRead — Successful Response

namestringrequired
descriptionstring | null
media_typeMediaTypeEnum

Kind of media asset. Extensible — add new embeddable kinds here.

UPLOADEMBED
urlstring | null
thumbnail_imagestring | null
publicboolean
idintegerrequired
org_idintegerrequired
media_uuidstringrequired
file_formatstring | null
file_sizeinteger | null
file_mimestring | null
creation_datestringrequired
update_datestringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "media_type": "UPLOAD",
  "url": "https://example.com",
  "thumbnail_image": "string",
  "public": true,
  "id": 1,
  "org_id": 1,
  "media_uuid": "string",
  "file_format": "string",
  "file_size": 0,
  "file_mime": "string",
  "creation_date": "string",
  "update_date": "string"
}

Get media

GET/api/v1/media/{media_uuid}
API tokenmedia:reador user session

Get a single media asset by its UUID.

Path parameters

media_uuidstringrequired

Returns

MediaRead — Successful Response

namestringrequired
descriptionstring | null
media_typeMediaTypeEnum

Kind of media asset. Extensible — add new embeddable kinds here.

UPLOADEMBED
urlstring | null
thumbnail_imagestring | null
publicboolean
idintegerrequired
org_idintegerrequired
media_uuidstringrequired
file_formatstring | null
file_sizeinteger | null
file_mimestring | null
creation_datestringrequired
update_datestringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "media_type": "UPLOAD",
  "url": "https://example.com",
  "thumbnail_image": "string",
  "public": true,
  "id": 1,
  "org_id": 1,
  "media_uuid": "string",
  "file_format": "string",
  "file_size": 0,
  "file_mime": "string",
  "creation_date": "string",
  "update_date": "string"
}

Update media

PUT/api/v1/media/{media_uuid}
API tokenmedia:updateor user session

Update a media asset's metadata.

Path parameters

media_uuidstringrequired

Request bodyapplication/jsonrequired

namestring | null
descriptionstring | null
urlstring | null
thumbnail_imagestring | null
publicboolean | null

Returns

MediaRead — Successful Response

namestringrequired
descriptionstring | null
media_typeMediaTypeEnum

Kind of media asset. Extensible — add new embeddable kinds here.

UPLOADEMBED
urlstring | null
thumbnail_imagestring | null
publicboolean
idintegerrequired
org_idintegerrequired
media_uuidstringrequired
file_formatstring | null
file_sizeinteger | null
file_mimestring | null
creation_datestringrequired
update_datestringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "name": "Example name",
  "description": "An example description",
  "media_type": "UPLOAD",
  "url": "https://example.com",
  "thumbnail_image": "string",
  "public": true,
  "id": 1,
  "org_id": 1,
  "media_uuid": "string",
  "file_format": "string",
  "file_size": 0,
  "file_mime": "string",
  "creation_date": "string",
  "update_date": "string"
}

Delete media

DELETE/api/v1/media/{media_uuid}
API tokenmedia:deleteor user session

Delete a media asset and remove it from any folders.

Path parameters

media_uuidstringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

List media for org

GET/api/v1/media/org/{org_id}/page/{page}/limit/{limit}
API tokenmedia:reador user session

List media assets for an organization, paginated.

Path parameters

pageintegerrequired
limitintegerrequired
org_idstringrequired

Returns

MediaRead[] — Successful Response

namestringrequired
descriptionstring | null
media_typeMediaTypeEnum

Kind of media asset. Extensible — add new embeddable kinds here.

UPLOADEMBED
urlstring | null
thumbnail_imagestring | null
publicboolean
idintegerrequired
org_idintegerrequired
media_uuidstringrequired
file_formatstring | null
file_sizeinteger | null
file_mimestring | null
creation_datestringrequired
update_datestringrequired
Error responses
  • 422 Validation Error — HTTPValidationError
Request
Response
[
  {
    "name": "Example name",
    "description": "An example description",
    "media_type": "UPLOAD",
    "url": "https://example.com",
    "thumbnail_image": "string",
    "public": true,
    "id": 1,
    "org_id": 1,
    "media_uuid": "string",
    "file_format": "string",
    "file_size": 0,
    "file_mime": "string",
    "creation_date": "string",
    "update_date": "string"
  }
]