Attach or replace the file on a resource
/resources/{ref}/fileUploads a file onto an existing resource, replacing any current file. Requires the write scope and a linked user with edit access to the resource.
This runs the same pipeline as an interactive upload: the file extension is validated against the resource type's allowed list, the original filename is stored as resource metadata, previews are regenerated, document text is re-extracted, and any configured AI extraction job is queued.
The maximum file size follows the server's upload limit (typically
reported by the error when exceeded); oversized uploads fail with
413 FILE_TOO_LARGE.
Authorization
apiKey Issued to you when your integration is provisioned. Determines which catalogue resources are visible and which AI tools are available.
In: header
Path Parameters
Resource ref.
Request Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/resources/0/file" \ -F file="string"{ "success": true, "status": "success", "message": "File uploaded", "data": { "ref": 42, "fileName": "my-book.epub", "fileSize": 5480329, "extension": "epub", "checksum": "3f7a9c", "previewsGenerated": true, "textExtracted": true, "aiJobCreated": false }}{ "success": false, "status": "fail", "message": "string", "error": { "message": "API key is required", "code": "NO_API_KEY" }}{ "success": false, "status": "fail", "message": "API key is required", "error": { "code": "NO_API_KEY", "message": "API key is required" }}{ "success": false, "status": "fail", "message": "string", "error": { "message": "API key is required", "code": "NO_API_KEY" }}{ "success": false, "status": "fail", "message": "string", "error": { "message": "API key is required", "code": "NO_API_KEY" }}{ "success": false, "status": "fail", "message": "string", "error": { "message": "API key is required", "code": "NO_API_KEY" }}List downloadable files for a resource GET
Returns the original file (when present and downloadable at the linked user's access level — `null` otherwise) and all alternative files attached to the resource (e.g. `formatted_extract` entries produced by the formatted-document-extract feature, audio samples, supplementary files). Each entry carries a `downloadUrl` you can fetch directly with the same api-key. Requires the **read** scope.
Inspect the api-key and its scope GET
Returns the identity of the api-key holder and, when the key has catalogue access, the access scope (group + permissions). Use this as the first call from any new integration to verify the key is active (`cmsAccess: true`) and that `imageProviderDefault` matches what you expect.