ntn files when you want to create a Notion File Upload from your terminal. The command handles the upload lifecycle for local files: it creates the File Upload object, sends the file bytes, completes the upload, and prints the resulting upload ID.
After the upload has a status of uploaded, use its ID in a file_upload file object to attach it to a page, block, page icon, page cover, or files property.
Upload a local file
Redirect the file intontn files create:
--plain to return tab-separated fields with the upload ID first:
--json when you want the full File Upload object:
ntn files create reads bytes from stdin. If you run it without redirecting a file, the command exits with a hint to pass a file with shell redirection.
Set the filename or content type
The CLI infers the filename and MIME type when it can. Override either value when stdin does not preserve enough information, or when you are generating file bytes from another command:--filename when the uploaded file should have a specific name in Notion. Use --content-type when the file extension is missing or the inferred MIME type would be ambiguous.
Import a file from a URL
Use--external-url when the file is already hosted at a public HTTPS URL:
uploaded. If the status becomes failed, create a new upload after fixing the URL, file type, or file size issue.
Attach an uploaded file
ntn files create uploads the file, but does not choose where to place it in your workspace. Attach the upload by passing the ID to a Notion API endpoint with ntn api.
The examples below use the inline body field syntax described in API request syntax.
For example, append an image block to a page:
Attachments with the name of your files property.
Attach file uploads within one hour. Uploads that are not attached before
their
expiry_time can expire and cannot be attached later.Find an existing upload
List recent file uploads:--json and --plain for scripting:
ntn files list currently returns only the first page. For cursor-based pagination, call the File Uploads API directly:
Send a multipart request yourself
Most uploads should usentn files create. Use ntn api --file when you need lower-level control over the File Upload API, such as sending one part of an upload that your own script created:
--file sends a multipart form-data request with the file contents in a form field named file. Other inline body fields become additional multipart form fields.
Troubleshooting
Next steps
API request syntax
Build Notion API requests with
ntn api.
File Upload reference
See File Upload statuses, fields, size limits, and endpoints.