Create a file

POST /projects/:projectid/library/files

Register a file and get a URL to upload its contents to.

Uploading is two steps. This one registers the file and returns a short-lived storageLink; PUT the bytes to that URL, then call Complete upload so the file is processed and indexed.

Authentication

• Project API key: The credential for everything external. Created in Project Settings, bound to one project, and limited to the scopes it was granted. Format: proj.<keyId>.<secret>.
• Execution token: Minted automatically for a running workflow and valid only for that workflow's project. Code nodes receive it as INTELLECTIBLE_EXECUTION_TOKEN — you never create one yourself. Format: exec_<jwt>.
• Required permission: library.write.

Path parameters

Name	Type	Required	Default	Description
projectid	string	Yes	-	The project id.

Request body

Content type: application/json

Name	Type	Required	Default	Description
originalname	string	Yes	-	The file name, including its extension.
fileType	string	Yes	-	The file extension, used to derive the MIME type, e.g. pdf.
dir	string	Yes	-	The id of the directory to create it in. Use root for the top level, or an id from List directories.

Example

{
  "originalname": "invoice-104.pdf",
  "fileType": "pdf",
  "dir": "root"
}

Example request

curl -X POST \
  -H "Authorization: proj.KEY_ID.SECRET" \
  -H "Content-Type: application/json" \
  -d '{"originalname":"invoice-104.pdf","fileType":"pdf","dir":"root"}' \
  {{BASE_URL}}/projects/{{PROJECT_ID}}/library/files

Responses

200

The file was registered. Upload the bytes to storageLink.

{
  "documentId": "doc_7Yq1",
  "storageLink": "https://storage.googleapis.com/...&X-Goog-Signature=...",
  "mimeType": "application/pdf",
  "path": "libraryDocuments/{{PROJECT_ID}}/doc_7Yq1.pdf",
  "createdDate": "2026-08-26T09:14:22.104Z"
}

400

originalname, fileType or dir was missing.

Notes

• storageLink is a signed URL that expires — use it promptly and do not store it.