Skip to main content
persona.files — /api/v1/developer/files. Files are uploaded on behalf of the asserted external user, optionally associated with an Agent/Thread. Every call here requires the client to have been constructed with externalUserId set — a File’s Subject is a person, same requirement and rejection behavior as Threads (400 EXTERNAL_USER_REQUIRED otherwise).

Methods

upload(input, idempotencyKey?)

filename and content are required; contentType, agentId, threadId are optional context.
  • UploadFilePayload: { filename, content: Uint8Array | Blob, contentType?, agentId?, threadId? }.
  • Returns a PersonaFile in the clean formatted shape (id, not _id — unlike Thread/Skill/Agent/Knowledge): { id, originalName, mimeType, size, agentId: string | null, threadId: string | null, createdAt }.
  • The optional trailing idempotencyKey is sent as the Idempotency-Key header.

list(params?)

Lists the asserted external user’s own uploaded files. Returns PaginatedResult<PersonaFile>.

download(fileId)

Downloads a file’s raw bytes. This is the one method on the whole client that doesn’t return parsed JSON — it returns the raw Response (a mediated file stream), so you can:
Call .arrayBuffer()/.blob() or pipe response.body onward as your framework needs. Throws PersonaApiError (404) for a file id the asserted user doesn’t own.

delete / bulkDelete

Complete example