Create a file
POST /projects/:projectid/library/files
Registers a new file and returns a temporary upload URL. This request sends metadata only, not the file bytes. Continue with the storage upload and Complete upload.
Authentication and request
Use a project key with library.write in Authorization, without Bearer. Replace :projectid with the key's project ID and send Content-Type: application/json.
| Field | Type | Required | Meaning |
|---|---|---|---|
originalname | String | Yes | Filename, including its extension, such as notes.txt. |
fileType | String | Yes | File extension without a dot, such as txt or pdf—not a MIME type. Keep it consistent with the filename and content. |
dir | String | Yes | Existing directory ID, or root. This is not a directory path. |
size | Number | No | Expected file size in bytes. Defaults to 0; provide the real size so capacity can be checked before upload. |
Use List directories to discover a destination ID. A path such as Reports/Monthly is not valid as an upload destination; creation does not resolve paths or create folders.
Using the Quickstart variables, this example registers a 128-byte text file:
curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"originalname":"notes.txt","fileType":"txt","dir":"root","size":128}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/files"
Replace the example size with your file's actual byte count.
Response
200 OK returns:
{
"documentId": "example-file-id",
"storageLink": "https://storage.example/temporary-signed-upload-url",
"mimeType": "text/plain",
"path": "libraryDocuments/example-project-id/example-file-id.txt",
"createdDate": "2026-10-30T10:00:00.000Z"
}
The URL and identifiers above are illustrative. Use the actual returned values:
documentIdis the file ID; retain it for subsequent operations.storageLinkis the signed URL to which you PUT the bytes.mimeTypemust be sent as the storage upload'sContent-Type.pathmust be passed unchanged to completion.createdDaterecords when the file was registered.
Signed upload URLs currently expire after ten minutes. Treat them as secrets and use them promptly. Do not send your project API key to the signed URL.
Continue the upload
PUT the raw file bytes to storageLink, then call completion only after that PUT succeeds. Do not use multipart form data or base64-encoded content. See Upload a file for the full sequence.
Creation allocates a new file ID every time. Reusing a filename does not overwrite an existing file, and retrying creation can leave duplicate or pending records.
Errors
- 400: a required field is missing.
- 401: missing or invalid project credential.
- 403: missing
library.write. - 429: request-rate limit reached.
- 500: registration or upload-link creation failed. Capacity-related failures can also reach this response.
Do not assume all invalid destinations or file types are rejected up front. Supply a known directory ID and a conventional extension matching the file. Check the returned upload URL before proceeding.