The Document resource allows you to manage files and documents in ITSM-NG. You can upload files, associate them with other items (tickets, assets, etc.), and download them.
Document Object A document object contains these key fields:
Unique document identifier
Relative path to the file
MIME type of the file (e.g., application/pdf, image/png)
User who uploaded the document
SHA1 hash of the file for integrity verification
Whether the file extension is blacklisted
Optional tag for document organization
Get a Document Retrieve document metadata (not the file itself).
curl -X GET \ -H 'Content-Type: application/json' \ -H "Session-Token: your_session_token" \ -H "App-Token: your_app_token" \ 'https://your-instance.com/apirest.php/Document/123'
Response Example { "id" : 123 , "name" : "Network Diagram" , "filename" : "network-diagram.pdf" , "filepath" : "/2024/03/" , "documentcategories_id" : 5 , "mime" : "application/pdf" , "date_creation" : "2024-03-02 10:30:00" , "users_id" : 42 , "sha1sum" : "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" }
Upload a Document Upload a file to ITSM-NG using multipart/form-data.
curl -X POST \ -H 'Content-Type: multipart/form-data' \ -H "Session-Token: your_session_token" \ -H "App-Token: your_app_token" \ -F 'uploadManifest={"input": {"name": "Network Diagram", "_filename": ["network-diagram.pdf"]}};type=application/json' \ -F 'filename[0][email protected] ' \ 'https://your-instance.com/apirest.php/Document/'
File uploads require the multipart/form-data content type. The metadata must be sent in the uploadManifest parameter as a JSON string.
Upload Parameters JSON string containing document metadata Array of filenames being uploaded (e.g., ["file.pdf"])
The actual file to upload (use @filename syntax in curl)
Response { "id" : 124 , "message" : "Document move succeeded." , "upload_result" : { "filename" : "network-diagram.pdf" , "size" : 245680 , "filepath" : "/2024/03/1234567890_network-diagram.pdf" } }
Upload Multiple Files You can upload multiple files in a single request:
curl -X POST \ -H 'Content-Type: multipart/form-data' \ -H "Session-Token: your_session_token" \ -F 'uploadManifest={"input": {"name": "Project Files", "_filename": ["doc1.pdf", "doc2.pdf"]}};type=application/json' \ -F 'filename[0][email protected] ' \ -F 'filename[1][email protected] ' \ 'https://your-instance.com/apirest.php/Document/'
Download a Document Download the actual file content of a document.
curl -X GET \ -H 'Content-Type: application/json' \ -H "Session-Token: your_session_token" \ -H "App-Token: your_app_token" \ -H "Accept: application/octet-stream" \ 'https://your-instance.com/apirest.php/Document/123' > document.pdf
To download a file, you must include the Accept: application/octet-stream header, or add the alt=media query parameter.
Alternative Download Method You can also use the alt=media query parameter:
curl -X GET \ -H "Session-Token: your_session_token" \ 'https://your-instance.com/apirest.php/Document/123?alt=media' > document.pdf
Link Document to Items Associate a document with other items (tickets, computers, users, etc.).
curl -X POST \ -H 'Content-Type: application/json' \ -H "Session-Token: your_session_token" \ -d '{ "input": { "documents_id": 123, "items_id": 456, "itemtype": "Ticket" } }' \ 'https://your-instance.com/apirest.php/Document_Item/'
Link Parameters ID of the item to link to
Type of item (e.g., Ticket, Computer, User)
Get Documents Linked to an Item Retrieve all documents associated with an item.
curl -X GET \ -H "Session-Token: your_session_token" \ 'https://your-instance.com/apirest.php/Ticket/456?with_documents=true'
Alternatively, search for document links:
curl -X GET \ -H "Session-Token: your_session_token" \ 'https://your-instance.com/apirest.php/Document_Item/?searchText[itemtype]=Ticket&searchText[items_id]=456'
Update document information (not the file itself).
curl -X PUT \ -H 'Content-Type: application/json' \ -H "Session-Token: your_session_token" \ -d '{ "input": { "name": "Updated Network Diagram", "documentcategories_id": 6 } }' \ 'https://your-instance.com/apirest.php/Document/123'
You cannot update the actual file content. To replace a file, delete the old document and upload a new one.
Delete a Document Delete a document and its associated file.
curl -X DELETE \ -H 'Content-Type: application/json' \ -H "Session-Token: your_session_token" \ 'https://your-instance.com/apirest.php/Document/123?force_purge=true'
If true, permanently delete the document and file. If false, move to trash.
Common Use Cases
Upload document and attach to ticket
# 1. Upload the document DOC_ID = $( curl -X POST \ -H 'Content-Type: multipart/form-data' \ -H "Session-Token: $SESSION_TOKEN " \ -F 'uploadManifest={"input": {"name": "Screenshot", "_filename": ["screenshot.png"]}};type=application/json' \ -F 'filename[0][email protected] ' \ 'https://your-instance.com/apirest.php/Document/' | jq -r '.id' ) # 2. Link to ticket curl -X POST \ -H 'Content-Type: application/json' \ -H "Session-Token: $SESSION_TOKEN " \ -d '{ "input": { "documents_id": ' $DOC_ID ', "items_id": 456, "itemtype": "Ticket" } }' \ 'https://your-instance.com/apirest.php/Document_Item/'
Download all documents from a ticket
# Get document links curl -X GET \ -H "Session-Token: $SESSION_TOKEN " \ 'https://your-instance.com/apirest.php/Ticket/456/Document_Item' | \ jq -r '.[] | .documents_id' | \ while read doc_id ; do # Download each document curl -X GET \ -H "Session-Token: $SESSION_TOKEN " \ -H "Accept: application/octet-stream" \ "https://your-instance.com/apirest.php/Document/ $doc_id " > "document_ $doc_id " done
Search documents by category
curl -g -X GET \ -H "Session-Token: $SESSION_TOKEN " \ 'https://your-instance.com/apirest.php/search/Document/?criteria[0][field]=2&criteria[0][searchtype]=equals&criteria[0][value]=5'
Where field 2 is documentcategories_id=5. File Type Restrictions ITSM-NG has security restrictions on file uploads:
Executable files (.exe, .bat, .sh) are typically blacklisted
PHP files and scripts are blocked for security
File types can be configured in Setup > Dropdowns > Document types
Maximum file size is determined by PHP settings (upload_max_filesize, post_max_size)
Check your document categories and allowed file extensions in the ITSM-NG interface under Setup > Dropdowns > Document types .
Best Practices
Use Categories Organize documents with categories for easier management and search.
Meaningful Names Use descriptive names for documents, not just filenames.
Link to Context Always link documents to relevant items (tickets, assets) for context.
Regular Cleanup Periodically review and remove obsolete documents to save storage.