Skip to main content

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.

FieldTypeRequiredMeaning
originalnameStringYesFilename, including its extension, such as notes.txt.
fileTypeStringYesFile extension without a dot, such as txt or pdf—not a MIME type. Keep it consistent with the filename and content.
dirStringYesExisting directory ID, or root. This is not a directory path.
sizeNumberNoExpected 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:

  • documentId is the file ID; retain it for subsequent operations.
  • storageLink is the signed URL to which you PUT the bytes.
  • mimeType must be sent as the storage upload's Content-Type.
  • path must be passed unchanged to completion.
  • createdDate records 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.