Files

Returns files in one repository. repo_type selects which — media for the shared media library, or the kind of object that owns them (ds, thread, design, prompt) together with a repo_id naming it. A repository is required: files are always scoped to one rather than listed across the workspace.

Each repository also has its own collection, which is the more direct way to ask — GET /knowledge-bases/{id}/files, GET /threads/{id}/files, GET /designs/{id}/files — and GET /media-files lists the media library with album membership and similarity search.

Requires any one of media:view, document:view, knowledge-base:view, thread:view, design:view, prompt:view or presentation:view.

Creates a markdown document to write into. For uploading bytes, start with upload URLs instead.

Requires any one of media:upload, document:upload, knowledge-base:upload, thread:upload, design:edit, prompt:edit or presentation:edit.

Returns one file's record — what it is, where it sits and what is known about it. The bytes are reached through a download URL.

Requires any one of media:view, document:view, knowledge-base:view, thread:view, design:view, prompt:view or presentation:view.

Replaces the file's record. This is a PUT: it is the metadata that is being written, never the bytes. Which repository the file belongs to is not editable here — moving it is its own operation, because where a file sits decides who can reach it.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Recoverable from the trash while its storage objects are still within the retention window.

Requires any one of media:delete, document:delete, knowledge-base:delete, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Copies a file into the media library, where albums, faces and tags apply to it. The original stays where it was.

Requires any one of media:download, document:download, knowledge-base:view, thread:view, design:view, prompt:view, presentation:view or media:upload.

Flips the caller's own favorite flag on the file. Favorites are per user, not per workspace.

Requires any one of media:view, document:view, knowledge-base:view, thread:view, design:view, prompt:view or presentation:view.

Completed analysis runs, tag edits, renames and deletions, newest first, reduced to the facts that changed — the full analysis records behind them are not returned here.

Replaces the file's tags with what you send.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Files the file under a different repository. Everything the move touches is checked: write access to the file, write access to where it is going, and write access to what it is leaving — taking a document out of a knowledge base changes that knowledge base.

Retrieval follows the move: chunks indexed for the old repository answer for the new one from then on. A file that was never indexed does not become searchable by moving it into a knowledge base — reindex it explicitly.

Only repositories a caller may name are accepted — library, ds, thread, design and prompt. The rest are stamped by the platform to record how a file came to exist, and are returned but never sent.

Requires any one of media:edit, document:edit, knowledge-base:write, thread:edit, design:edit, prompt:edit, presentation:edit or task:form:edit.

Everything holding on to this file — the albums containing it, designs using it in a layer or as a background, social posts that published it, share links exposing it, and the business objects it is attached to. This is what to check before deleting one.

Sections the caller may not see come back empty rather than being refused.

Compares stored embeddings. Returns an empty list when the file has no embedding yet — analysis still pending, or a generated image, which never gets one.

Rebuilds the search and retrieval index for a repository. It answers when the reindex is done, and refuses a repository holding more than 99 files rather than running long — the count of what was processed, skipped and what failed comes back in the response.

Adds to what is already there, rather than replacing it.

Moves files to another status in the flow that governs them. A move the flow does not allow is refused rather than forced.

Name matching for pickers and mentions, limited to files whose text has been extracted — a file with no rendition would add nothing to the message that mentions it. Two sources answer, each behind its own grant and labelled by source: the documents a knowledge base indexes, and the document library. An empty query answers with the most recently added.

Requires any one of media:view, document:view, knowledge-base:view, thread:view, design:view, prompt:view or presentation:view.

Each entry says whether it is still recoverable — the underlying storage objects are kept for a retention window, and once that passes the file is gone for good.

Restores the file and its thumbnails. Answers 409 if the storage objects are past their retention window — at that point there is nothing left to restore.

Returns files with the albums each belongs to. An embedding in the request adds a similarity score and orders by it; a face embedding does the same through face_similarity. GET /files is the plainer listing — this one is the library's own, and it is the only place the similarity searches are offered.

repo_type is required, as it is on GET /files: media for the uploaded library, generated for what the platform produced on its own. An image generated inside a conversation belongs to that conversation instead — list those with repo_type=thread.

fileType cuts the list by kind — Image, Video, Audio or Document — and file_format by the file name's extension, mov or mp4, with or without the leading dot. Both repeat to widen the selection rather than narrow it, and GET /media-files/formats answers which values are worth sending for a given repository. file_added_by keeps only files the named users uploaded, by user id, and repeats the same way.

analyzed=false keeps the files AI analysis never produced output for — deferred while credits were exhausted, failed, or uploaded before analysis existed — the set worth re-running; analyzed=true is its complement.

Requires either media:view or infographic:view.

The kinds and formats of file actually present in the repository the request names, each with how many files carry it. This is the option list behind the media library's type filter — it is what lets that filter offer mov and mp4 as separate choices without offering formats the account holds none of.

A row is a filter: kind is what fileType takes on GET /media-files and format is what file_format takes, so a caller sends one straight back. The counts describe the repository, the album and the favorite flag and nothing else — the gallery's remaining filters and both similarity searches leave them alone, so a count says what is in here rather than what the current query matches. A file whose name carries no extension has no format and is counted under its kind alone.

Counting is exact, which means reading every file the caller can see. A library too large to do that inside the server's budget answers with all four kinds, a null count on each and no formats — the filter still works, it just stops saying how many. Treat a null count as "not counted" rather than zero.

Requires either media:view or infographic:view.