assets

Add a file to the workspace

Store a new file at version 1. Send text kinds (markdown, html) as content, everything else base64-encoded as content_base64. The name must be free among the workspace's live files — a deleted file frees its name. Send folder_id to file it as it is created; the whole request is refused when that folder is not this workspace's, so a file is never stored somewhere nobody asked for. The new file is readable by the workspace (team); this route does not itself mint a public link, EXCEPT when folder_id names a folder that is already shared — filing into a shared folder publishes the file at once, and needs the same authority sharing does. Answers 404 for an unknown folder, 409 when the name is taken, 413 when the body is over the size cap, and 422 for an unknown kind or a mismatched content type.

post/v1/assets

Request

  • Base URL: https://api.patricia.app (the document declares no server; this is the origin it was published from)
  • URL: https://api.patricia.app/v1/assets
  • Auth: HTTP bearer

Headers

X-Tenant-Idstring nullable

Request body

contentstring nullable

UTF-8 text for a text kind (markdown, html). Mutually exclusive with content_base64.

content_base64string nullable

Base64-encoded bytes for any kind. Mutually exclusive with content.

namestring required

The file's name. Must be free among the workspace's live assets.

kind'app' | 'audio' | 'docx' | 'file' | 'html' | 'image' | 'markdown' | 'pdf' | 'slides' | 'spreadsheet' | 'video' required

What sort of file this is.

content_typestring nullable

Media type to store. Omit for the kind's default.

folder_idstring uuid nullable

File the new asset into this folder as it is created. Omit (or send null) to leave it unfiled. Answers 404 when the folder does not exist or belongs to another workspace, and stores nothing when it does.

Response

Successful Response

idstring uuid required
namestring required

The workspace's handle for the file. UNTRUSTED text: render escaped.

category'document' | 'media' | 'app' required

Which library this file lives in: 'document' or 'media'.

kind'app' | 'audio' | 'docx' | 'file' | 'html' | 'image' | 'markdown' | 'pdf' | 'slides' | 'spreadsheet' | 'video' required

What sort of file this is.

content_typestring required

The current version's media type, e.g. 'application/pdf'.

byte_sizeinteger required

The current version's size in bytes.

current_versioninteger required

The newest version number (versions count from 1).

updated_atstring date-time required

When the file last changed (UTC).

created_by_run_idstring uuid nullable

The Patricia run that created this file. Null when no run is recorded for it: a person uploaded it, or it was stored before Patricia began recording runs. Later versions can come from other runs, so read each version's own created_by_run_id for those.

favoriteboolean nullable

Whether the workspace marked this file a favourite (the Liked filter shows these). The server always sends it; the default exists for the same temporary fixture-compatibility reason the module docstring records for created_by_run_id.

thumbnail_status'ready' | 'pending' | 'unavailable'

Whether this file has a grid preview. 'ready' means GET /assets/{id}/thumbnail serves it; 'pending' means one is being prepared, ask again shortly; 'unavailable' means the type icon is the answer (no preview exists for this file type, or this file could not be rendered).

created_atstring date-time

When the file was first added to the workspace (UTC).

is_ownerboolean

Whether the caller is the person who owns this file.

requires_access_acknowledgementboolean

Whether opening this file requires an access_acknowledgement UUID and a durable audit receipt.

visibility'private' | 'team' | 'external'

Who can read this file. 'private' — only the person who added it, plus workspace admins. 'team' — everyone in the workspace (the default). 'external' — everyone in the workspace, and it may also be shared outside through a link. A file you can see at all is one you may read; the level tells you who ELSE can.

shared_via_folder_namestring nullable

The name of the folder making this file reachable beyond its own visibility level, when a live folder share link is why — for a private file, why anybody else in the workspace can read it; for any file, why anybody outside the workspace holding that folder's link can too. Null when no folder link is why this file is reachable.

can_editboolean

Whether YOU may change this file: save a new version, restore an older one, rename it, or move it to another folder. Computed server-side by the same may_mutate rule every mutation route enforces, so a control enabled by this flag is never refused by that request. A shared folder can make a private file READABLE without making it EDITABLE, so this answers the write question on its own — never inferred from visibility or from shared_via_folder_name.

can_open_in_canvaboolean

Whether YOU may open this media file as a Canva design. Requires edit access to THIS file, a supported image type, a live Canva connection, and the Canva provider in this deployment. Edit access is the same per-file rule this row reports as can_edit, because sending a file out to a third-party account is an export. Computed server-side by the same rule POST /assets/{id}/canva-design enforces, so a menu item enabled by this flag is never refused by that request.

Changes

No recorded changes to this operation across all 1 revision of this API.