File Upload

Use Case

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

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",
  "size": 524288
}

Response Example

{
  "upload_url": "https://upload.example.com/presigned-url",
  "method": "PUT",
  "headers": {
    "Content-Type": "application/pdf"
  },
  "file": {
    "type": "file",
    "file": {
      "url": "https://buildin.ai/files/launch-plan.pdf",
      "expiry_time": "2026-04-09T10:30:00.000Z"
    },
    "name": "launch-plan.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 upload, pass the returned file object to file or image block writes where supported.
• This endpoint does not upload file bytes through the Buildin JSON API.

Errors

• 400 validation_error: missing parent, filename, or content type.
• 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.

Related Docs

Prerequisites

• Create Page
• Append Block Children

Next Steps

• Markdown Read and Write

References

• Error Codes