Data Access

Files & Assets

Upload, download, and manage files through the API.

Note

The SDK does not include file upload or download methods — its HTTP client only supports JSON. Use fetch directly for file transfers.

Upload a File

Send a POST request with multipart/form-data to the assets endpoint. The response returns the file IDs only.

// Upload with fetch — the SDK has no upload method
const form = new FormData();
form.append('file', fileInput.files[0]);

const uploadResponse = await fetch('https://example.monospace.io/api/blog/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: form,
});

const { data } = await uploadResponse.json();
const fileId = data[0].id;

// Then query metadata via SDK
const fileMeta = await client.MonospaceFile.readOne({
  key: fileId,
  fields: ['id', 'fileName', 'fileSize', 'mediaType', 'title', 'description'],
});

curl -X POST https://example.monospace.io/api/blog/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"

const form = new FormData();
form.append('file', fileInput.files[0]);

const response = await fetch('https://example.monospace.io/api/blog/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: form,
});

const { data } = await response.json();
// data: [{ "id": "a1b2c3d4-..." }]

Known Limitation

The upload response only returns file IDs. To get full metadata like fileName, fileSize, and mediaType, query the MonospaceFile collection in a separate request.

File Size Limit

Uploads are subject to a server-configured maximum file size (MONOSPACE_MAX_FILE_PAYLOAD_SIZE). Requests exceeding this limit receive 413 Payload Too Large.

Upload Multiple Files

Include multiple file fields in a single request. Each field with a filename is treated as a separate file upload.

curl -X POST https://example.monospace.io/api/blog/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file1=@photo.jpg" \
  -F "file2=@document.pdf" \
  -F "file3=@report.csv"

const form = new FormData();
form.append('photo', photoFile);
form.append('document', documentFile);
form.append('report', reportFile);

const response = await fetch('https://example.monospace.io/api/blog/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: form,
});

const { data } = await response.json();
// data: [{ "id": "..." }, { "id": "..." }, { "id": "..." }]

If MONOSPACE_REDIRECT_ASSET_READ is enabled and the storage connector supports presigned URLs, the server returns a 307 Temporary Redirect. Presigned URLs expire after one hour by default; configure the duration with MONOSPACE_ASSET_PRESIGNED_URL_TTL. Otherwise, the file is streamed directly.

Force a File Download

Files on the inline allow-list are served with Content-Disposition: inline. Add ?download=true to force the browser to download one as an attachment instead. Files outside the allow-list are always attachments, and ?download=true has no additional effect on them.

curl "https://example.monospace.io/api/blog/assets/a1b2c3d4-5678-90ab-cdef-1234567890ab?download=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o photo.jpg

