Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/itsmng/itsm-ng/llms.txt

Use this file to discover all available pages before exploring further.

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:
​
id
integer
Unique document identifier
​
name
string
Document name/title
​
filename
string
Actual filename on disk
​
filepath
string
Relative path to the file
​
documentcategories_id
integer
Document category ID
​
mime
string
MIME type of the file (e.g., application/pdf, image/png)
​
date_creation
datetime
Upload date
​
date_mod
datetime
Last modification date
​
users_id
integer
User who uploaded the document
​
sha1sum
string
SHA1 hash of the file for integrity verification
​
is_blacklisted
boolean
Whether the file extension is blacklisted
​
tag
string
Optional tag for document organization

​
Get a Document

Retrieve document metadata (not the file itself).
cURL
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
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]=@network-diagram.pdf' \
  '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

​
uploadManifest
string
required
JSON string containing document metadata
​
filename[0]
file
required
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
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]=@doc1.pdf' \
  -F 'filename[1]=@doc2.pdf' \
  'https://your-instance.com/apirest.php/Document/'

​
Download a Document

Download the actual file content of a document.
cURL
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
curl -X GET \
  -H "Session-Token: your_session_token" \
  'https://your-instance.com/apirest.php/Document/123?alt=media' > document.pdf
Associate a document with other items (tickets, computers, users, etc.).
cURL
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/'
​
documents_id
integer
required
Document ID to link
​
items_id
integer
required
ID of the item to link to
​
itemtype
string
required
Type of item (e.g., Ticket, Computer, User)

​
Get Documents Linked to an Item

Retrieve all documents associated with an item.
cURL
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
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 Metadata

Update document information (not the file itself).
cURL
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
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'
​
force_purge
boolean
default:"false"
If true, permanently delete the document and file. If false, move to trash.

​
Common Use Cases

# 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]=@screenshot.png' \
  '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/'

# 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

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.

Build docs developers (and LLMs) love

Get started for freeTalk to us