File Upload

Use Case

Use this endpoint to create a presigned upload URL. Upload the bytes to that URL, then use the returned internal object key when creating or updating page content.

Upload URL Endpoint

Permissions

Requires pages.write. The API also verifies write access to parent.page_id.

Parameters

Request Example

{
  "parent": {
    "page_id": "11111111-1111-4111-8111-111111111111"
  },
  "filename": "launch-plan.pdf",
  "content_type": "application/pdf",
  "content_length": 524288
}

Response Example

{
  "object": "file_upload",
  "id": "upload_15151515-1515-4515-8515-151515151515",
  "upload_url": "https://upload.example.com/presigned-url",
  "oss_name": "s3/15151515-1515-4515-8515-151515151515/launch-plan.pdf",
  "file_url": "https://cdn2.buildin.ai/s3/15151515-1515-4515-8515-151515151515/launch-plan.pdf",
  "size": 524288,
  "expiry_time": "2026-04-09T10:30:00.000Z",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf"
  }
}

Behavior

• The request body must include parent.page_id.
• The presigned URL is time limited.
• Upload file bytes directly to upload_url using the returned method and headers.
• After a successful upload, use the returned oss_name and size in an internal file, image, audio, or video block write. Do not use file_url as an external file URL; it is a compatibility field.
• This endpoint does not upload file bytes through the Buildin JSON API.

Errors

• 400 validation_error: missing parent, filename, content type, or content length; unsupported MIME type; or a file over 100 MB or workspace capacity.
• 401 unauthorized: invalid or expired token.
• 403 forbidden: missing pages.write or no access to parent page.
• 404 not_found: parent page does not exist.

Download URL Endpoint

Use this endpoint to create a temporary authenticated URL for a file already referenced by a block the token can read.

{
  "object": "file",
  "name": "launch-plan.pdf",
  "type": "file",
  "file": {
    "url": "https://cdn2.buildin.ai/s3/15151515-1515-4515-8515-151515151515/launch-plan.pdf?token=...",
    "expiry_time": "2026-04-09T10:30:00.000Z",
    "oss_name": "s3/15151515-1515-4515-8515-151515151515/launch-plan.pdf"
  },
  "ttl": 1800
}

• The API verifies both blocks.read and that oss_name is referenced by block_id; it cannot mint URLs for arbitrary object keys.
• compressed_file is included only when a same-workspace compressed variant exists.
• ttl is the URL lifetime in seconds. Fetch the URL again after it expires.

Related Docs

Prerequisites

• Create Page
• Append Block Children

Next Steps

• Markdown Read

References

• Error Codes