const response = await fetch(
  'https://example.monospace.io/api/blog/assets/a1b2c3d4-5678-90ab-cdef-1234567890ab?download=true',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const blob = await response.blob();

Content Type Handling

Monospace preserves the stored content type for the formats listed below. Other formats use application/octet-stream and download as attachments, preventing uploaded HTML from running as a page at your asset URL.

Content type	Served as	`Content-Disposition`
`audio/`, `video/`, `text/plain`	Stored type	`inline`, or `attachment` with `?download=true`
`image/avif`, `image/bmp`, `image/gif`, `image/jpeg`, `image/png`, `image/vnd.microsoft.icon`, `image/webp`, `image/x-icon`	Stored type	`inline`, or `attachment` with `?download=true`
`image/svg+xml`	`image/svg+xml`	Always `attachment`
Everything else	`application/octet-stream`	Always `attachment`

An SVG still renders in an <img> tag because the browser fetches it as a subresource. Navigating directly to an SVG asset URL downloads it.

Warning

You cannot configure content types outside the allow-list to display inline. TIFF, HEIC, APNG, PDF, CSV, JSON, CSS, and fonts all download as attachments.

Read File Metadata

File metadata lives in the MonospaceFile collection. System files and workspace files are read differently.

Workspace Files

Read a workspace file's metadata through the file field that references it, with include. See Associate a File with an Item.

Note

MonospaceFile is a system collection. Requests to /api/{workspace}/items/MonospaceFile return 422.

System Files

System files (org logos, workspace logos, user avatars) have a dedicated endpoint at /api/system/files. These require authentication and only expose the base metadata fields.

curl https://example.monospace.io/api/system/files/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/system/files/a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();
// data.id, data.fileName, data.fileSize, data.mediaType

List Files

List system files at /api/system/files:

curl "https://example.monospace.io/api/system/files?fields=id,fileName,fileSize,mediaType" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://example.monospace.io/api/system/files?fields=id,fileName,fileSize,mediaType',
  {
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);

const { data } = await response.json();

Delete a File

Delete a file and its metadata. Returns 204 No Content on success. This removes both the database record and the file from storage.

curl -X DELETE https://example.monospace.io/api/blog/assets/a1b2c3d4-5678-90ab-cdef-1234567890ab \
  -H "Authorization: Bearer YOUR_API_KEY"

await fetch(
  'https://example.monospace.io/api/blog/assets/a1b2c3d4-5678-90ab-cdef-1234567890ab',
  {
    method: 'DELETE',
    headers: {
      Authorization: 'Bearer YOUR_API_KEY',
    },
  },
);
// 204 No Content

File Metadata Fields

Workspace MonospaceFile

Field	Type	Nullable	Description
`id`	uuid	No	Primary key
`fileName`	string	No	Original file name
`fileSize`	bigint	No	Size in bytes
`mediaType`	string	No	MIME type (auto-detected from extension if not provided)
`title`	string	Yes	User-editable title
`description`	string	Yes	User-editable description
`tags`	json	Yes	User-editable tags

System MonospaceFile

Field	Type	Nullable	Description
`id`	uuid	No	Primary key
`fileName`	string	No	Original file name
`fileSize`	bigint	No	Size in bytes
`mediaType`	string	No	MIME type

Associate a File with an Item

Store the file's UUID in a relation field on your collection. Upload the file first, then reference its ID when creating or updating an item.

// 1. Upload with fetch
const form = new FormData();
form.append('file', fileInput.files[0]);

const uploadResponse = await fetch('https://example.monospace.io/api/blog/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: form,
});

const { data: uploaded } = await uploadResponse.json();
const fileId = uploaded[0].id;

// 2. Create the article via SDK, connecting the file
const article = await client.Articles.createOne({
  data: {
    title: 'My Article',
    cover_image: {
      _connect: { key: { id: fileId } },
    },
  },
  fields: ['id', 'title'],
  include: {
    cover_image: { fields: ['id', 'fileName'] },
  },
});

# 1. Upload the file
curl -X POST https://example.monospace.io/api/blog/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@photo.jpg"
# Response: { "data": [{ "id": "a1b2c3d4-..." }] }

# 2. Create an article connecting the uploaded file
curl -X POST https://example.monospace.io/api/blog/items/Articles \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[{
    "title": "My Article",
    "cover_image": {
      "_connect": { "key": { "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab" } }
    }
  }]'

// 1. Upload the file
const form = new FormData();
form.append('file', fileInput.files[0]);

const uploadResponse = await fetch('https://example.monospace.io/api/blog/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
  body: form,
});

const { data: uploaded } = await uploadResponse.json();
const fileId = uploaded[0].id;

// 2. Create an article connecting the uploaded file
const articleResponse = await fetch('https://example.monospace.io/api/blog/items/Articles', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify([{
    title: 'My Article',
    cover_image: {
      _connect: { key: { id: fileId } },
    },
  }]),
});

const { data: article } = await articleResponse.json();

Tip

File fields are to-one relations to the MonospaceFile collection. Use _connect to link an uploaded file — see Relational Data for all relational operations.

Endpoint Summary

Operation	Endpoint	Method	Response
Upload (workspace)	`/api/{workspace}/assets`	`POST`	`{ data: [{ id }] }`
Upload (system)	`/api/system/assets`	`POST`	`{ data: [{ id }] }`
Download	`/api/{workspace}/assets/{file_id}`	`GET`	File stream
Download (named)	`/api/{workspace}/assets/{file_id}/{file_name}`	`GET`	File stream
Delete (workspace)	`/api/{workspace}/assets/{file_id}`	`DELETE`	204
Delete (system)	`/api/system/assets/{file_id}`	`DELETE`	204
File metadata (system)	`/api/system/files/{file_id}`	`GET`	`{ data: {...} }`
List files (system)	`/api/system/files`	`GET`	`{ data: [...] }`