HTTP¶
The HTTP API can be used to access NIM information. HTTP requests can be made to read information from the database, create new data, update existing data, and delete entries from the database. All requests responses are received in the form of JavaScript Object Notation (JSON) formatted objects if successful, and either text explaining the error or a value of FALSE.
HTTP requests are prefixed with the path to the hostname and NIM API and appended with the API command (CMD).
NIM API URL: http://hostname:portnumber/nimAPI.php?
API Example¶
The following request will return the basic job information for the given job ID:
URL: http://hostname:portnumber/nimAPI.php?q=getJobInfo&ID=1
Result: [{"ID":1,"number":"00000","jobname":"ADMIN","folder":"0_ADMIN"}]
The next example shows how to pass custom keys to update a job:
URL: http://hostname:portnumber/nimAPI.php?q=updateJob&jobID=1&customKeys={"My Custom Key Name":"Value"}
API Keys¶
NIM API keys are an optional security feature that restricts API access with time limited per user keys. Requiring API keys restricts all API access to only those users with an API key.
If Require API Keys is enabled in ADMIN/Security - Options, two HTTP headers are expected by the API:
X-NIM-API-USER |
This is the users username |
X-NIM-API-KEY |
This is the users API key |
The end users will be presented with a dialog box the first time they attempt to use a NIM Connector. API keys are unique to each user. Enter the NIM API key provided to you by your NIM administrator.
Note
It is recommended to ensure that all traffic is using HTTPS when enabling API keys to encrypt all communication. For more information on routing the NIM VM traffic please refer to the nim-ssl script in the Virtual Machine Shell Scripts section of the documentation.
For more information on enabling NIM API Keys please refer to the API Keys section of the documentation. For information on creating user API keys please refer to the Users Grid section of the Administration documentation.
API Common Functions¶
Test API¶
Used to test connectivity to the NIM API
URL: http://hostname:portnumber/nimAPI.php?q=testAPI
Return:
example: [{"version":"2.5.15.161123","keyValid":"false","keyRequired":"false","error":""}]
version - The current NIM version
keyValid - Is the API key valid
keyRequired - Is Require API Keys enabled
error - Any addtional error logs
Get Culture Codes¶
Retrieves a list of currency codes used for setting the currency type of an item
URL: http://hostname:portnumber/nimAPI.php?q=getCultureCodes
Return:
example: {"success":true,"error":"","rows":[{"cultureCode":"en-US","currency":"United States Dollar","currencyCode":"USD"},{"cultureCode":"en-IE","currency":"Euro (Ireland)","currencyCode":"EUR"},...,"totalRows":44}
Returns json as an associative array in the format
result->success True/False
result->error Includes any error or security messaging
result->rows An array of returned data
result->totalRows The total count of returned rows in the array
Users¶
Get User ID¶
Retrieves the user ID from username
URL: http://hostname:portnumber/nimAPI.php?q=getUserID
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
u The username to retrieve the ID string YES
Return:
int
Get User Full Name¶
Retrieves the user's full name from username
URL: http://hostname:portnumber/nimAPI.php?q=getUserFullName
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
u The username to retrieve the ID string YES
Return:
first_name
last_name
Get All Users¶
Returns the full list of NIM Users
URL: http://hostname:portnumber/nimAPI.php?q=getUsers
Return:
ID
username
first_name
last_name
full_name
Get User Info¶
Returns the ID, username, first name, last name, and email address for a given user based on ID or username. One of the two search parameters needs to be provided.
URL: http://hostname:portnumber/nimAPI.php?q=getUserInfo
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
ID The ID of the user to query integer Optional
username The username of the user to query string Optional
Return:
ID
username
first_name
last_name
full_name
email
Locations¶
Get All Locations¶
URL: http://hostname:portnumber/nimAPI.php?q=getLocations
Return:
ID
name
description
Jobs¶
Get User Jobs¶
Retrieves all jobs the user is assigned to.
URL: http://hostname:portnumber/nimAPI.php?q=getUserJobs
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
u User ID to retrieve jobs integer YES
Return:
ID
number
jobname
folder
Add Job¶
Creates a new job.
If no default job number template is set, either number or numberTemplate must be included.
URL: http://hostname:portnumber/nimAPI.php?q=addJob
Parameters Type Values Default Required
________________________________________________________________________________________________
name string YES
number string
numberTemplate string
description string
client string
agency string
producer string
agency_producer string
phone string
email string
prod_co string
prod_director string
prod_contact string
prod_phone string
prod_email string
prod_shoot_date date YYYY-mm-dd
prod_location string
prod_supervised boolean 0/1 0
editorial string
editor string
grading string
colorist string
music string
mix string
sound string
creative_lead string
projectStatus string ACTIVE / INACTIVE ACTIVE
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus
jobStatusID integer
jobStatus string
biddingLocationID OR biddingLocation
biddingLocationID integer
biddingLocation string
assignedLocationID OR assignedLocation
assignedLocationID integer
assignedLocation string
start_date date YYYY-mm-dd
end_date date YYYY-mm-dd
currency string 3 digit currency code DEPRECATED
cultureID should be used instead of currency
If currency is set insead of cultureID, NIM will use the first matching cultureID
cultureID integer
keywords array ["keyword1","keyword2"]
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=addJob&number=1&name=MyNewJob&customKeys={"My Custom Key Name":"Some text"}
Notes:
If no default job number template is set, either number or numberTemplate must be included
Return:
JSON Array
Update Job¶
Updates an existing job based on the jobID.
- The following values will only be updated if the job is offline:
folder projectStructureID projectStructure
URL: http://hostname:portnumber/nimAPI.php?q=updateJob
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string
number string
description string
client string
agency string
producer string
agency_producer string
phone string
email string
prod_co string
prod_director string
prod_contact string
prod_phone string
prod_email string
prod_shoot_date string YYYY-mm-dd
prod_location string
prod_supervised boolean 0 / 1 0
editorial string
editor string
grading string
colorist string
music string
mix string
sound string
creative_lead string
projectStatus string ACTIVE / INACTIVE ACTIVE
folder string
projectStructureID OR projectStructure
projectStructureID integer
projectStructure string
jobStatusID OR jobStatus
jobStatusID integer
jobStatus string
biddingLocationID OR biddingLocation
biddingLocationID integer
biddingLocation string
assignedLocationID OR assignedLocation
assignedLocationID integer
assignedLocation string
start_date date YYYY-mm-dd
end_date date YYYY-mm-dd
currency string 3 digit currency codes DEPRECATED
cultureID should be used instead of currency
If currency is set insead of cultureID, NIM will use the first matching cultureID
cultureID integer
keywords array ["keyword1","keyword2"]
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=updateJob&jobID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Delete Job¶
Deletes a job based on jobID.
This is a soft delete and these jobs can be recovered or permanently deleted from the Admin UI.
URL: http://hostname:portnumber/nimAPI.php?q=deleteJob
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
Return:
JSON Array
[{"success","true"},{"error",""}]
Upload Job Icon¶
Uploads a new job icon for a specified job ID. File information for the image to be uploaded needs to be included in the $_FILES directive.
URL: http://hostname:portnumber/nimAPI.php?q=uploadJobIcon
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
Return:
Get Job Info¶
Retrieves job information for a specified job ID.
URL: http://hostname:portnumber/nimAPI.php?q=getJobInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
Return:
Object
success - true or false
iconPath - if succesfull the path to the uploaded media will be returned
error - any associated error message
Servers & Project Structure¶
Get All Servers¶
Retrieves all servers optionally filtered by locationID
URL: http://hostname:portnumber/nimAPI.php?q=getServers
PARAMS:
ID - location ID
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
ID Optional filter by location integer
Return:
ID
server
description
locationID
mountpoint
mountsource
path
winPath
osxPath
priority
is_projServer
Get Job Servers¶
Retrieves servers associated with a specified job ID
URL: http://hostname:portnumber/nimAPI.php?q=getJobServers
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
ID Job ID integer YES
RETURN:
ID
server
description
locationID
mountpoint
mountsource
path
winPath
osxPath
priority
is_projServer
Get Server Info¶
Retrieves servers information from server ID
URL: http://hostname:portnumber/nimAPI.php?q=getServerInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
RETURN:
ID
server
description
locationID
mountpoint
mountsource
path
winPath
osxPath
priority
is_projServer
Get Server OS Path¶
Returns the path to the server based on OS type.
URL: http://hostname:portnumber/nimAPI.php?q=get_serverOSPath
Parameters Description Type Values Default Required
____________________________________________________________________________________________________________________
ID ID of the server integer YES
os OS Type string win,Windows,osx,mac, Linux YES
Darwin, Linux
Return:
serverOSPath
Get OS Path¶
Retrieves file path based on file ID and OS type.
URL: http://hostname:portnumber/nimAPI.php?q=getOSPath&fileID=ID&os=osType
Parameters Description Type Values Default Required
____________________________________________________________________________________________________
ID ID of the server integer YES
os OS Type string win,Windows,osx,mac, Linux YES
Darwin, Linux
Return:
path
Get Asset Master OS Path¶
Returns the path to the Asset Master based on asset ID and OS type.
URL: http://hostname:portnumber/nimAPI.php?q=getAssetMasterOSPath
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________
assetID Asset ID integer YES
os OS Type string win,Windows,osx,mac, Linux YES
Darwin, Linux
RETURN:
path
Get Paths¶
Retrieves the NIM path for a project structure given the item ID and the path item to look for.
- Type Options:
job (PROJECT ROOT)
asset (ASSET ROOT, ASSET COMPS, ASSET RENDERS)
show (SHOW ROOT)
shot (SHOT ROOT, SHOT PLATES, SHOT COMPS, SHOT RENDERS)
URL: http://hostname:portnumber/nimAPI.php?q=getPaths
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
item string job, show, shot, asset YES
RETURN:
path
Resolve Server OS Path¶
Given a path string, this function will look for matching NIM server and return an OS centric path based on the os name provided.
URL: http://hostname:portnumber/nimAPI.php?q=resolveOSPath
Parameters Type Values Default Required
________________________________________________________________________________________________
os string linux, win, osx YES
path string YES
RETURN:
path
Can Bring Online¶
Tests item against project structure to see if it can be brought online.
- Item types can be asset or shot
If asset, jobID OR assetID must be passed
If shot, showID or shotID must be passed
URL: http://hostname:portnumber/nimAPI.php?q=canBringOnline
Parameters Type Values Default Required
________________________________________________________________________________________________
item string shot, asset shot YES
jobID integer ---
assetID integer ---
showID integer ---
shotID integer ---
Return:
1 if the item can be brought online or 0 if not.
Bring Onine¶
Brings assets and shots online creating folders from project structure
- Item types can be asset or shot
If asset, assetID must be passed
If shot, shotID must be passed
CMD: http://hostname:portnumber/nimAPI.php?q=bringOnline
Parameters Type Values Default Required
________________________________________________________________________________________________
type string shot, asset shot YES
assetID integer
shotID integer
RETURN:
success - true or false
error - error message passed here if failed to bring item online
Assets¶
Get Assets¶
Returns all assets for a given job id
URL: http://hostname:portnumber/nimAPI.php?q=getAssets
Parameters Description Type Values Default Required
___________________________________________________________________________________________________________
ID The job ID integer YES
Return:
ID
name
Add Assets¶
Adds a new asset to a job and returns the new assetID.
If an asset with the specified name already exists, NIM wil update the existing asset instead of creating a new one with a duplicate name.
An asset status can be passed by either name or ID.
If both are passed the ID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=addAsset
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=addAsset&jobID=1&name=MyNewAsset&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Update Assets¶
Updates an existing asset based on the assetID.
An asset status can be passed by either name or ID. If both are passed the ID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=updateAsset
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
assetStatusID integer
assetStatus string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=updateAsset&assetID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Delete Assets¶
Deletes an asset based on assetID.
URL: http://hostname:portnumber/nimAPI.php?q=deleteAsset
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
Return:
JSON Array
Upload Asset Icon¶
Uploads a thumbnail for an asset
URL: http://hostname:portnumber/nimAPI.php?q=upload_assetIcon
The $_FILES directive must contain file for upload
Parameters Type Values Default Required
________________________________________________________________________________________________
assetID integer YES
Return:
success - true or false
error - will contain any generated error messages
Get Asset Info¶
Retrieves information for a given asset from the asset ID.
URL: http://hostname:portnumber/nimAPI.php?q=getAssetInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
jobID
jobFolder
jobNumber
jobName
AMR_path
AMR_filename
assetName
Get Asset Icon¶
Retrieves the path to the asset’s icon for a given assetID
URL: http://hostname:portnumber/nimAPI.php?q=getAssetIcon
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
img_link
Shows¶
Get Shows¶
Returns all shows for a given job id
URL: http://hostname:portnumber/nimAPI.php?q=getShows
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
ID
showname
folder
Get Show Info¶
Returns all show information for a given show id
URL: http://hostname:portnumber/nimAPI.php?q=getShowInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
RETURN:
ID
jobID
showname
folder
show_status
trt
previs_id
is_previs
has_previs
Add Show¶
Adds a new show to a job and returns the new showID
URL: http://hostname:portnumber/nimAPI.php?q=addShow
Parameters Type Values Default Required
________________________________________________________________________________________________
jobID integer YES
name string YES
trt string 00:00:00:00
has_previs boolean 0/1 (a value of 1 will create an associated previs show)
Return:
JSON Array
Update Show¶
Updates an existing show based on the showID.
Show name will only be updated if the show is offline.
URL: http://hostname:portnumber/nimAPI.php?q=updateShow
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
name string
trt string 00:00:00:00
Return:
JSON Array
Delete Show¶
Deletes an existing show based on the showID.
URL: http://hostname:portnumber/nimAPI.php?q=deleteShow
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
Return:
JSON Array
Shots¶
Get Shots¶
Returns all shots for a given show id
URL: http://hostname:portnumber/nimAPI.php?q=getShots
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
Return:
ID
name
Add Shot¶
Adds a shot to a show and returns the new ID.
If a shot with the specified name already exists, NIM will update the existing shot instead of creating a new one with a duplicate name.
A shot status can be passed by either name or ID. If both are passed the ID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=addShot
Parameters Type Values Default Required
________________________________________________________________________________________________
showID integer YES
name string YES
shotStatusID integer
shotStatus string
description string
vfx string
fps string
frames/shotDuration string
handles string
heads string
tails string
height string
pan string
tilt string
roll string
lens string
fstop string
filter string
dts string
focus string
ia string
convergence string
cam_roll string
stock string
format string
crop string
protect string
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=addShot&showID=1&name=MyNewShot&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Update Shot¶
Updates an existing shot based on the shotID.
A shot status can be passed by either name or ID. If both are passed the ID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=updateShot
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
shotStatusID integer
shotStatus string
description string
vfx string
fps string
frames/duration string
handles string
heads string
tails string
height string
pan string
tilt string
roll string
lens string
fstop string
filter string
dts string
focus string
ia string
convergence string
cam_roll string
stock string
format string
crop string
protect string
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=updateShot&shotID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Delete Shot¶
Deletes a shot based on shotID.
URL: http://hostname:portnumber/nimAPI.php?q=deleteShot
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
Return:
JSON Array
Upload Shot Icon¶
Uploads a thumbnail for a shot
URL: http://hostname:portnumber/nimAPI.php?q=upload_shotIcon
The $_FILES directive must contain file for upload
Parameters Type Values Default Required
________________________________________________________________________________________________
shotID integer YES
RETURN:
success - true or false
error - will contain any generated error messages
Get Shot Info¶
Retrieves shot information based from a given shot ID.
URL: http://hostname:portnumber/nimAPI.php?q=getShotInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
RETURN:
jobID
jobFolder
jobNumber
jobName,
showID
showFolder
showName
shotName
Get Shot Icon¶
Retrieves the path to the shot’s icon for a given shotID
URL: http://hostname:portnumber/nimAPI.php?q=getShotIcon
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
RETURN:
img_link
Tasks¶
Get Task Types¶
Retrieves the available task types from the API, optionally filtering down to only task types that are associated with files on a specific shot or asset.
URL: http://hostname:portnumber/nimAPI.php?q=getTaskTypes
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________
app Optional filter by application string MAYA, C4D, AE, NUKE, all
HIERO, PHOTOSHOP, 3DSMAX,
HOUDINI, FLAME, all artist
type Optional filter by role type string artist, producer, management
all
assetID Include tasks used on assetID integer
shotID Include tasks used on shotID integer
onlyWithFiles Flag to return only task types that are associated integer 0 or 1 0
with files on provided shot or asset
pub Optional filter for the onlyWithFiles flag to integer 0 or 1 0
return only task types with published files
RETURN:
ID
name
folder
Add Task¶
Adds a new task to an asset or shot.
AssetID or shotID can be passed. If both are passed, assetID will be used.
The task type can be determined by passing taskTypeID or taskTypeName. If both are passed, taskTypeID will be used.
A user can be attached to the task by passing either userID or username. If both are passed, userID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=addTask
Parameters Type Values Default Required
_______________________________________________________________________________________________________
assetID or shotID YES
assetID integer
shotID integer
taskTypeID or taskTypeName YES
taskTypeID integer
taskTypeName string
userID OR username
userID integer
username string
taskStatusID OR taskStatus
taskStatusID integer
taskStatus string
description string
estimated_hours float
startDate UTC datetime string "2017-01-01 08:00:00"
endDate UTC datetime string "2017-01-01 08:00:00"
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=addTask&assetID=1&taskTypeID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Update Task¶
Updates an existing task based on taskID.
The task type can be determined by passing taskTypeID or taskTypeName. If both are passed, taskTypeID will be used.
A user can be attached to the task by passing either userID or username. If both are passed, userID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=updateTask
Parameters Type Values Default Required
__________________________________________________________________________________________________________
taskID integer YES
taskTypeID or taskTypeName
taskTypeID integer
taskTypeName string
userID OR username
userID integer
username string
taskStatusID OR taskStatus
taskStatusID integer
taskStatus string
description string
estimated_hours float
startDate UTC datetime string "2017-01-01 08:00:00")
endDate UTC datetime string "2017-01-01 08:00:00")
customKeys dictionary {"Custom Key Name" : "Value"}
Example:
.../nimAPI.php?q=updateTask&taskID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
JSON Array
Delete Task¶
Deletes a task based on taskID.
URL: http://hostname:portnumber/nimAPI.php?q=deleteTask
Parameters Type Values Default Required
__________________________________________________________________________________________________________
taskID integer YES
Return:
JSON Array
Get Task Info¶
Retrieves information about one or more tasks.
Given the taskID passed as ID, this function will return the information for a single task.
Given the itemID for an asset or shot and setting the class to “asset” or “shot” will return information for all tasks for the respective item.
CMD: http://hostname:portnumber/nimAPI.php?q=getTaskInfo
Parameters Type Values Default Required
__________________________________________________________________________________________________________
ID integer ---
itemID integer ---
class string asset/shot ---
RETURN:
taskID
taskDesc
taskName
username
Files¶
Get Element Exports¶
Retrieves all element export settings for a given file ID Used in conjunction with setting Photoshop export settings
URL: http://hostname:portnumber/nimAPI.php?q=getElementExport
Parameters Type Values Default Required
__________________________________________________________________________________________________________
ID integer YES
Return:
JSON array of settings used by the Photoshop connector
Set Element Exports¶
Sets the element export settings for a given file ID Used in conjunction with setting Photoshop export settings
URL: http://hostname:portnumber/nimAPI.php?q=setElementExports
Parameters Type Values Default Required
__________________________________________________________________________________________________________
fileID integer YES
exports array YES
Parameter Details:
fileID - the ID of the file to associate the element export settings
exports - an array of export settings used by the NIM Photoshop connector
The export array requires the following settings:
isElement
elementTypeID
export
extension
bitDepth
resolution
epsPreview
epsEncoding
epsHalftone
epsTransferFunction
epsPostScriptColor
epsVectorData
epsInterpolation
jpgQuality
jpgFormat
jpgScans
pngCompression
pngInterlaced
tgaResolution
tgaCompress
tifImageCompression
tifSaveImagePyramid
tifSaveTransparency
tifPixelOrder
tifByteOrder
tifLayerCompression
Return:
JSON Araay
Get Basenames¶
Returns all basenames for a show, shot, or asset.
CMD: http://hostname:portnumber/nimAPI.php?q=getBasenames
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
ID The parent ID integer YES
class The parent class string asset, shot, show YES
type / taskType Task type Name to filter results string
task_type_ID / taskTypeID Task type ID to filter results integer
pub Filter to only return published basenames boolean True/False
Return:
basename
Get Published Basename¶
Retrieves information for the published file for a given basename.
The optional username is used to return the date information in the users selected timezone.
URL: http://hostname:portnumber/nimAPI.php?q=getBasenamePub
Parameters Type Values Default Required
________________________________________________________________________________________________
class string asset, shot, show YES
itemID integer YES
basename string YES
username string
RETURN:
fileID
fileClass
parentID
serverID
task_type
task_type_ID
task_type_folder
basename
filename
filepath
ext
version
isPublished
isWorking
note
userID
username
date
metadata
customKeys
Get All Published Basenames¶
Retrieves all published basename files for a given asset or shot filtered by task type.
The “type” parameter is the task type name.
The optional username is used to return the date information in the users selected timezone.
URL: http://hostname:portnumber/nimAPI.php?q=getBasenameAllPub
Parameters Type Values Default Required
________________________________________________________________________________________________
class string asset, shot, show YES
itemID integer YES
type string YES if task_type_ID is not passed
task_type_ID integer YES if type is not passed
basename string YES
username string
RETURN:
fileID
fileClass
parentID
serverID
task_type
task_type_ID
task_type_folder
basename
filename
filepath
ext
version
isPublished
isWorking
note
userID
username
date
metadata
customKeys
Get Basename Info¶
Retrieves all basenames and their max version for given asset, shot, or show based on ID
URL: http://hostname:portnumber/nimAPI.php?q=getBasenamesInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
class string show, shot, asset YES
task_type_ID ID YES
Return:
JSON Array
Get Basename Version¶
Retrieves the highest version number for a given basename on an asset, shot, or show based on ID
URL: http://hostname:portnumber/nimAPI.php?q=getBasenameVersion
Parameters Type Values Default Required
________________________________________________________________________________________________
class string show,shot,asset YES
itemID integer
basename string YES
Return:
ID The file ID for the returned version
basename The basename of the returned version
version The version number
Get Versions¶
Retrieves the versions for a given basename.
The optional username is used to return the date information in the users selected timezone.
URL: http://hostname:portnumber/nimAPI.php?q=getVersions
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
class The parent class type string show,shot,asset YES
itemID The parent ID integer YES
basename The basename in which to find versions string YES
pub Filter to only return published basenames boolean 1/0 0
username User to set timezone string
Return:
fileID
fileClass
parentID
serverID
task_type
task_type_ID
task_type_folder
basename
filename
filepath
ext
version
isPublished
isWorking
note
userID
username
date
metadata
customKeys
Get Version Info¶
Retrieves the version information of a specified file ID.
URL: http://hostname:portnumber/nimAPI.php?q=getVersionInfo&ID=fileID
Parameters Type Values Default Required
________________________________________________________________________________________________
ID integer YES
username string
RETURN:
fileID
fileClass
parentID
serverID
task_type
task_type_ID
task_type_folder
basename
filename
filepath
ext
version
isPublished
isWorking
note
userID
username
date
metadata
customKeys
Get Max Version¶
Retrieves the highest version number in a basename for a given fileID.
URL: http://hostname:portnumber/nimAPI.php?q=getMaxVersion
Parameters Type Values Default Required
________________________________________________________________________________________________
fileID integer YES
RETURN:
maxVersion
Clear Published Flags¶
Clears all published flags from basename
URL: http://hostname:portnumber/nimAPI.php?q=clearPubFlags
Parameters Description Type Values Default Required
_____________________________________________________________________________________________________________________________________________
class The parent class type string show,shot,asset YES
itemID The parent ID integer YES
basename The basename name string YES
Return:
success
Publish Symbolic Link¶
Creates the symbolic link for a published file based on the file ID
Force Link creates a symbolic link even if the source location is invalid.
URL: http://hostname:portnumber/nimAPI.php?q=publishSymlink
Parameters Type Values Default Required
________________________________________________________________________________________________
fileID integer YES
forceLink boolean True/False True
Return:
boolean (true/false)
Success returns true
Add File¶
Saves a file to the NIM database
URL: http://hostname:portnumber/nimAPI.php?q=addFile
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
class Class of parent for the file string show, shot, or asset YES
itemID ID of the parent integer YES
task_type_ID Task type ID to associate with the file integer YES
task_type_folder Task folder to use for the file string YES
userID ID of the user who owns the file integer YES
basename Basename for the file string YES
filename File name of the file being saved string YES
path Path to the file string YES
serverID ID of the server where file exists integer YES
ext File extension string
version Version of the file integer
note Note to add to the file entry string
isPub Value of True will publish the file boolean True/False False
isWork Mark file as a working file boolean True/False True
customKeys Dictionary of custom keys dictionary {"Custom Key Name" : "Value"}
metadata Dictionary of metadata (Internal Use) dictionary {"Key" : "Value"}
Example:
.../nimAPI.php?q=addFile&class=asset&itemID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
Array in the format {success, error, ID} where the ID is the NIM ID of the newly created file.
Update File¶
Updates an existing file in the NIM database
URL: http://hostname:portnumber/nimAPI.php?q=updateFile
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID ID of the file to update integer YES
task_type_ID Task type ID to associate with the file integer
task_type_folder Task folder to use for the file string
userID ID of the user who owns the file integer
basename Basename for the file string
filename File name of the file being saved string
filepath Path to the file string
ext File extension string
version Version of the file integer
note Comment to add to the file entry string
serverID ID of the server where file exists integer
isPub Value of True will publish the file boolean True/False False
isWork Mark file as a working file boolean True/False True
customKeys Dictionary of custom keys dictionary {"Custom Key Name" : "Value"}
metadata Dictionary of metadata (Internal Use) dictionary {"Key" : "Value"}
Example:
.../nimAPI.php?q=updateFile&fileID=1&customKeys={"My Custom Key Name":"Some text"}
Return:
Array in the format {success, error, ID} where the ID is the NIM ID of the newly created file.
Find Files¶
A search function for files.
Any provided parameters will filter the returned list.
URL: http://hostname:portnumber/nimAPI.php?q=findFiles
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
name Find matching name string
path Find matching path string
parent Used with parentID to set the parent type string ASSET / SHOT
parentID Finds children of the parent item integer
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
Return:
ID
class
parentID
serverID
task_type
task_type_ID
task_type_folder
basename
filename
filepath
ext
version
isPublished
isWorking
note
userID
username
date
metadata
customKeys
Elements¶
Get Element Types¶
Returns the full list of element types.
URL: http://hostname:portnumber/nimAPI.php?q=getElementTypes
RETURN:
ID
name
Get Element Type¶
Returns the element type name from the ID.
URL: http://hostname:portnumber/nimAPI.php?q=getElementType
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
RETURN:
name
Find Elements¶
A more robust search function for elements.
All parameters are optional.
Any provided parameters will filter the returned list.
URL: http://hostname:portnumber/nimAPI.php?q=findElements
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
name Element name string
path Element path string
jobID Job ID integer
showID Show ID integer
shotID Shot ID integer
assetID Asset ID integer
taskID Task ID integer
renderID Render ID integer
elementTypeID Element type ID integer
ext File extension string
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
RETURN:
JSON Array
Get Elements¶
Retrieves a dictionary of elements for a particular type given parentID.
If no elementTypeID is given will return elements for all types.
URL: http://hostname:portnumber/nimAPI.php?q=getElements
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
parent Parent of the element string shot, asset, task, or render shot YES
parentID ID of the parent object integer YES
elementTypeID ID of the element type integer
getLastElement Return on the last published element boolean True/False False
isPublished Return only the published elements boolean True/False False
RETURN:
ID
jobID
assetID
shotID
renderID
elementTypeID
elementType
name
path
full_path
isPublished
Add Element¶
Adds an element to an asset, shot, task, or render
URL: http://hostname:portnumber/nimAPI.php?q=addElement
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
parent Parent of the element string shot, asset, task, or render shot YES
parentID ID of the parent object integer YES
typeID Element Type ID integer YES
path Path to the file string YES
name Name of the file string YES
startFrame If a sequence, this is the start frame integer
endFrame If a sequence, this is the end frame integer
handles If a sequence, this is the handle length integer
isPublished Should element be flagged as published boolean True/False False
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
RETURN:
success
error
Update Element¶
Updates an existing element by element ID
URL: http://hostname:portnumber/nimAPI.php?q=updateElement
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
userID User ID integer
jobID Job ID integer
assetID Asset ID integer
shotID Shot ID integer
taskID Task ID integer
renderID Render ID integer
elementTypeID Element Type ID integer
name Name of the file string
path Path to the file string
startFrame If a sequence, this is the start frame integer
endFrame If a sequence, this is the end frame integer
handles If a sequence, this is the handle length integer
isPublished Should element be flagged as published boolean True/False False
metadata Find matching metadata (Internal) dictionary {"Key" : "Value"}
RETURN:
JSON Array
Delete Element¶
Deletes an existing element by element ID
URL: http://hostname:portnumber/nimAPI.php?q=deleteElement
Parameters Description Type Values Default Required
_________________________________________________________________________________________________________________________________________________
ID Element ID integer YES
Return:
JSON Array
Render¶
Add Render:¶
Logs a render to a given taskID.
URL: http://hostname:portnumber/nimAPI.php?q=addRender
Parameters Description Type Values Default Required
______________________________________________________________________________________________________________________________________________________
taskID ID of the task to log the render integer YES
jobID ID of job to log the render integer
class Is this an asset or shot render string asset, shot shot
fileID ID of a file to associate with render integer
renderKey Unique Key for render to link to external string
database / render management software
renderName Name of the render string
renderType Type of render string
(example: Deadline will pass "mayaPlugin", "nukePlugin", etc...)
renderComment Comment to add to the render string
outputDirs Array out output directories from the render JSON array
outputFiles Array of output files from the render JSON array
elementTypeID ID of the element type to use for the render integer
start_datetime Datetime value for the start of the render datetime
end_datetime Datetime value for the end of the render datetime
avgTime Average time of the render string
totalTime Total time of the render string
iconPath Path to the render icon string
frames The total frame count of the render integer
RETURN:
success
error
Upload Render Icon:¶
Uploads an icon for a render
URL: http://hostname:portnumber/nimAPI.php?q=uploadRenderIcon
TYPE: POST
2 required fields:
renderID or renderKey
$_FILE[]
$_FILE[] needs to include a image binary file in the $_FILES directive
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
renderID ID of the render to add the icon integer YES if renderKey is not passed
renderKey RenderKey of the render to add the icon string YES if renderID is not passed
RETURN:
success - true or false
error - will contain any generated error messages
Get Last Shot Render:¶
Retrieves the latest render for a shot
URL: http://hostname:portnumber/nimAPI.php?q=getLastShotRender
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the shot to retrieve last render integer YES
RETURN:
ID
jobID
class
taskID
fileID
userID
renderKey
deadlineID
renderName
renderType
comment
date
outputDirs
outputFiles
frames
start_datetime
end_datetime
avgTime
totalTime
iconPath
Review¶
Get Review Item Types¶
Retrieves the ID and name for all possible review items types
URL: http://hostname:portnumber/nimAPI.php?q=getReviewItemTypes
RETURN:
JSON Array of review item types:
ID - The ID of the review item type
name - The name of the review item type
Get Task Review Items¶
Retrieves review items for the specified taskID
URL: http://hostname:portnumber/nimAPI.php?q=getTaskDailies
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
taskID ID of the task to retrieve dailies integer YES
RETURN:
JSON Array of dailies items:
ID - The ID of the daily
name - The name of the daily
filepath - The filepath to the movie
iconPath - The path to the dailies icon relative to the NIM URL
dailiesMP4 -The path of the source mp4 relative to the NIM URL
submitted - The submitted for review status - 0 not submitted / 1 submitted
renderID - The ID of the associated render
renderName - The name of the associated render
frames - The total number of frames in the render
avgTime - The average frame time for the render
totalTime - The total time of the render
renderDate - The date of the render
renderIconPath - The path to the render icon relative to the NIM URL
comment - The text of the render comment
Upload Review Item¶
Uploads a review item to a given context
URL: http://hostname:portnumber/nimAPI.php?q=uploadReviewItem
TYPE: POST
Only 2 required fields:
itemID, itemType
$_FILE[] needs to include a mov file in the $_FILES directive
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
itemID ID of the parent item integer YES
itemType The type of parent item string user, job, show, shot, task, render YES
name The name of the review item string
description The description of the review item string
reviewItemTypeID The ID for the reviewItemType integer
reviewItemStatusID The ID for the reviewItemStatus integer
keywords An array of keywords to associate array string Format: ["keyword1","keyword2"]
Return:
success - true or false
error - will contain any generated error messages
Upload Review Note¶
Uploads a note to an existing daily in NIM along with an associated image
The $_FILES directive must contain the file for upload
URL: http://hostname:portnumber/nimAPI.php?q=uploadReviewNote
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
dailiesID ID of the daily to add note integer YES
name Name of the note string
note Text of the note string
frame Frame number to associate note integer
time Time in the movie to associate note. string
If this is not frame specific, -1 can be used.
userID NIM user ID of the note owner integer YES
RETURN:
success - true or false
error - will contain any generated error messages
- getReviewItems”:
- // Required Parameters:
// parentType user, job, dev, asset, show, shot, task, render // parentID ID of the parent; jobID if “dev”
- // Optional Parameters:
// allChildren 0 or 1, determines if we return review items associated with child items or not; // for example, if parent is show, would return review items on the show as well as // children shots, tasks, and renders // name Filters the returned review items by the given name // description Filters the returned review items to items that contain the given string // date Filters the returned review items by the given date in the format: yyyy-mm-dd // typeID OR type Filters the returned review items by the given typeID OR type name // statusID OR status Filters the returned review items by the given statusID OR status name // keywordID OR keyword Filters the returned review items by the given keywordID OR keyword name
- // Example:
// …/nimAPI.php?q=getReviewItems&parentType=asset&parentID=1
Get Review Items¶
Returns the child review items and details for the given parent item
URL: http://hostname:portnumber/nimAPI.php?q=getReviewItems
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
parentType string user YES
job
dev
asset
show
shot
task
render
parentID ID of the parent; jobID if value is "dev" integer YES
allChildren 0 or 1, determines if we return review items associated with child items or not;
for example, if parent is show, would return review items on the show as well as
children shots, tasks, and renders
name Filters the returned review items by the given name
description Filters the returned review items to items that contain the given string
date Filters the returned review items by the given date in the format: yyyy-mm-dd
typeID OR type Filters the returned review items by the given typeID OR type name
statusID OR status Filters the returned review items by the given statusID OR status name
keywordID OR keyword Filters the returned review items by the given keywordID OR keyword name
Example:
.../nimAPI.php?q=getReviewItems&parentType=asset&parentID=1
RETURN:
success - true or false
data - an associative array review item details:
ID - The ID of the review item
renderKey - an associated render key if applicable
name - the name of the review item
description - the description for the review item
reviewItemTypeID - the assocaited review item type ID
reviewItemGroupID - the group ID for review items belonging to a set of versions
reviewItemStatusID - the assoiciated review item status ID
iconPath - the path to the poster icon
mp4 - the path to the mp4 media if one exists
ogv - the path to the ogv media if one exists
webm - the path to the webm media if one exists
filmstrip - the path to the filmstrip image if one exists
width - width of the media
height - height of the media
duration - the duration of the media if applicable
frames - the frames of the media if applicable
frame_rate - the frame rate of the media if applicable
date - the creation date
creatorUserID - the creators user ID
creatorFullName - the creators full name
itemType - the type of parent this review item is assocaited with (user, job, dev, asset, show, shot, task)
itemID - the ID of the parent item
mediaType - the type of media (image, pdf, video)
mediaPath - the path to the uploaded media
error - will contain any generated error messages
Get Review Item Details¶
Returns the details for the given review item ID
URL: http://hostname:portnumber/nimAPI.php?q=getReviewItem
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
RETURN:
success - true or false
data - an associative array review item details:
ID - The ID of the review item
renderKey - an associated render key if applicable
name - the name of the review item
description - the description for the review item
reviewItemTypeID - the assocaited review item type ID
reviewItemGroupID - the group ID for review items belonging to a set of versions
reviewItemStatusID - the assoiciated review item status ID
iconPath - the path to the poster icon
mp4 - the path to the mp4 media if one exists
ogv - the path to the ogv media if one exists
webm - the path to the webm media if one exists
filmstrip - the path to the filmstrip image if one exists
width - width of the media
height - height of the media
duration - the duration of the media if applicable
frames - the frames of the media if applicable
frame_rate - the frame rate of the media if applicable
date - the creation date
creatorUserID - the creators user ID
creatorFullName - the creators full name
itemType - the type of parent this review item is assocaited with (user, job, dev, asset, show, shot, task)
itemID - the ID of the parent item
mediaType - the type of media (image, pdf, video)
mediaPath - the path to the uploaded media
error - will contain any generated error messages
Get Review Item Notes¶
Returns the all notes for a given review item ID
URL: http://hostname:portnumber/nimAPI.php?q=getReviewNotes
Parameters Description Type Values Default Required
_______________________________________________________________________________________________________________________________________________________________
ID ID of the review item integer YES
RETURN:
success - true or false
data - an array of objects containing all assocaited note data
error - will contain any generated error messages
Timecards¶
Get Timecards¶
Retrieves a timecard, or array of timecards based on search criteria
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
URL: http://hostname:portnumber/nimAPI.php?q=getTimecards
Parameters Type Values Default Required
________________________________________________________________________________________________
startDate date format: 2017-11-30 not required if jobID provided
endDate date format: 2017-11-30 not required if jobID provided
jobID integer ---
userID integer
username string
taskTypeID integer
taskType string
taskID integer
locationID integer
location string
Return:
JSON Array
Add Timecards¶
Adds a new timecard
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
If a taskID is passed, the tasks values will override userID, jobID, and taskTypeID
URL: http://hostname:portnumber/nimAPI.php?q=addTimecard
Parameters Type Values Default Required
________________________________________________________________________________________________
date date format: 2017-11-30 YES
userID integer
username string
jobID integer
taskTypeID integer
taskType string
taskID integer
startTime string range: 00:00:00 to 23:59:59
endTime string range: 00:00:00 to 23:59:59
hrs decimal hours between start_time and end_time, including break_hrs, ot, and dt; max 24
breakHrs decimal must fit within hrs
ot decimal must fit within hrs - break_hrs
dt decimal must fit within hrs - (break_hrs + ot)
locationID integer
location string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
Return:
dictionary
Update Timecard¶
Updates an existing timecard
A user can be passed by either username or userID. If both are passed the userID will be used. A taskType can be passed by either the name using taskType or ID with taskTypeID. If both are passed the taskTypeID will be used. A location can be passed by either the name using location or ID with locationID. If both are passed the locationID will be used.
If a taskID is passed, the tasks values will override userID, jobID, and task_types_ID
URL: http://hostname:portnumber/nimAPI.php?q=updateTimecard
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
date date format: 2017-11-30
userID integer
username string
jobID integer
taskTypeID integer
taskType string
taskID integer
startTime string range: 00:00:00 to 23:59:59
endTime string range: 00:00:00 to 23:59:59
hrs decimal hours between start_time and end_time, including break_hrs, ot, and dt; max 24
breakHrs decimal must fit within hrs
ot decimal must fit within hrs - break_hrs
dt decimal must fit within hrs - (break_hrs + ot)
locationID integer
location string
description string
customKeys dictionary {"Custom Key Name" : "Value"}
Return:
dictionary
Delete Timecard¶
Deletes an existing timecard
URL: http://hostname:portnumber/nimAPI.php?q=deleteTimecard
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
Return:
dictionary
Get Timecard Info¶
Retrieves information for an existing timecard
URL: http://hostname:portnumber/nimAPI.php?q=getTimecardInfo
Parameters Type Values Default Required
________________________________________________________________________________________________
timecardID integer YES
Return:
dictionary