Python

The Python API can be used to read information from the NIM, create new items, update existing items, and delete items. All request responses are received in the form of JavaScript Object Notation (JSON) formatted objects.

API Example

The following example displays how the NIM API can be used by render farm managers that support script integration. The python code below uses the NIM API to add a render, log elements, and upload a daily to a known task ID.

Example Request:

import nim_core.nim_api as nimAPI

result = nimAPI.add_render(taskID=14941, renderName='myRender')

if result['success'] == 'true':
   nimAPI.upload_renderIcon(renderID=result['ID'],img='/path/to/icon.jpeg')
   nimAPI.upload_reviewItem(renderID=result['ID'],path='/path/to/movie/myImages.mov',submit=0)
   nimAPI.add_element( parent='render', parentID=result['ID'], path='/path/to/frames', name='myImage.####.exr', \
                          startFrame=1, endFrame=128, handles=12, isPublished=False )
   nimAPI.add_element( parent='render', parentID=result['ID'], path='/path/to/frames', name='myImage_matte.####.exr', \
                          startFrame=1, endFrame=128, handles=12, isPublished=False )

Example Response:

{
    "success": true,
    "error": "",
    "ID": "1234"
}

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:

HTTP Headers

X-NIM-API-USER	The user’s NIM username
X-NIM-API-KEY	The user’s NIM 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.

Important

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.

In the Python API, the inclusion of the required headers is managed by the connect() function which handles communication to the VM through HTTP/HTTPS. By default, the connect() function reads the user’s NIM URL and username from the NIM preferences file and API key stored in the ~/.nim directory.

Note

The NIM API URL, username, and API key used for any request can be overrode using the nimURL, apiUser, and apiKey arguments respectively. Passing these values to the connect() function to authenticate the user will bypass the reading of the user’s NIM preferences. The functions in the python API provide arguments to pass the NIM URL, NIM username, and API key to the connect() function.

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

testAPI(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Used to test connectivity to the NIM API. Returns the current NIM version, API key validity, and whether API keys are required.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

version string	The current NIM version.
keyValid boolean	Indicates if the API key is valid. Possible values: true or false.
keyRequired boolean	Indicates if API keys are required. Possible values: true or false.
error string	Contains any error messages if keyValid is false. If keyValid is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import testAPI

response = testAPI()

if response["keyValid"]:
    print(f"NIM Version: {response['version']}, API Key Required: {response['keyRequired']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "version": "7.2.0.250224",
    "keyValid": False,
    "keyRequired": False,
    "error": ""
}

Get Connect Info

get_connect_info() → dict

Returns the connection information stored in preferences.

RETURN

nim_apiURL string	The URL to the NIM API.
nim_apiUser string	The NIM username of the person accessing the API.
nim_apiKey string	The NIM API key of the person accessing the API.

Example Usage:

from nim_core.nim_api import get_connect_info

response = get_connect_info()

if response:
    print(f"NIM API URL: {response['nim_apiURL']}, User: {response['nim_apiUser']}")
else:
    print("Failed to retrieve connection info")

Example Response:

{
    "nim_apiURL": "http://hostname:portnumber",
    "nim_apiUser": "username",
    "nim_apiKey": "api_key"
}

Get API Key

get_apiKey() → str

Retrieves the API key from the user’s ~/.nim/nim.key file.

Example Usage:

from nim_core.nim_api import get_apiKey

api_key = get_apiKey()
print(f"API Key: {api_key}")

Example Response:

"your_api_key"

Connect

connect(method: str = 'get', params: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Wrapper function used by Python API functions to connect to the NIM HTTP API endpoint.

ARGUMENTS

method string REQUIRED	Connection method. Valid values are get or post.
params dictionary REQUIRED	Dictionary containing the API query parameters. Please refer to the HTTP API documentation for a list of available queries and parameters. Example: params = {} params['q'] = 'getShots' params['showID'] = '100'
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

dict	A dictionary containing the response from the NIM Web API. The response will vary based on the query sent to the NIM API.

Example Usage:

from nim_core.nim_api import connect

params = {
    'q': 'testAPI'
}
response = connect(method='get', params=params)

if response["keyValid"]:
    print(f"API Version: {response['version']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "version": "2.5.15.161123",
    "keyValid": "false",
    "keyRequired": "false",
    "error": ""
}

Upload

upload(params: dict, nimURL: str = None, apiUser: str = None, apiKey: str = None) → bool

Wrapper function used by Python API commands that require a file to be uploaded to the NIM Web API.

ARGUMENTS

params dict REQUIRED	Dictionary containing the API query parameters. Please refer to the HTTP API documentation for a list of available queries and parameters. Example: params = {} params['q'] = 'uploadDailiesNote' params['dailiesID'] = '100' params['name'] = 'note name' params['file'] = open(imageFile, 'rb')
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean

Indicates whether the upload was successful. Possible values: True or False.

Example Usage:

from nim_core.nim_api import upload

params = {
    'q': 'uploadDailiesNote',
    'dailiesID': '100',
    'name': 'note name',
    'file': open('/path/to/image.jpg', 'rb')
}
success = upload(params=params)

if success:
    print("Upload successful")
else:
    print("Upload failed")

Example Response:

True

Get Application

get_app() → str

Returns the current host application name.

Example Usage:

from nim_core.nim_api import get_app

app_name = get_app()
print(f"Application Name: {app_name}")

Example Response:

"Host Application"

Get Culture Codes

get_cultureCodes(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves a list of currency codes used for setting the currency type of an item.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.
rows list	A list of dictionaries. Each dictionary includes: cultureCode : The culture code. currency : The currency name. currencyCode : The currency code.
totalRows integer	The total number of rows that match the search criteria.

Example Usage:

from nim_core.nim_api import get_cultureCodes

response = get_cultureCodes()

if response["success"]:
    for row in response["rows"]:
        print(f"Culture Code: {row['cultureCode']}, Currency: {row['currency']}, Currency Code: {row['currencyCode']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": "",
    "rows": [
        {
            "cultureCode": "en-US",
            "currency": "United States Dollar",
            "currencyCode": "USD"
        },
        {
            "cultureCode": "en-IE",
            "currency": "Euro (Ireland)",
            "currencyCode": "EUR"
        }
    ],
    "totalRows": 44
}

Users

Get User

get_user() → str

Retrieves the current user’s username.

Example Usage:

from nim_core.nim_api import get_user

username = get_user()
print(f"Username: {username}")

Example Response:

"john_doe"

Get User ID

get_userID(user: str, nimURL: str = None, apiUser: str = None, apiKey: str = None) → int

Retrieves the current user’s ID.

ARGUMENTS

user string REQUIRED	The username to retrieve the ID.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

integer

The ID of the user.

Example Usage:

from nim_core.nim_api import get_userID

user_id = get_userID(user="john_doe")
print(f"User ID: {user_id}")

Example Response:

1234

Get All Users

get_userList(nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns the full list of NIM Users.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The ID of the user. username : The username of the user. first_name : The first name of the user. last_name : The last name of the user. full_name : The full name of the user.

Example Usage:

from nim_core.nim_api import get_userList

response = get_userList()

if response["success"]:
    for user in response["data"]:
        print(f"User ID: {user['ID']}, Username: {user['username']}, Full Name: {user['full_name']}")
else:
    print(f"Error: {response['error']}")

Example Response:

[
    {
        "ID": 1,
        "username": "jdoe",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe"
    },
    {
        "ID": 2,
        "username": "asmith",
        "first_name": "Alice",
        "last_name": "Smith",
        "full_name": "Alice Smith"
    }
]

Get User Info

get_userInfo(ID: int = None, username: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

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 arguments needs to be provided.

ARGUMENTS

ID integer OPTIONAL	The ID of the user.
username string OPTIONAL	The username of the user.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The ID of the user. username : The username of the user. first_name : The first name of the user. last_name : The last name of the user. full_name : The full name of the user.

Example Usage:

from nim_core.nim_api import get_userInfo

user_info = get_userInfo(username="jdoe")
print(f"User Info: {user_info}")

Example Response:

[
    {
        "ID": 1,
        "username": "jdoe",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "email": "jdoe@example.com"
    }
]

Locations

Get All Locations

get_locations(nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves all defined locations.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The ID of the location. name : The name of the location. description : The description of the location.

Example Usage:

from nim_core.nim_api import get_locations

response = get_locations()

if response["success"]:
    for location in response["data"]:
        print(f"Location ID: {location['ID']}, Name: {location['name']}, Description: {location['description']}")
else:
    print(f"Error: {response['error']}")

Example Response:

[
    {
        "ID": 1,
        "name": "Los Angeles",
        "description": "Main Office"
    },
    {
        "ID": 2,
        "name": "New York",
        "description": "East Coast Office"
    }
]

Contacts

Get Contacts

get_contacts(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Get Contacts filtered by search parameters. Query will return all contacts the requesting user has access to.

Note

• This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.

• Arguments need to be passed as keyword arguments.

  Example: get_contacts(first_name=’John’, last_name=’Doe’)

ARGUMENTS

ID integer OPTIONAL	The ID of a contact item to query.
first_name string OPTIONAL	Will return all contact items matching the first name.
last_name string OPTIONAL	Will return all contact items matching the last name.
email string OPTIONAL	Will return all contact items matching the email.
title string OPTIONAL	Will return all contact items matching the title.
company string OPTIONAL	Will return all contact items matching the company name.
website string OPTIONAL	Will return all contact items matching the website.
work_phone string OPTIONAL	Will return all contact items matching the work phone number.
work_fax string OPTIONAL	Will return all contact items matching the work fax number.
mobile_phone string OPTIONAL	Will return all contact items matching the mobile phone number.
home_phone string OPTIONAL	Will return all contact items matching the home phone number.
address1 string OPTIONAL	Will return all contact items matching the address1 field.
address2 string OPTIONAL	Will return all contact items matching the address2 field.
city string OPTIONAL	Will return all contact items matching the city.
state string OPTIONAL	Will return all contact items matching the state.
zip string OPTIONAL	Will return all contact items matching the zip.
description string OPTIONAL	Will return all contact items partially matching the description.
keywords string OPTIONAL	A comma-separated list of keywords. Will return all contact items matching the keywords.
groups string OPTIONAL	A comma-separated list of groups. Will return all contact items matching the groups.
customKeys dict OPTIONAL	A dictionary of custom field names and values. Will return all contact items matching the custom field value.
limit integer OPTIONAL default: 0	Specifies the maximum number of rows to return. 0 = no limit
offset integer OPTIONAL default: 0	Specifies the number of rows to skip before starting to return rows. 0 = no offset
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data list	An list of returned data. Each object includes: ID : The unique identifier for the contact is_company : Indicates if the contact is a company (1) or an individual (0) userID : The user ID associated with the contact first_name : The first name of the contact last_name : The last name of the contact email : The email address of the contact title : The title of the contact company : The company name of the contact website : The website of the contact work_phone : The work phone number of the contact work_fax : The work fax number of the contact mobile_phone : The mobile phone number of the contact home_phone : The home phone number of the contact address1 : The first line of the contact’s address address2 : The second line of the contact’s address city : The city of the contact state : The state of the contact zip : The zip code of the contact description : The description of the contact contact_type : The type of contact keywords : The keywords associated with the contact groups : The groups associated with the contact linked_contacts : A list of linked contacts, each containing: ID : The unique identifier for the linked contact is_company : Indicates if the linked contact is a company (1) or an individual (0) first_name : The first name of the linked contact last_name : The last name of the linked contact company : The company name of the linked contact email : The email address of the linked contact customKeys : A list of custom keys, each containing: keyID : The unique identifier for the custom key keyName : The name of the custom key typeID : The type ID of the custom key value : The value of the custom key dropdownText : The dropdown text of the custom key linkText : The link text of the custom key priority : The priority of the custom key enabled : Indicates if the custom key is enabled (1) or disabled (0) editable : Indicates if the custom key is editable (1) or not (0) dropdownOptions : A list of dropdown options for the custom key, each containing: ID : The unique identifier for the dropdown option value : The value of the dropdown option enabled : Indicates if the dropdown option is enabled (1) or disabled (0)

Example Usage:

from nim_core.nim_api import get_contacts

response = get_contacts(first_name='John', last_name='Doe')

if response["success"]:
    for contact in response["data"]:
        print(f"Contact ID: {contact['ID']}, Name: {contact['first_name']} {contact['last_name']}, Email: {contact['email']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "total_count": 1,
    "data": [
        {
            "ID": 1,
            "is_company": 1,
            "userID": 0,
            "first_name": "John",
            "last_name": "Smith",
            "email": "john.smith@example.com",
            "title": "Manager",
            "company": "Example Corp",
            "website": "www.example.com",
            "work_phone": "123-456-7890",
            "work_fax": "123-456-7891",
            "mobile_phone": "123-456-7892",
            "home_phone": "123-456-7893",
            "address1": "123 Main St",
            "address2": "Suite 100",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345",
            "description": "A sample contact",
            "contact_type": "staff",
            "keywords": "API, Python",
            "groups": "API Test",
            "linked_contacts": [
                {
                    "ID": 2,
                    "is_company": 0,
                    "first_name": "Jane",
                    "last_name": "Doe",
                    "company": "Example Corp",
                    "email": "jane.doe@example.com"
                },
                {
                    "ID": 3,
                    "is_company": 1,
                    "first_name": "",
                    "last_name": null,
                    "company": "Example Corp",
                    "email": null
                }
            ],
            "customKeys": [
                {
                    "keyID": 1,
                    "keyName": "Contact Single Line",
                    "typeID": 1,
                    "value": "Custom Text",
                    "dropdownText": "",
                    "linkText": "",
                    "priority": 1,
                    "enabled": 1,
                    "editable": 1
                },
                {
                    "keyID": 2,
                    "keyName": "Contact Dropdown",
                    "typeID": 3,
                    "value": "",
                    "dropdownText": "",
                    "linkText": "",
                    "priority": 1,
                    "enabled": 1,
                    "editable": 1,
                    "dropdownOptions": [
                        {
                            "ID": 1,
                            "value": "1 Contact",
                            "enabled": 1
                        },
                        {
                            "ID": 2,
                            "value": "2 Contact",
                            "enabled": 1
                        },
                        {
                            "ID": 3,
                            "value": "3 Contact",
                            "enabled": 1
                        }
                    ]
                }
            ]
        }
    ]
}

Add Contact

add_contact(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Creates a new contact in NIM.

Note

Arguments need to be passed as keyword arguments.

Example: add_contact(first_name=’John’, last_name=’Doe’)

ARGUMENTS

is_company boolean OPTIONAL default: 0	Indicates if the contact is a company. 0 = No 1 = Yes
first_name string OPTIONAL	The first name of the contact.
last_name string OPTIONAL	The last name of the contact.
email string OPTIONAL	The email address of the contact.
title string OPTIONAL	The title of the contact.
company string OPTIONAL	The company name of the contact.
website string OPTIONAL	The website of the contact.
work_phone string OPTIONAL	The work phone number of the contact.
work_fax string OPTIONAL	The work fax number of the contact.
mobile_phone string OPTIONAL	The mobile phone number of the contact.
home_phone string OPTIONAL	The home phone number of the contact.
address1 string OPTIONAL	The first address line of the contact.
address2 string OPTIONAL	The second address line of the contact.
city string OPTIONAL	The city of the contact.
state string OPTIONAL	The state of the contact.
zip string OPTIONAL	The zip code of the contact.
description string OPTIONAL	The description of the contact.
keywords string OPTIONAL	A comma-separated list of keywords associated with the contact. Format: [“keyword1”,”keyword2”]
groups string OPTIONAL	A comma-separated list of groups associated with the contact. Format: [“group1”,”group2”]
contact_link_IDs string OPTIONAL	A comma-separated list of contact IDs to link to this contact. Format: 1,2,3 Including this argument will set all linked contacts for this contact.
customKeys dict OPTIONAL	A dictionary of custom field names and values.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the newly created item.

Example Usage:

from nim_core.nim_api import add_contact

response = add_contact(first_name='John', last_name='Doe')

if response["success"]:
    print(f"Contact created with ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": "",
    "ID": 1234
}

Update A Contact

update_contact(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Update an existing contact by ID.

Note

• If an optional field is not passed, the value for that field will remain unchanged.

• Arguments need to be passed as keyword arguments.

  Example: update_contact(ID=1, first_name=’John’, last_name=’Doe’)

ARGUMENTS

ID integer REQUIRED	The ID of the contact to update.
first_name string OPTIONAL	The first name of the contact.
last_name string OPTIONAL	The last name of the contact.
email string OPTIONAL	The email address of the contact.
title string OPTIONAL	The title of the contact.
company string OPTIONAL	The company name of the contact.
website string OPTIONAL	The website of the contact.
work_phone string OPTIONAL	The work phone number of the contact.
work_fax string OPTIONAL	The work fax number of the contact.
mobile_phone string OPTIONAL	The mobile phone number of the contact.
home_phone string OPTIONAL	The home phone number of the contact.
address1 string OPTIONAL	The first address line of the contact.
address2 string OPTIONAL	The second address line of the contact.
city string OPTIONAL	The city of the contact.
state string OPTIONAL	The state of the contact.
zip string OPTIONAL	The zip code of the contact.
description string OPTIONAL	The description of the contact.
keywords string OPTIONAL	A comma-separated list of keywords associated with the contact.
groups string OPTIONAL	A comma-separated list of groups associated with the contact.
contact_link_IDs string OPTIONAL	A comma-separated list of contact IDs to link to this contact.
customKeys dict OPTIONAL	A dictionary of custom field names and values.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the updated item.

Example Usage:

from nim_core.nim_api import update_contact

response = update_contact(ID=1, first_name='John', last_name='Doe')

if response["success"]:
    print(f"Contact updated with ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": "",
    "ID": 1
}

Delete A Contact

delete_contact(ID: int, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Delete an existing contact by ID.

ARGUMENTS

ID integer REQUIRED	The ID of the contact to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_contact

response = delete_contact(ID=1)

if response["success"]:
    print("Contact deleted successfully")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Schedule Events

Get Schedule Events

get_scheduleEvents(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Get Schedule Events filtered by search parameters.

Note

• This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.

• Arguments need to be passed as keyword arguments.

  Example: get_scheduleEvents(statusName=’BOOKED’, userIDs=1)

ARGUMENTS

ID integer OPTIONAL	The ID of a schedule event to query.
title string OPTIONAL	Will return all schedule events matching the title.
description string OPTIONAL	Will return all schedule events partially matching the description.
statusName string OPTIONAL	Will return all schedule events matching the statusName.
locationName string OPTIONAL	Will return all schedule events matching the locationName.
jobName string OPTIONAL	Will return all schedule events matching the jobName.
jobNumber string OPTIONAL	Will return all schedule events matching the jobNumber.
userIDs string OPTIONAL	Will return all schedule events matching the userIDs. Format: A comma separated list of IDs.
users string OPTIONAL	Will return all schedule events matching the users. Format: A comma separated list of names.
resourceIDs string OPTIONAL	Will return all schedule events matching the resourceIDs Format: A comma separated list of IDs.
resources string OPTIONAL	Will return all schedule events matching the resources. Format: A comma separated list of names.
start datetime OPTIONAL	Will return all schedule events matching the start. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
end datetime OPTIONAL	Will return all schedule events matching the end. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
startRange datetime OPTIONAL	Will return all schedule events (and event recurrences) AFTER the startRange. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
endRange datetime OPTIONAL	Will return all schedule events (and event recurrences) BEFORE the endRange. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
startTimezone string OPTIONAL	Will return all schedule events matching the startTimezone.
endTimezone string OPTIONAL	Will return all schedule events matching the endTimezone.
isAllDay boolean OPTIONAL	Will return all schedule events matching the isAllDay setting. 0 = not an all-day event 1 = an all-day event
recurrenceId integer OPTIONAL	Will return all schedule events matching the recurrenceId.
recurrenceRule string OPTIONAL	Will return all schedule events matching the recurrenceRule.
recurrenceException string OPTIONAL	Will return all schedule events matching the recurrenceException.
userUtilizationTypeID integer OPTIONAL	Will return all schedule events matching the userUtilizationTypeID.
userUtilizationType string OPTIONAL	Will return all schedule events matching the userUtilizationType.
userUtilizationValue string OPTIONAL	Will return all schedule events matching the userUtilizationValue.
resourceUtilizationTypeID integer OPTIONAL	Will return all schedule events matching the resourceUtilizationTypeID.
resourceUtilizationType string OPTIONAL	Will return all schedule events matching the resourceUtilizationType.
resourceUtilizationValue string OPTIONAL	Will return all schedule events matching the resourceUtilizationValue.
limit integer OPTIONAL default: 0	Specifies the maximum number of rows to return. 0 = no limit.
offset integer OPTIONAL default: 0	Specifies the number of rows to skip before starting to return rows.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data list	A list of returned data. Each object includes: ID : The unique identifier for the schedule event title : The title of the schedule event start : The start datetime of the schedule event end : The end datetime of the schedule event startTimezone : The start timezone of the schedule event endTimezone : The end timezone of the schedule event description : The description of the schedule event recurrenceId : The recurrence ID of the schedule event recurrenceRule : The recurrence rule of the schedule event recurrenceException : The recurrence exception of the schedule event isAllDay : Indicates if the schedule event is an all-day event (1) or not (0) status : An object containing the status ID and name of the schedule event location : An object containing the location ID and name of the schedule event job : An object containing the job ID, number, and name associated with the schedule event users : A list of objects, each containing the user ID and name associated with the schedule event resources : A list of objects, each containing the resource ID and name associated with the schedule event userUtilization : An object containing the user utilization type ID, type, and value associated with the schedule event resourceUtilization : An object containing the resource utilization type ID, type, and value associated with the schedule event startUtc : The start datetime of the schedule event in UTC endUtc : The end datetime of the schedule event in UTC recurrences : A list of objects, each containing the start and end datetimes of the recurrences of the schedule event

Example Usage:

from nim_core.nim_api import get_scheduleEvents

response = get_scheduleEvents()

if response["success"]:
    for event in response["data"]:
        print(f"Event ID: {event['ID']}, Title: {event['title']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "total_count": 12,
    "data": [
        {
            "ID": 3394,
            "title": "MyEvent",
            "start": "2024-07-08",
            "end": "2024-07-12",
            "startTimezone": "America/Los_Angeles",
            "endTimezone": "America/Los_Angeles",
            "description": "Event description",
            "recurrenceId": "",
            "recurrenceRule": "FREQ=WEEKLY;COUNT=3;BYDAY=MO;WKST=SU;",
            "recurrenceException": "20240722T070000Z",
            "isAllDay": "true",
            "status": {
                "ID": 6,
                "name": "2nd Hold"
            },
            "location": {
                "ID": 3,
                "name": "London"
            },
            "job": {
                "ID": 5025,
                "number": "24013",
                "name": "Example Job"
            },
            "users": [
                {
                    "ID": "309",
                    "name": "John Doe"
                },
                {
                    "ID": "75",
                    "name": "Jane Smith"
                }
            ],
            "resources": [],
            "userUtilization": {
                "typeID": 1,
                "type": "hours per day",
                "value": "8.00"
            },
            "resourceUtilization": {
                "typeID": 1,
                "type": "units per day",
                "value": "1.00"
            },
            "startUtc": "2024-07-08T00:00:00Z",
            "endUtc": "2024-07-12T00:00:00Z",
            "recurrences": [
                {
                    "start": "2024-07-08",
                    "end": "2024-07-12",
                    "startUtc": "2024-07-08T00:00:00Z",
                    "endUtc": "2024-07-12T00:00:00Z"
                },
                {
                    "start": "2024-07-15",
                    "end": "2024-07-19",
                    "startUtc": "2024-07-15T00:00:00Z",
                    "endUtc": "2024-07-19T00:00:00Z"
                },
                {
                    "start": "2024-07-22",
                    "end": "2024-07-26",
                    "startUtc": "2024-07-22T00:00:00Z",
                    "endUtc": "2024-07-26T00:00:00Z"
                }
            ]
        }
    ]
}

Add Schedule Event

add_scheduleEvent(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Creates a new event on the schedule.

Note

Arguments need to be passed as keyword arguments.

ARGUMENTS

start datetime REQUIRED	The start datetime of the event. Date if isAllDay = 1; datetime otherwise. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
end datetime REQUIRED	The end datetime of the event. Date if isAllDay = 1; datetime otherwise. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
jobID integer OPTIONAL	A job ID to associate with the event. Required if userIDs and resourceIDs are not provided.
userIDs string OPTIONAL	A comma-separated list of user IDs. Required if jobID and resourceIDs are not provided.
resourceIDs string OPTIONAL	A comma-separated list of resource IDs. Required if jobID and userIDs are not provided.
title string OPTIONAL	The title of the event.
description string OPTIONAL	The description of the event.
statusID integer OPTIONAL	The ID of the status to associate with the event.
statusName string OPTIONAL	The name of the status to associate with the event.
locationID integer OPTIONAL	The ID of the location to associate with the event.
startTimezone string OPTIONAL	A valid timezone identifier. Example: America/Los_Angeles
endTimezone string OPTIONAL	A valid timezone identifier. Example: America/Los_Angeles
isAllDay boolean OPTIONAL	Indicates if the event is an all-day event. Possible values: 0 or 1.
recurrenceId integer OPTIONAL	ID of this schedule event’s parent. This should only exist if this event is an EXCEPTION to a recurring event’s ruleset.
recurrenceRule string OPTIONAL	Recurring event ruleset string. For more information on rulesets, see https://datatracker.ietf.org/doc/html/rfc5545.
recurrenceException string OPTIONAL	A list of comma-separated start datetimes for all exceptions to this recurring event’s rules.
userUtilizationTypeID integer OPTIONAL	The ID of the user utilization type to associate with the event.
userUtilizationType string OPTIONAL	The name of the user utilization type to associate with the event. Possible values are: hours per day, percent per day, total hours.
userUtilizationValue string OPTIONAL	The value of the user utilization type to associate with the event.
resourceUtilizationTypeID integer OPTIONAL	The ID of the resource utilization type to associate with the event.
resourceUtilizationType string OPTIONAL	The name of the resource utilization type to associate with the event. Possible values are: units per day or percent per day.
resourceUtilizationValue string OPTIONAL	The value of the resource utilization type to associate with the event.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the newly created item.

Example Usage:

from nim_core.nim_api import add_scheduleEvent

response = add_scheduleEvent(
    title="MyEvent",
    start="2024-07-10T07:00:00.000Z",
    end="2024-07-10T08:00:00.000Z",
    jobID=1,
    userIDs="1,2,3",
    resourceIDs="1,2,3"
)

if response["success"]:
    print(f"Newly created event ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "ID": 1234
}

Update Schedule Event

update_scheduleEvent(nimURL: str = None, apiUser: str = None, apiKey: str = None, **kwargs) → dict

Updates an existing schedule event by ID.

Note

Arguments need to be passed as keyword arguments.

ARGUMENTS

ID integer REQUIRED	The ID of the schedule event to update.
title string OPTIONAL	The title of the event.
description string OPTIONAL	The description of the event.
statusID integer OPTIONAL	The ID of the status to associate with the event.
statusName string OPTIONAL	The name of the status to associate with the event.
locationID integer OPTIONAL	The ID of the location to associate with the event.
jobID integer OPTIONAL	The ID of the job to associate with the event.
userIDs string OPTIONAL	A comma-separated list of user IDs.
resourceIDs string OPTIONAL	A comma-separated list of resource IDs.
start datetime OPTIONAL	The start datetime of the event. Date if isAllDay = 1; datetime otherwise. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
end datetime OPTIONAL	The end datetime of the event. Date if isAllDay = 1; datetime otherwise. Format: yyyy-mm-ddThh:mm:ss.sssZ or yyyy-mm-dd hh:mm:ss.sss timezone
startTimezone string OPTIONAL	A valid timezone identifier. Example: America/Los_Angeles
endTimezone string OPTIONAL	A valid timezone identifier. Example: America/Los_Angeles
isAllDay boolean OPTIONAL	Indicates if the event is an all-day event. Possible values: 0 or 1.
recurrenceId integer OPTIONAL	ID of this schedule event’s parent; this should only exist if this event is an EXCEPTION to a recurring event’s ruleset.
recurrenceRule string OPTIONAL	Recurring event ruleset string. For more information on rulesets, see https://datatracker.ietf.org/doc/html/rfc5545.
recurrenceException string OPTIONAL	A list of comma-separated start datetimes for all exceptions to this recurring event’s rules.
userUtilizationTypeID integer OPTIONAL	The ID of the user utilization type to associate with the event.
userUtilizationType string OPTIONAL	The name of the user utilization type to associate with the event. Possible values are: hours per day, percent per day, total hours
userUtilizationValue string OPTIONAL	The value of the user utilization type to associate with the event.
resourceUtilizationTypeID integer OPTIONAL	The ID of the resource utilization type to associate with the event.
resourceUtilizationType string OPTIONAL	The name of the resource utilization type to associate with the event. Possible values are: units per day or percent per day
resourceUtilizationValue string OPTIONAL	The value of the resource utilization type to associate with the event.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the updated item

Example Usage:

from nim_core.nim_api import update_scheduleEvent

response = update_scheduleEvent(ID=8963, title="MyEvent")

if response["success"]:
    print(f"Updated event ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "ID": 1234
}

Delete A Schedule Event

delete_scheduleEvent(ID: int, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an existing event from the schedule.

ARGUMENTS

ID integer REQUIRED	The ID of the schedule event to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_scheduleEvent

response = delete_scheduleEvent(ID=8978)

if response["success"]:
    print("Schedule event deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Get Schedule Event Statuses

get_scheduleEventStatuses(nimURL=None, apiUser=None, apiKey=None) → dict

Get all schedule event statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of dictionaries. Each dictionary includes: status : The name of the schedule event status priority : The priority of the schedule event status color : The color associated with the schedule event status lower_capacity : Indicates if the status lowers capacity 1 = lowers capacity 0 = does not lower capacity

Example Usage:

from nim_core.nim_api import get_scheduleEventStatuses

response = get_scheduleEventStatuses()

if response["success"]:
    for status_info in response["data"]:
        print(f"Status: {status_info['status']}, Color: {status_info['color']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "status": "Booked",
            "priority": 0,
            "color": "#40633b",
            "lower_capacity": 0
        },
        {
            "status": "Available",
            "priority": 1,
            "color": "#d76c01",
            "lower_capacity": 0
        },
        {
            "status": "Unavailable",
            "priority": 2,
            "color": "#89081d",
            "lower_capacity": 1
        }
    ]
}

Resources

Get Resources

get_resources(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Get Resources filtered by search parameters. The query will return all resources the requesting user has access to.

Note

• This query can return a large amount of data. Use the limit and offset parameters in conjunction with the total_count value to paginate your results.

• Arguments need to be passed as keyword arguments.

  Example: get_resources(name=”Software License”)

ARGUMENTS

ID integer OPTIONAL	The ID of a resource to query.
name string OPTIONAL	Will return all resources matching the name.
description string OPTIONAL	Will return all resources partially matching the description.
color string OPTIONAL	Will return all resources matching the color.
locationID integer OPTIONAL	Will return all resources matching the location ID.
locationName string OPTIONAL	Will return all resources matching the locationName.
keywordIDs string OPTIONAL	Will return all resources matching the keywordIDs. Format: A comma separated list of IDs.
keywords string OPTIONAL	Will return all resources matching the keywords. Format: A comma separated list of names.
resourceGroupIDs string OPTIONAL	Will return all resources matching the resourceGroupIDs. Format: A comma separated list of IDs.
resourceGroups string OPTIONAL	Will return all resources matching the resourceGroups. Format: A comma separated list of names.
limit integer OPTIONAL default: 0	Specifies the maximum number of rows to return. 0 = no limit.
offset integer OPTIONAL default: 0	Specifies the number of rows to skip before starting to return rows.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the resource name : The name of the resource description : The description of the resource color : The color of the resource location : An object containing the location ID and name of the resource keywords : A list of objects, each containing the keyword ID and name associated with the resource resourceGroups : A list of objects, each containing the resource group ID and name associated with the resource

Example Usage:

from nim_core.nim_api import get_resources

response = get_resources(name="Houdini License")

if response["success"]:
    for resource in response["data"]:
        print(f"Resource ID: {resource['ID']}, Name: {resource['name']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "total_count": 42,
    "data": [
        {
            "ID": 54,
            "name": "Software License",
            "description": "All available software licenses.",
            "color": "#b840d6",
            "location": {
                "ID": 1,
                "name": "Los Angeles"
            },
            "keywords": [
                {
                    "ID": "9",
                    "keyword": "Software"
                }
            ],
            "resourceGroups": [
                {
                    "ID": "1",
                    "name": "Licenses"
                }
            ]
        }
    ]
}

Add A Resource

add_resource(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Creates a new resource.

Note

Arguments need to be passed as keyword arguments.

Example: add_resource(name=”Software License”, locationID=1)

ARGUMENTS

name string REQUIRED	The resource name.
description string OPTIONAL	The resource description.
color string OPTIONAL	The resource color.
locationID integer OPTIONAL	The location ID to associate with the resource.
keywords string OPTIONAL	A comma-separated list of keywords.
keywordIDs string OPTIONAL	A comma-separated list of keyword IDs.
resourceGroups string OPTIONAL	A comma-separated list of resource groups.
resourceGroupIDs string OPTIONAL	A comma-separated list of resource group IDs.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the newly created item.

Example Usage:

from nim_core.nim_api import add_resource

response = add_resource(name="NewResource")

if response["success"]:
    print(f"New resource ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 62,
    "success": true,
    "error": ""
}

Update A Resource

update_resource(nimURL=None, apiUser=None, apiKey=None, **kwargs)

Updates an existing resource based on the resource ID.

Note

Arguments need to be passed as keyword arguments.

Example: update_resource(ID=1, name=”Updated Resource”)

ARGUMENTS

ID integer REQUIRED	The ID of the resource to update.
name string OPTIONAL	The resource name.
description string OPTIONAL	The resource description.
color string OPTIONAL	The resource color.
locationID integer OPTIONAL	The location ID to associate with the resource.
keywords string OPTIONAL	A comma-separated list of keywords.
keywordIDs string OPTIONAL	A comma-separated list of keyword IDs.
resourceGroups string OPTIONAL	A comma-separated list of resource groups.
resourceGroupIDs string OPTIONAL	A comma-separated list of resource group IDs.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the updated item.

Example Usage:

from nim_core.nim_api import update_resource

response = update_resource(ID=62, name="UpdatedResource")

if response["success"]:
    print(f"Resource ID {response['ID']} updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 62,
    "success": true,
    "error": ""
}

Delete A Resource

delete_resource(ID=None, nimURL=None, apiUser=None, apiKey=None) → dict

Deletes an existing resource based on the resource ID.

ARGUMENTS

ID integer REQUIRED	The ID of the resource to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_resource

response = delete_resource(ID=8978)

if response["success"]:
    print("Resource deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Jobs

Get User Jobs

get_jobs(userID=None, nimURL=None, apiUser=None, apiKey=None) → dict

Retrieves all jobs the user is assigned to.

ARGUMENTS

userID integer REQUIRED	The user ID to retrieve jobs.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the job number : The job number jobname : The name of the job folder : The folder associated with the job description : The description of the job job_icon : The path to the job icon

Example Usage:

from nim_core.nim_api import get_jobs

response = get_jobs(userID=123)

if response.get("success"):
    for job in response["data"]:
        print(f"Job ID: {job['ID']}, Number: {job['number']}")
else:
    print(f"Error: {response.get('error')}")

Example Response:

[
    {
        "ID": 5085,
        "number": "25004",
        "jobname": "Example Job",
        "folder": "25004_Example Job",
        "description": null,
        "job_icon": "/media/jobs/5085/icon/example_icon.jpg"
    }
]

Get Crew

get_crew(jobID=None, getData=None, limit=None, offset=None, nimURL=None, apiUser=None, apiKey=None) → dict

Returns a list of users for the crew of the corresponding job(s).

Note

This query can return a large amount of data. Use the limit and offset arguments in conjunction with the total_count value to paginate your results.

ARGUMENTS

jobID string REQUIRED	A single ID or comma-separated list of job IDs.
getData integer OPTIONAL default: 0	Specifies whether to return full data for items. 0 = returns only userIDs 1 = returns full user data
limit integer OPTIONAL default: 0	Specifies the maximum number of rows to return. 0 = no limit
offset integer OPTIONAL default: 0	Specifies the number of rows to skip before starting to return rows.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data dictionary	An dictionary where each key is a job ID and the value is a list of crew members. Each crew member dictionary includes: user_id : The unique identifier for the user first_name : The first name of the user last_name : The last name of the user email : The email address of the user

Example Usage:

from nim_core.nim_api import get_crew

response = get_crew(jobID="4557,4561")

if response["success"]:
    crew_data = response.get("data", {})
    for job_id, job_info in crew_data.items():
        print(f"Job ID: {job_id}")
        for member in job_info["crew"]:
            print(f"   {member['first_name']} {member['last_name']} ({member['email']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "total_count": 24,
    "data": {
        "4557": {
            "crew": [
                {
                    "user_id": 1,
                    "first_name": "John",
                    "last_name": "Doe",
                    "email": "john.doe@example.com"
                },
                {
                    "user_id": 2,
                    "first_name": "Jane",
                    "last_name": "Smith",
                    "email": "jane.smith@example.com"
                }
            ]
        },
        "4561": {
            "crew": [
                {
                    "user_id": 3,
                    "first_name": "Alice",
                    "last_name": "Johnson",
                    "email": "alice.johnson@example.com"
                },
                {
                    "user_id": 4,
                    "first_name": "Bob",
                    "last_name": "Brown",
                    "email": "bob.brown@example.com"
                }
            ]
        }
    }
}

Add Job

add_job(name=None, number=None, numberTemplate=None, description=None, client_details=None, agency=None, producer=None, agency_producer=None, phone=None, email=None, prod_co=None, prod_director=None, prod_contact=None, prod_phone=None, prod_email=None, prod_shoot_date=None, prod_location=None, prod_supervised=None, editorial=None, editor=None, grading=None, colorist=None, music=None, mix=None, sound=None, creative_lead=None, projectStatus=None, folder=None, projectStructureID=None, projectStructure=None, jobStatusID=None, jobStatus=None, biddingLocationID=None, biddingLocation=None, assignedLocationID=None, assignedLocation=None, startDate=None, endDate=None, currency=None, cultureID=None, customKeys=None, contactIDs=None, nimURL=None, apiUser=None, apiKey=None) → dict

Creates a new job.

Note

If no default job number template is included, either number or numberTemplate must be included.

ARGUMENTS

name string REQUIRED	The name of the job.
number string OPTIONAL	The job number.
numberTemplate string OPTIONAL	The job number template.
description string OPTIONAL	The description of the job.
client_details string OPTIONAL	The client details for the job.
agency string OPTIONAL	The agency associated with the job.
producer string OPTIONAL	The producer of the job.
agency_producer string OPTIONAL	The agency producer of the job.
phone string OPTIONAL	The phone number associated with the job.
email string OPTIONAL	The email address associated with the job.
prod_co string OPTIONAL	The production company associated with the job.
prod_director string OPTIONAL	The production director of the job.
prod_contact string OPTIONAL	The production contact for the job.
prod_phone string OPTIONAL	The production phone number.
prod_email string OPTIONAL	The production email address.
prod_shoot_date date OPTIONAL	The production shoot date. Format: YYYY-mm-dd
prod_location string OPTIONAL	The production location.
prod_supervised boolean OPTIONAL default: 0	Indicates if the production is supervised. 0 = No 1 = Yes
editorial string OPTIONAL	The editorial information.
editor string OPTIONAL	The editor of the job.
grading string OPTIONAL	The grading information.
colorist string OPTIONAL	The colorist of the job.
music string OPTIONAL	The music information.
mix string OPTIONAL	The mix information.
sound string OPTIONAL	The sound information.
creative_lead string OPTIONAL	The creative lead for the job.
projectStatus string OPTIONAL default: ACTIVE	The project status. Possible values: ACTIVE or INACTIVE Providing a projectStatus will override any job status associated activity status.
folder string OPTIONAL	The folder associated with the job.
projectStructureID integer OPTIONAL	The project structure ID.
projectStructure string OPTIONAL	The project structure.
jobStatusID integer OPTIONAL	The job status ID.
jobStatus string OPTIONAL	The job status.
biddingLocationID integer OPTIONAL	The bidding location ID.
biddingLocation string OPTIONAL	The bidding location.
assignedLocationID integer OPTIONAL	The assigned location ID.
assignedLocation string OPTIONAL	The assigned location.
start_date date OPTIONAL	The start date of the job. Format: YYYY-mm-dd
end_date date OPTIONAL	The end date of the job. Format: YYYY-mm-dd
cultureID integer OPTIONAL	The ID of the currency culture to use for the job.
keywords list OPTIONAL	A list of keywords. Format: [“keyword1”,”keyword2”]
contactIDs string OPTIONAL	A comma-separated list of contact IDs to link to the job. Example: 1,2,3
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the newly created item.

Example Usage:

from nim_core.nim_api import add_job

response = add_job(name="NewJob")

if response["success"]:
    print(f"Newly created job ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 5086,
    "success": true,
    "error": ""
}

Update Job

update_job(jobID=None, name=None, number=None, description=None, client_details=None, agency=None, producer=None, agency_producer=None, phone=None, email=None, prod_co=None, prod_director=None, prod_contact=None, prod_phone=None, prod_email=None, prod_shoot_date=None, prod_location=None, prod_supervised=None, editorial=None, editor=None, grading=None, colorist=None, music=None, mix=None, sound=None, creative_lead=None, projectStatus=None, folder=None, projectStructureID=None, projectStructure=None, jobStatusID=None, jobStatus=None, biddingLocationID=None, biddingLocation=None, assignedLocationID=None, assignedLocation=None, startDate=None, endDate=None, currency=None, cultureID=None, customKeys=None, contactIDs=None, nimURL=None, apiUser=None, apiKey=None) → dict

Updates an existing job based on the jobID.

Note

The following values will only be updated if the job is offline:

• folder

• projectStructureID

• projectStructure

ARGUMENTS

jobID integer REQUIRED	The ID of the job to update.
name string OPTIONAL	The name of the job.
number string OPTIONAL	The job number.
description string OPTIONAL	The description of the job.
client_details string OPTIONAL	The client details for the job.
agency string OPTIONAL	The agency associated with the job.
producer string OPTIONAL	The producer of the job.
agency_producer string OPTIONAL	The agency producer of the job.
phone string OPTIONAL	The phone number associated with the job.
email string OPTIONAL	The email address associated with the job.
prod_co string OPTIONAL	The production company associated with the job.
prod_director string OPTIONAL	The production director of the job.
prod_contact string OPTIONAL	The production contact for the job.
prod_phone string OPTIONAL	The production phone number.
prod_email string OPTIONAL	The production email address.
prod_shoot_date date OPTIONAL	The production shoot date. Format: YYYY-mm-dd
prod_location string OPTIONAL	The production location.
prod_supervised boolean OPTIONAL default: 0	Indicates if the production is supervised. Possible values: 0 or 1.
editorial string OPTIONAL	The editorial information.
editor string OPTIONAL	The editor of the job.
grading string OPTIONAL	The grading information.
colorist string OPTIONAL	The colorist of the job.
music string OPTIONAL	The music information.
mix string OPTIONAL	The mix information.
sound string OPTIONAL	The sound information.
creative_lead string OPTIONAL	The creative lead for the job.
projectStatus string OPTIONAL default: ACTIVE	The project status. Possible values: ACTIVE or INACTIVE. Providing a projectStatus will override any job status associated activity status.
folder string OPTIONAL	The folder associated with the job.
projectStructureID integer OPTIONAL	The project structure ID.
projectStructure string OPTIONAL	The project structure.
jobStatusID integer OPTIONAL	The job status ID. Including the job status ID will set the project status based on the associated activity status.
jobStatus string OPTIONAL	The job status. Including the job status will set the project status based on the associated activity status.
biddingLocationID integer OPTIONAL	The bidding location ID.
biddingLocation string OPTIONAL	The bidding location.
assignedLocationID integer OPTIONAL	The assigned location ID.
assignedLocation string OPTIONAL	The assigned location.
startDate date OPTIONAL	The start date of the job. Format: YYYY-mm-dd
endDate date OPTIONAL	The end date of the job. Format: YYYY-mm-dd
cultureID integer OPTIONAL	The ID of the currency culture to use for the job.
keywords list OPTIONAL	A list of keywords. Format: [“keyword1”,”keyword2”]
contactIDs string OPTIONAL	A comma-separated list of contact IDs to link to the job. Example: 1,2,3
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the updated item.

Example Usage:

from nim_core.nim_api import update_job

response = update_job(jobID=5086, name="UpdatedJob")

if response["success"]:
    print(f"Updated job ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 5086,
    "success": true,
    "error": ""
}

Delete Job

delete_job(jobID=None, nimURL=None, apiUser=None, apiKey=None) → dict

Deletes a job based on jobID.

Note

This is a soft delete and these jobs can be recovered or permanently deleted from the UI in the Admin > Jobs > Deleted menu.

ARGUMENTS

jobID integer REQUIRED	The ID of the job to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_job

response = delete_job(jobID=8978)

if response["success"]:
    print("Job deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Upload Job Icon

upload_jobIcon(jobID=None, img=None, nimURL=None, apiUser=None, apiKey=None) → dict

Uploads a new job icon for a specified job ID.

ARGUMENTS

jobID integer REQUIRED	The ID of the job to upload the icon for.
img string OPTIONAL	The local file path to the image that will be uploaded as the job icon.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
iconPath string	If successful, the path to the uploaded media will be returned.

Example Usage:

from nim_core.nim_api import upload_jobIcon

response = upload_jobIcon(jobID=1234, img="/path/to/icon.jpg")

if response["success"]:
    print(f"Icon uploaded successfully! Path: {response['iconPath']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "iconPath": "media/jobs/5088/icon/c02ea16c.jpg"
}

Get Job Info

get_jobInfo(jobID=None, nimURL=None, apiUser=None, apiKey=None) → dict

Retrieves job information for a specified job ID.

Note

Returns limited data if the user does not have permission to view job details.

ARGUMENTS

jobID integer REQUIRED	The ID of the job to retrieve information for.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data object	An object containing the job information.

Example Usage:

from nim_core.nim_api import get_jobInfo

response = get_jobInfo(jobID=5025)

if response["success"]:
    job_data = response.get("data", {})
    print(f"Job Name: {job_data.get('jobname')}")
    print(f"Job Description: {job_data.get('description')}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": {
        "ID": 5025,
        "number": "24013",
        "jobname": "New Job",
        "description": null,
        "bgcolor": "#fcb3ff",
        "textcolor": "#FFFFFF",
        "start_date": "2024-04-19",
        "end_date": "2024-07-30",
        "jobStatusID": 4,
        "jobStatus": "IN PROGRESS",
        "job_status_bgcolor": "#539a87",
        "job_status_textcolor": "#070707",
        "folder": "24013_New Job",
        "client_details": "John Doe Details",
        "biddingLocationID": 1,
        "biddingLocation": "Los Angeles",
        "assignedLocationID": 1,
        "assignedLocation": "Los Angeles",
        "keywordIDs": null,
        "keywords": null,
        "currency": "USD",
        "is_private": 0,
        "is_deleted": 0,
        "agency": "",
        "agency_producer": "",
        "agency_phone": "",
        "agency_email": "",
        "prodco": "",
        "director": "",
        "prod_contact": "",
        "prod_phone": "",
        "prod_email": "",
        "post_producer": "",
        "post_lead": "",
        "telecine": "",
        "colorist": "",
        "editorial": "",
        "editor": "",
        "mix": "",
        "music": "",
        "sounddesign": "",
        "shoot_date": null,
        "shoot_location": "",
        "shoot_sup": 0,
        "proj_status": "ONLINE",
        "activityStatus": "ACTIVE",
        "projectStructureID": 19,
        "structure_created": 1,
        "securityGroupIDs": null,
        "securityGroups": null,
        "client_contacts": [
            {
                "ID": 55,
                "is_company": 0,
                "first_name": "John",
                "last_name": "Doe",
                "company": "Example Company",
                "email": "john.doe@example.com"
            },
            {
                "ID": 79,
                "is_company": 0,
                "first_name": "Jane",
                "last_name": "Doe",
                "company": "Example Productions",
                "email": "jane.doe@example.com"
            }
        ],
        "customKeys": [
            {
                "keyID": 25,
                "keyName": "New Job Key",
                "typeID": 1,
                "value": "1234",
                "dropdownText": "",
                "linkText": "",
                "priority": 1,
                "enabled": 1,
                "editable": 1
            }
        ]
    }
}

Find Jobs

find_jobs(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Retrieves job IDs or full job data filtered by search parameters.

Note

• This query can return a large amount of data. Use the limit and offset arguments in conjunction with the total_count value to paginate your results.

• Arguments need to be passed as keyword arguments.

  Example: find_jobs(name=”New Job”, jobStatus=”IN PROGRESS”)

ARGUMENTS

getData integer OPTIONAL default: 0	Specifies whether to return full data for items. Possible values: 0 or 1. The query will return limited data if the user does not have permission to view job details.
ID integer OPTIONAL	Allows comma-separated list of job IDs.
name string OPTIONAL	Will partially match the job name.
number string OPTIONAL	Will match the job number.
description string OPTIONAL	Will partially match the job description.
startDate date OPTIONAL	Format: YYYY-MM-DD
endDate date OPTIONAL	Format: YYYY-MM-DD
jobStatusID integer OPTIONAL	Job Status ID.
jobStatus string OPTIONAL	Job Status Name.
folder string OPTIONAL	The job folder name.
client_contactID integer OPTIONAL	The ID of a linked contact. Allows comma-separated list.
client_details string OPTIONAL	Will partially match the client details.
biddingLocationID integer OPTIONAL	ID of the corresponding locations. Allows comma-separated list.
biddingLocation string OPTIONAL	Name of the bidding location.
assignedLocationID integer OPTIONAL	ID of the corresponding locations. Allows comma-separated list.
assignedLocation string OPTIONAL	Name of the assigned location.
currency string OPTIONAL	Currency code (USD, EUR, etc).
is_private integer OPTIONAL	0 = Public (Anyone can access the job) 1 = Private (Only crew members can access the job)
agency string OPTIONAL	Agency.
agency_producer string OPTIONAL	Agency Producer.
agency_phone string OPTIONAL	Agency Phone.
agency_email string OPTIONAL	Agency Email.
production_company string OPTIONAL	Production Company.
director string OPTIONAL	Director.
prod_contact string OPTIONAL	Production Contact.
prod_phone string OPTIONAL	Production Phone.
prod_email string OPTIONAL	Production Email.
producer string OPTIONAL	Producer.
creative_lead string OPTIONAL	Creative Lead.
grading string OPTIONAL	Grading.
colorist string OPTIONAL	Colorist.
editorial string OPTIONAL	Editorial.
editor string OPTIONAL	Editor.
mix string OPTIONAL	Mix.
music string OPTIONAL	Music.
sound_design string OPTIONAL	Sound Design.
shoot_date date OPTIONAL	Format: YYYY-MM-DD
shoot_location string OPTIONAL	Shoot Location.
supervised integer OPTIONAL	0 = No 1 = Yes
proj_status string OPTIONAL	Possible values: ONLINE or OFFLINE.
activity string OPTIONAL	Possible values: ACTIVE or INACTIVE.
keywords list OPTIONAL	Allows comma-separated list. Format: [“keyword1”,”keyword2”]
customKeys dictionary OPTIONAL	A dictionary of custom key names and values. Format: {“Custom Key Name” : “Value”}
include_deleted integer OPTIONAL	0 = Do not included deleted jobs 1 = Include deleted jobs
limit integer OPTIONAL default: 0	Specifies the maximum number of rows to return. 0 = no limit.
offset integer OPTIONAL default: 0	Specifies the number of rows to skip before starting to return rows.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data list	A list of returned data. Each object includes: ID : The unique identifier for the job When getData is set to 1, the full job data is returned.

Example Usage:

from nim_core.nim_api import find_jobs

# Searching by a partial job name
response = find_jobs(name="Example")

if response["success"]:
    print(f"Found {response['total_count']} matching job(s).")
    for job in response["data"]:
        print(f"Job ID: {job['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "total_count": 38,
    "data": [
        {
            "ID": 1012
        }
    ]
}

Get Job Statuses

get_jobStatuses(nimURL=None, apiUser=None, apiKey=None) → dict

Returns the list of available job statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of returned data. Each object includes: ID : The unique identifier for the job status name : The name of the job status priority : The priority of the job status bgcolor : The background color of the job status textcolor : The text color of the job status activity_status : The activity status of the job status. Possible values: active or inactive

Example Usage:

from nim_core.nim_api import get_jobStatuses

response = get_jobStatuses()

if response["success"]:
    for status in response["data"]:
        print(f"Job Status: {status['name']} (ID: {status['ID']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 1,
            "name": "BIDDING",
            "priority": 0,
            "bgcolor": "#c5c285",
            "textcolor": "#000000",
            "activity_status": "active"
        },
        {
            "ID": 3,
            "name": "AWARDED",
            "priority": 2,
            "bgcolor": "#94ba77",
            "textcolor": "#000000",
            "activity_status": "active"
        }
    ]
}

Servers & Project Structure

Get All Servers

get_allServers(locationID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves all servers optionally filtered by locationID.

ARGUMENTS

locationID integer OPTIONAL	Optional filter by location ID.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The unique identifier for the server server : The name of the server description : The description of the server locationID : The ID of the location mountpoint : The mount point of the server mountsource : The mount source of the server pub_method : The publication method of the server 0 = Symbolic Link 1 = Copy path : The Linux path to the server winPath : The Windows path to the server osxPath : The macOS path to the server priority : The priority of the server is_projServer : Indicates if the server is a project server 0 = No 1 = Yes

Example Usage:

from nim_core.nim_api import get_allServers

# Retrieve all servers, optionally filtering by locationID
servers = get_allServers(locationID=1)

for srv in servers:
    print(f"Server ID: {srv['ID']}, Name: {srv['server']}")

Example Response:

[
    {
        "ID": 1,
        "server": "Server 1",
        "description": "Primary storage server",
        "locationID": 1,
        "mountpoint": "/mnt/server1",
        "mountsource": null,
        "pub_method": 0,
        "path": "/mnt/server1",
        "winPath": "//Server1/Path",
        "osxPath": "/Volumes/Server1/Path",
        "priority": 0,
        "is_projServer": 1,
        "userID": 0
    }
]

Get Job Servers

get_jobServers(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves servers associated with a specified job ID.

ARGUMENTS

ID integer REQUIRED	The ID of the job to retrieve servers for.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The unique identifier for the server server : The name of the server description : The description of the server locationID : The ID of the location mountpoint : The mount point of the server mountsource : The mount source of the server pub_method : The publication method of the server. 0 = Symbolic Link 1 = Copy path : The path to the server winPath : The Windows path to the server osxPath : The macOS path to the server priority : The priority of the server is_projServer : Indicates if the server is a project server. 0 = No 1 = Yes

Example Usage:

from nim_core.nim_api import get_jobServers

servers = get_jobServers(ID=1234)
for srv in servers:
    print(srv)

Example Response:

[
    {
        "ID": 1,
        "server": "Server 1",
        "description": "Primary storage server",
        "locationID": 1,
        "mountpoint": "/mnt/server1",
        "mountsource": null,
        "pub_method": 0,
        "path": "/mnt/server1",
        "winPath": "//Server1/Path",
        "osxPath": "/Volumes/Server1/Path",
        "priority": 0,
        "is_projServer": 1
    },
    {
        "ID": 2,
        "server": "Server 2",
        "description": "Secondary storage server",
        "locationID": 1,
        "mountpoint": "/mnt/server2",
        "mountsource": null,
        "pub_method": 0,
        "path": "/mnt/server2",
        "winPath": "//Server2/Path",
        "osxPath": "/Volumes/Server2/Path",
        "priority": 1,
        "is_projServer": 1
    }
]

Get Server Info

get_serverInfo(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves server information from server ID.

ARGUMENTS

ID integer REQUIRED	The ID of the server to retrieve information for.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The unique identifier for the server server : The name of the server description : The description of the server locationID : The ID of the location mountpoint : The mount point of the server mountsource : The mount source of the server pub_method : The publication method of the server 0 = Symbolic Link 1 = Copy path : The path to the server winPath : The Windows path to the server osxPath : The macOS path to the server priority : The priority of the server is_projServer : Indicates if the server is a project server. 0 = No 1 = Yes

Example Usage:

from nim_core.nim_api import get_serverInfo

response = get_serverInfo(ID=26)

# The response is expected to be a list of server objects.
for server_info in response:
    print(f"Server Name: {server_info.get('server')}")
    print(f"Mount Point: {server_info.get('mountpoint')}")
    print("---")

Example Response:

[
    {
        "ID": 1,
        "server": "Server 1",
        "description": "Primary storage server",
        "locationID": 1,
        "mountpoint": "/mnt/server1",
        "mountsource": null,
        "pub_method": 0,
        "path": "/mnt/server1",
        "winPath": "//Server1/Path",
        "osxPath": "/Volumes/Server1/Path",
        "priority": 0,
        "is_projServer": 1
    }
]

Get Server OS Path

get_serverOSPath(ID: int = None, os: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns the path to the server based on OS type.

ARGUMENTS

ID integer REQUIRED	The ID of the server.
os string REQUIRED default: Linux	The OS type. Possible values: win, Windows, osx, mac, Darwin, Linux.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: serverOSPath : The OS-specific path for the server

Example Usage:

from nim_core.nim_api import get_serverOSPath

response = get_serverOSPath(ID=1, os="win")

for item in response:
    print(f"Server Path: {item.get('serverOSPath')}")

Example Response:

[
    {
        "serverOSPath": "//Server1/Path"
    }
]

Get OS Path

get_osPath(fileID: int = None, os: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves file path based on file ID and OS type.

ARGUMENTS

fileID integer REQUIRED	The ID of the file.
os string REQUIRED default: Linux	The OS type. Possible values: win, Windows, osx, mac, Darwin, Linux.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

path string

path : The OS-specific path for the file.

Example Usage:

from nim_core.nim_api import get_osPath

response = get_osPath(fileID=1234, os="win")

print(f"The file path for Windows is: {response.get('path')}")

Example Response:

{
    "path": "\\Server1\\Path\\To\\File"
}

Get Asset Master OS Path

get_assetMasterOsPath(assetID: int = None, os: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the path to the asset master based on asset ID and OS type.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset.
os string REQUIRED default: Linux	The OS type. Possible values: win, Windows, osx, mac, Darwin, Linux.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

path string

The path to the asset master based on the OS type.

Example Usage:

from nim_core.nim_api import get_assetMasterOsPath

response = get_assetMasterOsPath(assetID=1234, os="win")

if "path" in response:
    print(f"Asset master path (Windows): {response['path']}")
else:
    print("No path returned.")

Example Response:

{
    "path": "\\Server1\\Path\\To\\AssetMaster.mb"
}

Get Paths

get_paths(item: str = '', ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves the NIM path for a project structure given the item ID and the path item to look for.

ARGUMENTS

ID integer REQUIRED	The ID of the item.
item string REQUIRED	The item type. Item Options with the corresponding path item: job : Project Root show : Asset Root, Asset Comps, Asset Renders shot : Show Root asset : Shot Root, Shot Plates, Shot Comps, Shot Renders
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

root string	The root path for the specified item.
plates string	The plates path for the specified item.
renders string	The render path for the specified item.
comps string	The comp path for the specified item.

Example Usage:

from nim_core.nim_api import get_paths

response = get_paths(ID=1234, item="job")

if "root" in response:
    print(f"Root path: {response['root']}")
else:
    print("No root path returned.")

Example Response:

{
    "root": "Project_Root"
}

Resolve Server OS Path

resolve_OsPath(os: str = None, path: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Given a path string, this function will look for a matching NIM server and return an OS-centric path based on the OS name provided.

ARGUMENTS

os string REQUIRED	The OS type. Possible values: linux, win, osx.
path string REQUIRED	The path to resolve.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
path string	The resolved path based on the OS type.
source_os string	The source OS type.
server string	The name of the server.

Example Usage:

from nim_core.nim_api import resolve_OsPath

response = resolve_OsPath(os="win", path="/mnt/server1/project/file.ext")

if response.get("success"):
    print(f"Resolved Path: {response.get('path')}")
    print(f"Source OS: {response.get('source_os')}")
    print(f"Server: {response.get('server')}")
else:
    print(f"Error: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": "",
    "path": "C:\\Server1\\Project\\File.ext",
    "source_os": "linux",
    "server": "Server 1"
}

Can Bring Online

can_bringOnline(item: str = 'shot', jobID: int = 0, assetID: int = 0, showID: int = 0, shotID: int = 0, nimURL: str = None, apiUser: str = None, apiKey: str = None) → int

Determines if an item can be brought online based on any project structure dependencies.

Note

Item types can be asset or shot.

• If asset, jobID or assetID must be passed.

• If shot, showID or shotID must be passed.

ARGUMENTS

item string REQUIRED default: shot	The item type. Possible values: shot, asset.
jobID integer OPTIONAL	The ID of the job.
assetID integer OPTIONAL	The ID of the asset.
showID integer OPTIONAL	The ID of the show.
shotID integer OPTIONAL	The ID of the shot.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

integer

Indicates if the item can be brought online. 1 = Yes 0 = No

Example Usage:

from nim_core.nim_api import can_bringOnline

# Example: Checking if a shot can be brought online
response = can_bringOnline(item="shot", shotID=1234)

if response == 1:
    print("This shot can be brought online.")
else:
    print("This shot cannot be brought online.")

Example Response:

1

Bring Online

bring_online(item: str = 'shot', assetID: int = 0, shotID: int = 0, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Brings assets and shots online, creating folders from the project structure.

Note

Item types can be asset or shot.

• If asset, assetID must be passed.

• If shot, shotID must be passed.

ARGUMENTS

item string REQUIRED default: shot	The item type. Possible values: shot, asset.
assetID integer OPTIONAL	The ID of the asset.
shotID integer OPTIONAL	The ID of the shot.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import bring_online

response = bring_online(item="shot", shotID=1234)

if response["success"]:
    print("Folders have been created and the shot is now online.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Assets

Get Assets

get_assets(jobID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns all assets for a given job ID.

ARGUMENTS

jobID integer REQUIRED	The job ID.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the asset name : The name of the asset

Example Usage:

from nim_core.nim_api import get_assets

# Retrieve assets for job ID 1234
response = get_assets(jobID=1234)

for asset in response:
    print(f"Asset ID: {asset.get('ID')}, Name: {asset.get('name')}")

Example Response:

[
    {
        "ID": 1,
        "name": "Asset 1"
    },
    {
        "ID": 2,
        "name": "Asset 2"
    }
]

Add Assets

add_asset(jobID: int = None, name: str = None, assetStatusID: int = None, assetStatus: str = None, description: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds a new asset to a job and returns the new assetID.

Note

• If an asset with the specified name already exists, NIM will update the existing asset instead of creating a new one with a duplicate name.

• An asset status can be passed by either name using assetStatus or ID using assetStatusID. If both are passed, the ID will be used.

ARGUMENTS

jobID integer REQUIRED	The ID of the job.
name string REQUIRED	The name of the asset.
assetStatusID integer OPTIONAL	The ID of the asset status.
assetStatus string OPTIONAL	The name of the asset status.
description string OPTIONAL	The description of the asset.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the newly created asset.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
online boolean	Indicates if the asset is online. Possible values: true or false.
folders_created list	A list of paths to the folders created for the asset.

Example Usage:

from nim_core.nim_api import add_asset

response = add_asset(jobID=1, name="NewAsset")

if response["success"]:
    print(f"Created/Updated asset ID: {response['ID']}")
    if response["online"]:
        print("Asset is online. Folders created:")
        for folder in response.get("folders_created", []):
            print(folder)
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 1273,
    "success": true,
    "error": "",
    "online": true,
    "folders_created": [
        "/mnt/server1/project/assets/asset1",
        "/mnt/server1/project/assets/output/asset1",
        "/mnt/server1/project/assets/output/asset1/renders",
        "/mnt/server1/project/assets/output/asset1/comps"
    ]
}

Update Assets

update_asset(assetID: int = None, assetStatusID: int = None, assetStatus: str = None, description: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing asset based on the assetID.

Note

An asset status can be passed by either name or ID. If both are passed, the ID will be used.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset to update.
assetStatusID integer OPTIONAL	The ID of the asset status.
assetStatus string OPTIONAL	The name of the asset status.
description string OPTIONAL	The description of the asset.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the updated asset.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import update_asset

response = update_asset(assetID=1273, description="UpdatedDescription")

if response["success"]:
    print(f"Asset {response['ID']} updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 1273,
    "success": true,
    "error": ""
}

Delete Assets

delete_asset(assetID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an asset based on assetID.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_asset

response = delete_asset(assetID=1273)

if response["success"]:
    print("Asset deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Upload Asset Icon

upload_assetIcon(assetID: int = None, img: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Uploads a thumbnail for an asset.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset.
img string REQUIRED	The local file path to the image file to upload.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
iconPath string	The path to the uploaded icon.

Example Usage:

from nim_core.nim_api import upload_assetIcon

# Example uploading an asset icon from a local file path
response = upload_assetIcon(assetID=1234, img="/path/to/icon.jpg")

if response["success"]:
    print(f"Icon uploaded successfully! Path: {response['iconPath']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "iconPath": "media/jobs/1234/asset/5678/icon/asset_icon.jpg"
}

Get Asset Info

get_assetInfo(assetID: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves information for the asset(s) from the asset ID or comma-separated list of asset IDs.

ARGUMENTS

assetID integer or string REQUIRED	The asset ID or comma-separated list of asset IDs.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

dictionary

A dictionary containing success, error, and data. The data field is a list of dictionaries. Each dictionary includes: jobID : The ID of the job jobFolder : The folder of the job jobNumber : The number of the job jobName : The name of the job assetID : The ID of the asset assetName : The name of the asset AMR_file_ID : The asset master file ID AMR_path : The asset master path AMR_filename : The asset master filename description : The description of the asset img_link : The link to the asset’s image asset_status : The status name of the asset asset_status_ID : The ID of the asset status asset_status_bgcolor : The background color of the asset status asset_status_textcolor : The text color of the asset status securityGroupIDs : The security group IDs securityGroups : The security groups customKeys : A list of dictionaries, each representing a custom key: keyID : The ID of the custom key keyName : The name of the custom key typeID : The type ID of the custom key value : The value of the custom key dropdownText : The dropdown text of the custom key linkText : The link text of the custom key priority : The priority of the custom key enabled : Indicates if the custom key is enabled editable : Indicates if the custom key is editable dropdownOptions : A list of dictionaries representing dropdown options: ID : The ID of the dropdown option value : The value of the dropdown option enabled : Indicates if the dropdown option is enabled

Example Usage:

from nim_core.nim_api import get_assetInfo

# Retrieve info for a single asset
response_single = get_assetInfo(assetID="815")
# Or retrieve info for multiple assets: get_assetInfo(assetID="815,816")

if response_single.get("success"):
    for asset_info in response_single.get("data", []):
        print(f"Asset ID: {asset_info.get('assetID')}, Name: {asset_info.get('assetName')}")
else:
    print(f"Error: {response_single.get('error')}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "jobID": 1,
            "jobFolder": "Project_Folder",
            "jobNumber": "12345",
            "jobName": "Project_Name",
            "assetID": 1,
            "assetName": "Asset_Name",
            "AMR_file_ID": 0,
            "AMR_path": "",
            "AMR_filename": "",
            "description": "",
            "img_link": "/media/jobs/1/assets/Asset_Name_1_icon.jpg",
            "asset_status": "IN PROGRESS",
            "asset_status_ID": 3,
            "asset_status_bgcolor": "#c5c285",
            "asset_status_textcolor": "#000000",
            "securityGroupIDs": "",
            "securityGroups": "",
            "customKeys": [
                {
                    "keyID": 1,
                    "keyName": "Type",
                    "typeID": 3,
                    "value": "3",
                    "dropdownText": "Prop",
                    "linkText": "",
                    "priority": 1,
                    "enabled": 1,
                    "editable": 1,
                    "dropdownOptions": [
                        {
                            "ID": 1,
                            "value": "Character",
                            "enabled": 1
                        },
                        {
                            "ID": 2,
                            "value": "Environment",
                            "enabled": 1
                        },
                        {
                            "ID": 3,
                            "value": "Prop",
                            "enabled": 1
                        }
                    ]
                }
            ]
        }
    ]
}

Get Asset Icon

get_assetIcon(assetID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the path to the asset’s icon for a given assetID.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: img_link : The path to the asset’s icon.

Example Usage:

from nim_core.nim_api import get_assetIcon

response = get_assetIcon(assetID=815)

for asset_info in response:
    print(f"Asset icon path: {asset_info.get('img_link')}")

Example Response:

[
    {
        "img_link": "/media/jobs/4557/assets/asset_icon.jpg"
    }
]

Get Asset Statuses

get_assetStatuses(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the list of available asset statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of asset statuses. Each dictionary includes: ID : The unique identifier for the asset status name : The name of the asset status priority : The priority of the asset status bgcolor : The background color of the asset status textcolor : The text color of the asset status task_status_ID : The task status ID associated with the asset status

Example Usage:

from nim_core.nim_api import get_assetStatuses

response = get_assetStatuses()

if response["success"]:
    for status in response["data"]:
        print(f"Asset Status: {status['name']} (ID: {status['ID']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 4,
            "name": "NOT STARTED",
            "priority": 0,
            "bgcolor": "#bb6060",
            "textcolor": "#c7c7c7",
            "task_status_ID": 0
        },
        {
            "ID": 5,
            "name": "COMPLETED",
            "priority": 0,
            "bgcolor": "#3f6d3f",
            "textcolor": "#cccccc",
            "task_status_ID": 0
        }
    ]
}

Shows

Get Shows

get_shows(jobID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns all shows for a given job ID.

ARGUMENTS

jobID integer REQUIRED	The ID of the job.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the show. showname : The name of the show. folder : The folder name of the show.

Example Usage:

from nim_core.nim_api import get_shows

response = get_shows(jobID=1234)

for show in response:
    print(f"Show ID: {show.get('ID')}, Name: {show.get('showname')}")

Example Response:

[
    {
        "ID": 1234,
        "showname": "Example Show",
        "folder": "example_show"
    },
    {
        "ID": 1235,
        "showname": "Example Show 2",
        "folder": "example_show_2"
    }
]

Get Show Info

get_showInfo(showID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns all show information for a given show ID.

ARGUMENTS

showID integer REQUIRED	The ID of the show.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The unique identifier for the show. jobID : The ID of the job. showname : The name of the show. folder : The folder name of the show. show_status : The status of the show. trt : The total running time of the show. previs_id : The ID of the previs show. is_previs : Indicates if the show is a previs show. has_previs : Indicates if the show has a previs show.

Example Usage:

from nim_core.nim_api import get_showInfo

response = get_showInfo(showID=1234)

for show_data in response:
    print(f"Show ID: {show_data.get('ID')}, Status: {show_data.get('show_status')}")

Example Response:

[
    {
        "ID": 1234,
        "jobID": 5678,
        "showname": "Example Show",
        "folder": "example_show",
        "show_status": "ONLINE",
        "trt": "00:00:30",
        "previs_id": 1235,
        "is_previs": 0,
        "has_previs": 1
    }
]

Add Show

add_show(jobID: int = None, name: str = None, trt: str = None, has_previs: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds a new show to a job and returns the new showID.

Note

If a show with the specified name already exists, NIM will update the existing show instead of creating a new one with a duplicate name.

ARGUMENTS

jobID integer REQUIRED	The ID of the job.
name string REQUIRED	The name of the show.
trt string OPTIONAL	The total running time of the show. Format: 00:00:00:00
has_previs boolean (represented as integer) OPTIONAL	Indicates if the show has a previs show. 0 = No 1 = Yes
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the newly created show.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
online boolean	Indicates if the show is online. Possible values: true or false.
folders_created list	A list of paths to the folders created for the show.

Example Usage:

from nim_core.nim_api import add_show

response = add_show(jobID=1, name="NewShow")

if response["success"]:
    print(f"Created/Updated show ID: {response['ID']}")
    if response["online"]:
        print("Show is online. Folders created:")
        for folder in response.get("folders_created", []):
            print(folder)
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 2994,
    "success": true,
    "error": "",
    "online": true,
    "folders_created": [
        "/mnt/server1/project/shows/show1",
        "/mnt/server1/project/shows/show1/images",
        "/mnt/server1/project/shows/show1/shots",
        "/mnt/server1/project/shows/show1/plates",
        "/mnt/server1/project/shows/show1/conform"
    ]
}

Update Show

update_show(showID: int = None, name: str = None, trt: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing show based on the showID.

Note

The show name will only be updated if the show is offline.

ARGUMENTS

showID integer REQUIRED	The ID of the show to update.
name string OPTIONAL	The name of the show.
trt string OPTIONAL	The total running time of the show. Format: 00:00:00:00
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the updated show.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import update_show

response = update_show(showID=2994, name="UpdatedShow")

if response["success"]:
    print(f"Show {response['ID']} updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 1234,
    "success": true,
    "error": ""
}

Delete Show

delete_show(showID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an existing show based on the showID.

ARGUMENTS

showID integer REQUIRED	The ID of the show to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_show

response = delete_show(showID=2994)

if response["success"]:
    print("Show deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Shots

Get Shots

get_shots(showID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns all shots for a given show ID.

ARGUMENTS

showID integer REQUIRED	The ID of the show.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the shot name : The name of the shot

Example Usage:

from nim_core.nim_api import get_shots

response = get_shots(showID=1234)

for shot in response:
    print(f"Shot ID: {shot.get('ID')}, Name: {shot.get('name')}")

Example Response:

[
    {
        "ID": 11034,
        "name": "SHOT_010"
    },
    {
        "ID": 11035,
        "name": "SHOT_020"
    }
]

Add Shot

add_shot(showID: int = None, shotName: str = None, name: str = None, shotStatusID: int = None, shotStatus: str = None, description: str = None, vfx: str = None, fps: str = None, frames: str = None, shotDuration: str = None, handles: str = None, heads: str = None, tails: str = None, height: str = None, pan: str = None, tilt: str = None, roll: str = None, lens: str = None, fstop: str = None, filter: str = None, dts: str = None, focus: str = None, ia: str = None, convergence: str = None, cam_roll: str = None, stock: str = None, format: str = None, crop: str = None, protect: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds a shot to a show and returns the new ID.

Note

• 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 using shotStatus or ID using shotStatusID. If both are passed, the ID will be used.

ARGUMENTS

showID integer REQUIRED	The ID of the show.
shotName string OPTIONAL	An alternative name for the shot. This argument is included for legacy compatibility. If provided in addition to name, name takes precedence.
name string REQUIRED	The primary name of the shot.
shotStatusID integer OPTIONAL	The ID of the shot status. A status can be passed by either name or ID. If both are passed, the ID will be used.
shotStatus string OPTIONAL	The name of the shot status. A status can be passed by either name or ID. If both are passed, the ID will be used.
description string OPTIONAL	The description of the shot.
vfx string OPTIONAL	The VFX description of the shot.
fps string OPTIONAL	The frames per second for the shot.
frames string OPTIONAL	The duration of the shot in frames.
shotDuration string OPTIONAL	An alternative argument name for the shot duration included for legacy compatibility. This argument can be used in place of frames.
handles string OPTIONAL	The handles for the shot.
heads string OPTIONAL	The heads for the shot.
tails string OPTIONAL	The tails for the shot.
height string OPTIONAL	The height of the shot.
pan string OPTIONAL	The pan of the shot.
tilt string OPTIONAL	The tilt of the shot.
roll string OPTIONAL	The roll of the shot.
lens string OPTIONAL	The lens used for the shot.
fstop string OPTIONAL	The f-stop of the shot.
filter string OPTIONAL	The filter used for the shot.
dts string OPTIONAL	The DTS of the shot.
focus string OPTIONAL	The focus of the shot.
ia string OPTIONAL	The IA of the shot.
convergence string OPTIONAL	The convergence of the shot.
cam_roll string OPTIONAL	The camera roll of the shot.
stock string OPTIONAL	The stock used for the shot.
format string OPTIONAL	The format of the shot.
crop string OPTIONAL	The crop of the shot.
protect string OPTIONAL	The protection for the shot.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the newly created shot.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
online boolean	Indicates if the shot is online. Possible values: true or false.
folders_created list	A list of paths to the folders created for the shot.

Example Usage:

from nim_core.nim_api import add_shot

response = add_shot(showID=1, name="NewShot")

if response["success"]:
    print(f"Created/Updated shot ID: {response['ID']}")
    if response["online"]:
        print("Shot is online. Folders created:")
        for folder in response.get("folders_created", []):
            print(folder)
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 17549,
    "success": true,
    "error": "",
    "online": true,
    "folders_created": [
        "/mnt/server1/project/shots/shot1",
        "/mnt/server1/project/shots/shot1/images",
        "/mnt/server1/project/shots/shot1/images/renders",
        "/mnt/server1/project/shots/shot1/images/comps",
        "/mnt/server1/project/shots/shot1/images/plates",
        "/mnt/server1/project/shots/shot1/work"
    ]
}

Update Shot

update_shot(shotID: int = None, shotStatusID: int = None, shotStatus: str = None, description: str = None, vfx: str = None, fps: str = None, frames: str = None, duration: str = None, handles: str = None, heads: str = None, tails: str = None, height: str = None, pan: str = None, tilt: str = None, roll: str = None, lens: str = None, fstop: str = None, filter: str = None, dts: str = None, focus: str = None, ia: str = None, convergence: str = None, cam_roll: str = None, stock: str = None, format: str = None, crop: str = None, protect: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing shot based on the shotID.

Note

A shot status can be passed by either name using shotStatus or ID using shotStatusID. If both are passed, the ID will be used.

ARGUMENTS

shotID integer REQUIRED	The ID of the shot to update.
shotStatusID integer OPTIONAL	The ID of the shot status. A status can be passed by either name or ID. If both are passed, the ID will be used.
shotStatus string OPTIONAL	The name of the shot status. A status can be passed by either name or ID. If both are passed, the ID will be used.
description string OPTIONAL	The description of the shot.
vfx string OPTIONAL	The VFX description of the shot.
fps string OPTIONAL	The frames per second for the shot.
frames string OPTIONAL	The duration of the shot in frames.
duration string OPTIONAL	An alternative argument name for the shot duration included for legacy compatibility. This argument can be used in place of frames.
handles string OPTIONAL	The handles for the shot.
heads string OPTIONAL	The heads for the shot.
tails string OPTIONAL	The tails for the shot.
height string OPTIONAL	The height of the shot.
pan string OPTIONAL	The pan of the shot.
tilt string OPTIONAL	The tilt of the shot.
roll string OPTIONAL	The roll of the shot.
lens string OPTIONAL	The lens used for the shot.
fstop string OPTIONAL	The f-stop of the shot.
filter string OPTIONAL	The filter used for the shot.
dts string OPTIONAL	The DTS of the shot.
focus string OPTIONAL	The focus of the shot.
ia string OPTIONAL	The IA of the shot.
convergence string OPTIONAL	The convergence of the shot.
cam_roll string OPTIONAL	The camera roll of the shot.
stock string OPTIONAL	The stock used for the shot.
format string OPTIONAL	The format of the shot.
crop string OPTIONAL	The crop of the shot.
protect string OPTIONAL	The protection for the shot.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the updated shot.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import update_shot

response = update_shot(shotID=17549, description="UpdatedShotDescription")

if response["success"]:
    print(f"Shot {response['ID']} updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 17549,
    "success": true,
    "error": ""
}

Delete Shot

delete_shot(shotID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes a shot based on shotID.

ARGUMENTS

shotID integer REQUIRED	The ID of the shot to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_shot

response = delete_shot(shotID=17549)

if response["success"]:
    print("Shot deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Upload Shot Icon

upload_shotIcon(shotID: int = None, img: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Uploads a thumbnail for a shot.

ARGUMENTS

shotID integer REQUIRED	The ID of the shot.
img string OPTIONAL	The local file path to the image file to upload.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
iconPath string	The path to the uploaded icon.

Example Usage:

from nim_core.nim_api import upload_shotIcon

response = upload_shotIcon(shotID=17543, img="/path/to/icon.jpg")

if response["success"]:
    print(f"Shot icon uploaded successfully! Path: {response['iconPath']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "iconPath": "media/jobs/5089/shot/17543/icon/example_icon.jpg"
}

Get Shot Info

get_shotInfo(shotID: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves information for the shot(s) from the shot ID or comma-separated list of shot IDs.

ARGUMENTS

shotID integer or string REQUIRED	The ID (integer) or comma-separated list of shot IDs (string).
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of returned data. Each dictionary includes: jobID : The unique identifier for the job jobFolder : The folder name of the job jobNumber : The number of the job jobName : The name of the job showID : The unique identifier for the show showFolder : The folder name of the show showName : The name of the show shotID : The unique identifier for the shot shotName : The name of the shot description : The description of the shot vfx : The VFX description of the shot fps : The frames per second for the shot lens : The lens used for the shot frames : The duration of the shot in frames handles : The handles for the shot heads : The heads for the shot tails : The tails for the shot height : The height of the shot pan : The pan of the shot tilt : The tilt of the shot roll : The roll of the shot fstop : The f-stop of the shot filter : The filter used for the shot dts : The DTS of the shot focus : The focus of the shot IA : The IA of the shot conv : The convergence of the shot cam_roll : The camera roll of the shot stock_type : The stock type used for the shot film_format : The film format of the shot crop : The crop of the shot protect : The protection for the shot img_link : The link to the shot’s icon shot_status : The status of the shot shot_status_ID : The ID of the shot status shot_status_bgcolor : The background color of the shot status shot_status_textcolor : The text color of the shot status securityGroupIDs : The security group IDs associated with the shot securityGroups : The security groups associated with the shot customKeys : A list of dictionaries representing the custom keys for the shot. Each dictionary includes: keyID : The unique identifier for the custom key keyName : The name of the custom key typeID : The type ID of the custom key value : The value of the custom key dropdownText : The dropdown text of the custom key linkText : The link text of the custom key priority : The priority of the custom key enabled : Indicates if the custom key is enabled editable : Indicates if the custom key is editable dropdownOptions : A list of dictionaries for dropdown options, each including: ID : The unique identifier for the dropdown option value : The value of the dropdown option enabled : Indicates if the dropdown option is enabled

Example Usage:

from nim_core.nim_api import get_shotInfo

# Single shot:
response_single = get_shotInfo(shotID="11034")

# Multiple shots: get_shotInfo(shotID="11034,11035")

if isinstance(response_single, list):
    for shot_data in response_single:
        print(f"Shot ID: {shot_data.get('shotID')}, Name: {shot_data.get('shotName')}")
else:
    print("Error parsing shot data.")

Example Response:

[
    {
        "jobID": 4557,
        "jobFolder": "10000_JOB",
        "jobNumber": "10000",
        "jobName": "JOB",
        "showID": 2330,
        "showFolder": "SHOW",
        "showName": "SHOW",
        "shotID": 11034,
        "shotName": "SH_010",
        "description": "The shot description.",
        "vfx": "The vfx notes.",
        "fps": "",
        "lens": "80mm",
        "frames": 46,
        "handles": null,
        "heads": 8,
        "tails": 8,
        "height": null,
        "pan": null,
        "tilt": null,
        "roll": null,
        "fstop": null,
        "filter": null,
        "dts": null,
        "focus": null,
        "IA": "",
        "conv": "",
        "cam_roll": null,
        "stock_type": null,
        "film_format": null,
        "crop": null,
        "protect": null,
        "img_link": "/media/jobs/4557/shots/shot_icon.jpg",
        "shot_status": "IN PROGRESS",
        "shot_status_ID": 3,
        "shot_status_bgcolor": "#c5c285",
        "shot_status_textcolor": "#000000",
        "securityGroupIDs": "",
        "securityGroups": "",
        "customKeys": [
            {
                "keyID": 9,
                "keyName": "Completion %",
                "typeID": 1,
                "value": "80%",
                "dropdownText": "",
                "linkText": "",
                "priority": 1,
                "enabled": 1,
                "editable": 1
            }
        ]
    }
]

Get Shot Icon

get_shotIcon(shotID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the path to the shot’s icon for a given shotID.

ARGUMENTS

shotID integer REQUIRED	The ID of the shot.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: img_link : The link to the shot’s icon

Example Usage:

from nim_core.nim_api import get_shotIcon

response = get_shotIcon(shotID=11034)

for shot_info in response:
    print(f"Shot icon link: {shot_info.get('img_link')}")

Example Response:

[
    {
        "img_link": "/media/jobs/4557/shots/shot_icon.jpg"
    }
]

Get Shot Statuses

get_shotStatuses(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the list of available shot statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of shot statuses. Each dictionary includes: ID : The unique identifier for the shot status name : The name of the shot status priority : The priority of the shot status bgcolor : The background color of the shot status textcolor : The text color of the shot status task_status_ID : The task status ID associated with the shot status

Example Usage:

from nim_core.nim_api import get_shotStatuses

response = get_shotStatuses()

if response["success"]:
    for status in response["data"]:
        print(f"Shot Status: {status['name']} (ID: {status['ID']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 3,
            "name": "IN PROGRESS",
            "priority": 1,
            "bgcolor": "#c5c285",
            "textcolor": "#000000",
            "task_status_ID": 0
        },
        {
            "ID": 4,
            "name": "COMPLETED",
            "priority": 2,
            "bgcolor": "#3f6d3f",
            "textcolor": "#cccccc",
            "task_status_ID": 0
        }
    ]
}

Tasks

Get Task Types

get_taskTypes(app: str = 'all', userType: str = 'artist', assetID: int = None, shotID: int = None, onlyWithFiles: int = None, pub: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

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.

ARGUMENTS

app string OPTIONAL default: all	Filter task types by associated application. Possible values: MAYA, C4D, AE, NUKE, HIERO, PHOTOSHOP, 3DSMAX, HOUDINI, FLAME, all.
userType string OPTIONAL default: artist	Filter task types by associated role type. Possible values: artist, producer, management, all.
assetID integer OPTIONAL	Include tasks used on the asset by ID.
shotID integer OPTIONAL	Include tasks used on the shot by ID.
onlyWithFiles integer OPTIONAL default: 0	Flag to return only task types that are associated with files on the provided shot or asset. 0 = All task types 1 = Only task types that are associated with files on the provided shot or asset
pub integer OPTIONAL default: 0	Optional filter in conjunction with the onlyWithFiles flag to return only task types with published files. 0 = All task types 1 = Only task types with published files
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the task type name : The name of the task type short_name : The short name of the task type folder : The folder name of the task type

Example Usage:

from nim_core.nim_api import get_taskTypes

# Example: retrieving all task types for Maya, only for tasks used on shot 42, with published files
response = get_taskTypes(app="MAYA", shotID=42, onlyWithFiles=1, pub=1)

if isinstance(response, list):
    for task_type in response:
        print(f"Task Type: {task_type.get('name')} (ID: {task_type.get('ID')})")
else:
    print("Error retrieving task types.")

Example Response:

[
    {
        "ID": 4,
        "name": "ANIM",
        "short_name": "ANI",
        "folder": "ANIM"
    },
    {
        "ID": 3,
        "name": "TEXTURE",
        "short_name": "TEX",
        "folder": "TEX"
    }
]

Add Task

add_task(assetID: int = None, shotID: int = None, taskTypeID: int = None, taskTypeName: str = None, userID: int = None, username: str = None, taskStatusID: int = None, taskStatus: str = None, description: str = None, estimatedHours: float = None, startDate: str = None, endDate: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds a new task to an asset or shot.

Note

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.

ARGUMENTS

assetID integer REQUIRED	The ID of the asset. Required if shotID is not passed.
shotID integer REQUIRED	The ID of the shot. Required if assetID is not passed.
taskTypeID integer REQUIRED	The ID of the task type. Required if taskTypeName is not passed.
taskTypeName string REQUIRED	The name of the task type. Required if taskTypeID is not passed.
userID integer OPTIONAL	The ID of the user.
username string OPTIONAL	The username of the user.
taskStatusID integer OPTIONAL	The ID of the task status.
taskStatus string OPTIONAL	The name of the task status.
description string OPTIONAL	The description of the task.
estimatedHours float OPTIONAL	The estimated hours for the task.
startDate UTC datetime string OPTIONAL	The start date of the task. Format: YYYY-MM-DD HH:MM:SS
endDate UTC datetime string OPTIONAL	The end date of the task. Format: YYYY-MM-DD HH:MM:SS
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

Example Request:

curl 'http://hostname:portnumber/nimAPI.php?q=addTask&assetID=1&taskTypeID=1&customKeys={"My Custom Key Name":"Some text"}'

Example Response:

{
    "ID": "22685",
    "success": true,
    "error": ""
}

Update Task

update_task(taskID: int = None, taskTypeID: int = None, taskTypeName: str = None, userID: int = None, username: str = None, taskStatusID: int = None, taskStatus: str = None, description: str = None, estimatedHours: float = None, startDate: str = None, endDate: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing task based on taskID.

Note

• 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.

ARGUMENTS

taskID integer REQUIRED	The ID of the task to update.
taskTypeID integer OPTIONAL	The ID of the task type.
taskTypeName string OPTIONAL	The name of the task type.
userID integer OPTIONAL	The ID of the user.
username string OPTIONAL	The username of the user.
taskStatusID integer OPTIONAL	The ID of the task status.
taskStatus string OPTIONAL	The name of the task status.
description string OPTIONAL	The description of the task.
estimatedHours float OPTIONAL	The estimated hours for the task.
startDate UTC datetime string OPTIONAL	The start date of the task. Format: YYYY-MM-DD HH:MM:SS
endDate UTC datetime string OPTIONAL	The end date of the task. Format: YYYY-MM-DD HH:MM:SS
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the updated task.
success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Request:

curl "http://hostname:portnumber/nimAPI.php?q=updateTask&taskID=22685&description=UpdatedDescription"

Example Response:

{
    "ID": "22685",
    "success": true,
    "error": ""
}

Delete Task

delete_task(taskID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes a task based on taskID.

ARGUMENTS

taskID integer REQUIRED	The ID of the task to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_task

response = delete_task(taskID=22685)

if response["success"]:
    print("Task deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Get Task Info

get_taskInfo(ID: int = None, itemClass: str = None, itemID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves information about one or more tasks.

Note

• Providing the task ID as ID will return the information for a single task.

• Providing an asset or shot ID as itemID and setting the itemClass argument will return information for all tasks associated with the respective item.

ARGUMENTS

ID integer OPTIONAL	The ID of the task. If this is provided, the query returns info for a single task.
itemClass string OPTIONAL	The item class for itemID. Possible values: asset, shot. Required if itemID is passed.
itemID integer OPTIONAL	The ID of the asset or shot to retrieve task info for, depending on itemClass.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: taskID : The unique identifier for the task typeID : The type ID of the task taskName : The name of the task userID : The ID of the user assigned to the task username : The username of the user assigned to the task jobID : The ID of the job associated with the task assetID : The ID of the asset associated with the task showID : The ID of the show associated with the task shotID : The ID of the shot associated with the task taskDesc : The description of the task task_status_ID : The ID of the task status task_status : The name of the task status start_date : The start date of the task end_date : The end date of the task progress : The progress of the task estimated_hours : The estimated hours for the task customKeys : A dictionary of custom keys associated with the task

Example Request:

curl "http://hostname:portnumber/nimAPI.php?q=getTaskInfo&ID=21120"

Example Response:

[
    {
        "taskID": 21120,
        "typeID": 9,
        "taskName": "COMP",
        "userID": 1,
        "username": "john.doe",
        "jobID": null,
        "assetID": null,
        "showID": null,
        "shotID": 15839,
        "taskDesc": "",
        "task_status_ID": 4,
        "task_status": "REVIEW",
        "start_date": "2023-11-23 08:00:00",
        "end_date": "2023-11-26 08:00:00",
        "progress": 0,
        "estimated_hours": "20.00",
        "customKeys": []
    }
]

Get Task Statuses

get_taskStatuses(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the list of available task statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of task statuses. Each dictionary includes: ID : The unique identifier for the task status status : The name of the task status type : The type of the task status priority : The priority of the task status bgcolor : The background color of the task status textcolor : The text color of the task status

Example Usage:

from nim_core.nim_api import get_taskStatuses

response = get_taskStatuses()

if response["success"]:
    for status_info in response["data"]:
        print(f"Task Status: {status_info['status']} (ID: {status_info['ID']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 2,
            "status": "IN PROGRESS",
            "type": "active",
            "priority": 2,
            "bgcolor": "#c5c285",
            "textcolor": "#000000"
        },
        {
            "ID": 7,
            "status": "COMPLETED",
            "type": "completed",
            "priority": 6,
            "bgcolor": "#3f6d3f",
            "textcolor": "#e0e0e0"
        }
    ]
}

Files

Get Basenames

get_bases(shotID: int = None, assetID: int = None, showID: int = None, taskType: str = None, taskTypeID: int = None, pub: bool = False, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns all basenames for a show, shot, or asset.

Note

A shot ID, asset ID, or show ID must be provided. If more than one is provided, the order of precedence is showID > assetID > shotID.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to find basenames. Required if assetID and showID are not passed.
assetID integer OPTIONAL	The ID of the asset to find basenames. Required if shotID and showID are not passed.
showID integer OPTIONAL	The ID of the show to find basenames. Required if shotID and assetID are not passed.
taskType string OPTIONAL	Task type name to filter results.
taskTypeID integer OPTIONAL	Task type ID to filter results.
pub boolean OPTIONAL	Filter to only return published basenames. true = Return only published basenames false = Return all basenames
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: basename : The basename of the file.

Example Usage:

from nim_core.nim_api import get_bases

# Example: retrieving basenames for an asset with ID=1234, filtering for a recognized task type, returning only published basenames:
response = get_bases(assetID=1234, taskType="COMP", pub=True)

for entry in response:
    print(f"Found basename: {entry.get('basename')}")

Example Response:

[
    {
        "basename": "SH_010_ANIM"
    },
    {
        "basename": "SH_010_COMP"
    },
    {
        "basename": "SH_001_MODEL"
    }
]

Get Published Basename

get_basesPub(shotID: int = None, assetID: int = None, basename: str = '', username: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves information for the published file for a given basename.

Note

The optional username argument is used to return date information in the user’s selected timezone.

ARGUMENTS

shotID integer OPTIONAL	The shot ID to find the basename. Required if assetID is not passed.
assetID integer OPTIONAL	The asset ID to find the basename. Required if shotID is not passed.
basename string REQUIRED	The basename of the file.
username string OPTIONAL	The username to return date information in the user’s selected timezone.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: fileID : The ID of the file. fileClass : The class of the file’s parent. parentID : The ID of the parent item. serverID : The ID of the server where the file is located. task_type : The task type associated with the file. task_type_ID : The ID of the file’s task type. task_type_folder : The folder of the task type. basename : The basename of the file. filename : The filename of the file. filepath : The filepath of the file. ext : The file extension. version : The version of the file. isPublished : Indicates if the file is published. 1 = Published 0 = Not Published isWorking : Indicates if the file is a working file. 1 = Is a working file 0 = Not a working file note : The note associated with the file. userID : The ID of the user who created the file. username : The username of the user who created the file. date : The date associated with the file. metadata : The metadata associated with the file. customKeys : A dictionary of custom keys associated with the file.

Example Usage:

from nim_core.nim_api import get_basesPub

# Example: retrieving the published file info for basename="SH_010_ANIM" on shotID=14245, using a specific username:
response = get_basesPub(shotID=14245, basename="SH_010_ANIM", username="jane.doe")

for file_info in response:
    print(f"Filename: {file_info.get('filename')} (Published? {file_info.get('isPublished')})")

Example Response:

[
    {
        "fileID": 34721,
        "fileClass": "SHOT",
        "parentID": 14245,
        "serverID": 25,
        "task_type": "",
        "task_type_ID": 4,
        "task_type_folder": "ANIM",
        "basename": "SH_010_ANIM",
        "filename": "SH_010_ANIM_v03.c4d",
        "filepath": "/path/to/SH_010_ANIM/",
        "ext": "c4d",
        "version": 6,
        "isPublished": 1,
        "isWorking": 1,
        "note": "",
        "userID": 1,
        "username": "john.doe",
        "date": "2022-05-24 11:55:42",
        "metadata": "{}",
        "customKeys": {
            "Status": ""
        }
    }
]

Get All Published Basenames

get_basesAllPub(shotID: int = None, assetID: int = None, task: str = None, taskID: int = None, username: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves all published basename files for a given asset or shot filtered by task type.

Note

• The type argument represents the task type name.

• The optional username argument is used to return the date information in the user’s selected timezone.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to find basenames. Required if assetID is not passed.
assetID integer OPTIONAL	The ID of the asset to find basenames. Required if shotID is not passed.
task string OPTIONAL	Task type name to filter results. Required if taskID is not passed.
taskID integer OPTIONAL	Task type ID to filter results. Required if task is not passed.
username string OPTIONAL	The username to return date information in the user’s selected timezone.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: fileID : The ID of the file. fileClass : The class of the file’s parent. parentID : The ID of the parent item. serverID : The ID of the server where the file is located. task_type : The task type associated with the file. task_type_ID : The ID of the file’s task type. task_type_folder : The folder of the task type. basename : The basename of the file. filename : The filename of the file. filepath : The filepath of the file. ext : The file extension. version : The version of the file. isPublished : Indicates if the file is published. 1 = Published 0 = Not Published isWorking : Indicates if the file is a working file. 1 = Is a working file 0 = Not a working file note : The note associated with the file. userID : The ID of the user who created the file. username : The username of the user who created the file. date : The date associated with the file. metadata : The metadata associated with the file. customKeys : A dictionary of custom keys associated with the file.

Example Usage:

from nim_core.nim_api import get_basesAllPub

# Example: retrieving published basenames for shotID=14245, filtering by task="ANIM", returning date info for user "jane.doe"
response = get_basesAllPub(shotID=14245, task="ANIM", username="jane.doe")

for file_info in response:
    print(f"Filename: {file_info.get('filename')}, Published: {file_info.get('isPublished')}")

Example Response:

[
    {
        "fileID": 34721,
        "fileClass": "SHOT",
        "parentID": 14245,
        "serverID": 25,
        "task_type": "",
        "task_type_ID": 4,
        "task_type_folder": "ANIM",
        "basename": "SH_010_ANIM",
        "filename": "SH_010_ANIM_v03.c4d",
        "filepath": "/path/to/SH_010_ANIM/",
        "ext": "c4d",
        "version": 6,
        "isPublished": 1,
        "isWorking": 1,
        "note": "",
        "userID": 1,
        "username": "john.doe",
        "date": "2022-05-24 11:55:42",
        "metadata": "{}",
        "customKeys": {
            "Status": ""
        }
    }
]

Get Basename Info

get_baseInfo(shotID: int = None, assetID: int = None, showID: int = None, taskTypeID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves all basenames and their max version for a given asset, shot, or show based on ID.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to find basenames. Required if assetID and showID are not passed.
assetID integer OPTIONAL	The ID of the asset to find basenames. Required if shotID and showID are not passed.
showID integer OPTIONAL	The ID of the show to find basenames. Required if shotID and assetID are not passed.
taskTypeID integer REQUIRED	The task type ID of the files associated with the basename.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: basename : The name of the basename. maxVersion : The highest file version number in the basename.

Example Usage:

from nim_core.nim_api import get_baseInfo

# Example: retrieving basenames for shotID=1234 and taskTypeID=4
response = get_baseInfo(shotID=1234, taskTypeID=4)

for info in response:
    print(f"Basename: {info.get('basename')} (Max Version: {info.get('maxVersion')})")

Example Response:

[
    {
        "basename": "SH_010_ANIM",
        "maxVersion": 7
    }
]

Get Basename Version

get_baseVer(shotID: int = None, assetID: int = None, basename: str = '', nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the highest version number for a given basename on an asset or shot.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to find the basename. Required if assetID is not passed.
assetID integer OPTIONAL	The ID of the asset to find the basename. Required if shotID is not passed.
basename string REQUIRED	The basename of the file.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The file ID for the returned version basename : The basename of the returned version version : The version number

Example Usage:

from nim_core.nim_api import get_baseVer

# Example: retrieving the highest file version for basename="SH_010_ANIM" on shotID=1234
response = get_baseVer(shotID=1234, basename="SH_010_ANIM")

for file_info in response:
    print(f"File ID: {file_info.get('ID')}, Basename: {file_info.get('basename')}, Version: {file_info.get('version')}")

Example Response:

[
    {
        "ID": 34722,
        "basename": "SH_010_ANIM",
        "version": 7
    }
]

Get Versions

get_vers(shotID: int = None, assetID: int = None, showID: int = None, basename: str = None, pub: bool = False, username: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the versions for a given basename.

Note

The optional username argument is used to return date information in the user’s selected timezone.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to find basenames. Required if assetID and showID are not passed.
assetID integer OPTIONAL	The ID of the asset to find basenames. Required if shotID and showID are not passed.
showID integer OPTIONAL	The ID of the show to find basenames. Required if shotID and assetID are not passed.
basename string REQUIRED	The basename in which to find versions.
pub boolean OPTIONAL	Filter to only return published basenames. 1 = Return only published basenames 0 = Return all basenames
username string OPTIONAL	The username to return date information in the user’s selected timezone.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: fileID : The ID of the file. fileClass : The class of the file. parentID : The ID of the parent. serverID : The ID of the server. task_type : The task type. task_type_ID : The ID of the task type. task_type_folder : The folder of the task type. basename : The basename of the file. filename : The filename of the file. filepath : The filepath of the file. ext : The file extension. version : The version of the file. isPublished : Indicates if the file is published. 1 = Published 0 = Not Published isWorking : Indicates if the file is a working file. 1 = Is a working file 0 = Not a working file note : The note associated with the file. userID : The ID of the user who created the file. username : The username of the user who created the file. date : The date associated with the file. metadata : The metadata associated with the file. customKeys : A dictionary of custom keys associated with the file.

Example Usage:

from nim_core.nim_api import get_vers

# Example: retrieving versions for basename="SH_010_ANIM" on shotID=1234, published only, date info for user "john.doe"
response = get_vers(shotID=1234, basename="SH_010_ANIM", pub=True, username="john.doe")

for file_data in response:
    print(f"File ID: {file_data.get('fileID')}, Version: {file_data.get('version')}")

Example Response:

[
    {
        "fileID": 34720,
        "fileClass": "SHOT",
        "parentID": 14245,
        "serverID": 25,
        "task_type": "",
        "task_type_ID": 4,
        "task_type_folder": "ANIM",
        "basename": "SH_010_ANIM",
        "filename": "SH_010_ANIM_v03.c4d",
        "filepath": "/path/to/SH_010_ANIM/",
        "ext": ".c4d",
        "version": 7,
        "isPublished": 1,
        "isWorking": 1,
        "note": "",
        "userID": 1,
        "username": "john.doe",
        "date": "2022-05-24 11:49:23",
        "metadata": "{}",
        "customKeys": {
            "Status": ""
        }
    }
]

Get Version Info

get_verInfo(verID: int = None, username: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the version information of a specified file ID.

ARGUMENTS

verID integer REQUIRED	The ID of the file.
username string OPTIONAL	The username to return date information in the user’s selected timezone.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: fileID : The ID of the file. fileClass : The class of the file. parentID : The ID of the parent. serverID : The ID of the server. task_type : The task type. task_type_ID : The ID of the task type. task_type_folder : The folder of the task type. basename : The basename of the file. filename : The filename of the file. filepath : The filepath of the file. ext : The file extension. version : The version of the file. isPublished : Indicates if the file is published. 1 = Published 0 = Not Published isWorking : Indicates if the file is a working file. 1 = Is a working file 0 = Not a working file note : The note associated with the file. userID : The ID of the user who created the file. username : The username of the user who created the file. date : The date associated with the file. metadata : The metadata associated with the file. customKeys : A dictionary of custom keys associated with the file.

Example Usage:

from nim_core.nim_api import get_verInfo

# Example: retrieving version info for file ID=33307, returning date info for user "john.doe"
response = get_verInfo(verID=33307, username="john.doe")

for file_data in response:
    print(f"File ID: {file_data.get('fileID')}, Basename: {file_data.get('basename')}, Version: {file_data.get('version')}")

Example Response:

[
    {
        "fileID": 33307,
        "fileClass": "SHOT",
        "parentID": 11034,
        "serverID": 25,
        "task_type": "",
        "task_type_ID": 4,
        "task_type_folder": "ANIM",
        "basename": "ESC_010_ANIM_b1",
        "filename": "ESC_010_ANIM_b1_v01.mb",
        "filepath": "/path/to/ESC_010_ANIM_b1/scenes/",
        "ext": ".mb",
        "version": 1,
        "isPublished": 0,
        "isWorking": 1,
        "note": "",
        "userID": 1,
        "username": "john.doe",
        "date": "2018-02-21 17:41:30",
        "metadata": "{}",
        "customKeys": {
            "Status": "DECLINED"
        }
    }
]

Get Max Version

get_maxVersion(fileID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the highest version number in a basename for a given fileID.

ARGUMENTS

fileID integer REQUIRED

The ID of the file.

RETURN

list	An list of dictionaries. Each dictionary includes: maxVersion : The highest version number in the basename.

Example Request:

from nim_core.nim_api import get_maxVersion

# Example: retrieving max version for file ID=33307
response = get_maxVersion(fileID=33307)

for version in response:
    print(f"Max Version: {version.get('maxVersion')}")

Example Response:

[
    {
        "maxVersion": 7
    }
]

Clear Published Flags

clear_pubFlags(shotID: int = None, assetID: int = None, basename: str = '', nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Clears all published flags from a basename.

Note

Run before publishing to clear previous basename published flags.

ARGUMENTS

shotID integer OPTIONAL	The ID of the shot to clear basename published flags. Required if assetID is not passed.
assetID integer OPTIONAL	The ID of the asset to clear basename published flags. Required if shotID is not passed.
basename string REQUIRED	The basename name to clear.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

result boolean

Indicates whether the operation was successful.

Example Usage:

from nim_core.nim_api import clear_pubFlags

# Example: clearing all published flags for basename="SH_010_ANIM" on shotID=1234
response = clear_pubFlags(shotID=1234, basename="SH_010_ANIM")

if response.get("result"):
    print("Published flags cleared successfully.")
else:
    print("Failed to clear published flags.")

Example Response:

{
    "result": true
}

Publish Symbolic Link

publish_symLink(fileID: int = None, forceLink: bool = True, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Creates the symbolic link for a published file based on the file ID.

ARGUMENTS

fileID integer REQUIRED	The ID of the file.
forceLink boolean OPTIONAL	Creates a symbolic link even if the source location is invalid. Possible values: True, False.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

result boolean

Indicates whether the operation was successful.

Example Usage:

from nim_core.nim_api import publish_symLink

# Example: publishing symbolic link for fileID=1234 with forceLink=True
response = publish_symLink(fileID=1234, forceLink=True)

if response.get("result"):
    print("Symbolic link created successfully.")
else:
    print("Failed to create symbolic link.")

Example Response:

{
    "result": true
}

Save File

save_file(parent: str = 'show', parentID: int = 0, task_type_ID: int = 0, task_folder: str = '', userID: int = 0, basename: str = '', filename: str = '', path: str = '', ext: str = None, version: int = None, comment: str = None, serverID: int = 0, pub: bool = False, forceLink: int = 1, work: bool = True, metadata: dict = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Saves a file to the NIM database.

ARGUMENTS

parent string REQUIRED	Class of parent for the file. Possible values: show, shot, asset.
parentID integer REQUIRED	ID of the parent.
task_type_ID integer REQUIRED	Task type ID to associate with the file.
task_folder string REQUIRED	Task folder to use for the file.
userID integer REQUIRED	ID of the user who owns the file.
basename string REQUIRED	Basename for the file.
filename string REQUIRED	File name of the file being saved.
path string REQUIRED	Path to the file.
ext string OPTIONAL	File extension.
version integer OPTIONAL	Version of the file.
comment string OPTIONAL	Note to add to the file entry.
serverID integer REQUIRED	ID of the server where the file exists.
pub boolean OPTIONAL	Value of True will publish the file. Possible values: True, False.
forceLink integer OPTIONAL default: 1	Will create a symbolic link even if the source location is invalid. 1 = Force create the symbolic link 0 = Do not force create the link.
work boolean OPTIONAL	Mark file as a working file. Possible values: True, False.
metadata dictionary OPTIONAL	Dictionary of metadata. Format: {“Key” : “Value”}
customKeys dictionary OPTIONAL	Dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID string	The NIM ID of the newly created file.
success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import add_file

# Example: adding a file to an asset with ID=1, using task type ID=4, userID=1, etc.
response = add_file(
    parent='asset',
    parentID=1,
    task_type_ID=4,
    task_folder='ANIM',
    userID=1,
    basename='SH_010_ANIM',
    filename='SH_010_ANIM_v01.c4d',
    path='/path/to/file',
    serverID=1
)

if response["success"]:
    print(f"File added successfully with ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": "35260",
    "success": true,
    "error": ""
}

Update File

update_file(ID: int = 0, task_type_ID: int = 0, task_folder: str = '', userID: int = 0, basename: str = '', filename: str = '', path: str = '', ext: str = '', version: str = '', comment: str = '', serverID: int = 0, pub: bool = False, forceLink: int = 1, work: bool = True, metadata: str = '', customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing file in the NIM database.

ARGUMENTS

ID integer REQUIRED	The ID of the file to update.
task_type_ID integer OPTIONAL	Task type ID to associate with the file.
task_folder string OPTIONAL	Task folder to use for the file.
userID integer OPTIONAL	ID of the user who owns the file.
basename string OPTIONAL	Basename for the file.
filename string OPTIONAL	File name of the file being saved.
path string OPTIONAL	Path to the file.
ext string OPTIONAL	File extension.
version string OPTIONAL	Version of the file.
comment string OPTIONAL	Comment to add to the file entry.
serverID integer OPTIONAL	ID of the server where the file exists.
pub boolean OPTIONAL	Value of True will publish the file. Possible values: True, False.
forceLink integer OPTIONAL	Will create a symbolic link even if the source location is invalid.
work boolean OPTIONAL	Mark file as a working file. Possible values: True, False.
metadata string OPTIONAL	Dictionary of metadata. Format: {“Key” : “Value”}
customKeys dictionary OPTIONAL	Dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID string	The ID of the updated file.
success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import update_file

# Example: updating a file with ID=35260, setting a new version and comment
response = update_file(
    ID=35260,
    version='2',
    comment='Updated version comment'
)

if response["success"]:
    print(f"File updated successfully. New ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": "35260",
    "success": true,
    "error": ""
}

Find Files

find_files(parent: str = 'shot', parentID: int = None, name: str = '', path: str = '', metadata: str = '', nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

A search function for files. Any provided arguments will filter the returned list.

ARGUMENTS

parent string OPTIONAL	Finds children of the given parent type. Possible values: ASSET, SHOT. Required when parentID is passed.
parentID integer OPTIONAL	Finds children of the parent item with the specified ID. Required when parent is passed.
name string OPTIONAL	Find matching name.
path string OPTIONAL	Find matching path.
metadata string OPTIONAL	Find matching metadata. Format: {“Key” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The ID of the file. class : The class of the file. parentID : The ID of the parent. serverID : The ID of the server. task_type : The task type. task_type_ID : The ID of the task type. task_type_folder : The folder of the task type. basename : The basename of the file. filename : The filename of the file. filepath : The filepath of the file. ext : The file extension. version : The version of the file. isPublished : Indicates if the file is published. 1 = Published 0 = Not Published isWorking : Indicates if the file is a working file. 1 = Is a working file 0 = Not a working file note : The note associated with the file. userID : The ID of the user who created the file. username : The username of the user who created the file. date : The date associated with the file. metadata : A dictionary of metadata associated with the file. customKeys : A dictionary of custom keys associated with the file.

Example Usage:

from nim_core.nim_api import find_files

# Example: searching for files under shot parent=SHOT, parentID=11034
response = find_files(parent='SHOT', parentID=11034)

for file_info in response:
    print(f"File ID: {file_info.get('ID')}, Filename: {file_info.get('filename')}")

Example Response:

[
    {
        "ID": 33874,
        "class": "SHOT",
        "parentID": 11034,
        "serverID": 25,
        "task_type": "",
        "task_type_ID": 9,
        "task_type_folder": "COMP",
        "basename": "SH_010_COMP",
        "filename": "SH_010_COMP_v01.nk",
        "filepath": "/path/to/SH_010_COMP/",
        "ext": ".nk",
        "version": 1,
        "isPublished": 0,
        "isWorking": 1,
        "note": "",
        "userID": 1,
        "username": "john.doe",
        "date": "2020-02-27 14:57:32",
        "metadata": "{}",
        "customKeys": {
            "Status": ""
        }
    }
]

Elements

Get Element Types

get_elementTypes(nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns the full list of element types.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The ID of the element type. name : The name of the element type.

Example Usage:

from nim_core.nim_api import get_elementTypes

# Example: retrieving element types
response = get_elementTypes()

for etype in response:
    print(f"Element Type ID: {etype.get('ID')}, Name: {etype.get('name')}")

Example Response:

[
    {
        "ID": 1,
        "name": "COMPS"
    },
    {
        "ID": 4,
        "name": "PLATES"
    },
    {
        "ID": 2,
        "name": "RENDERS"
    }
]

Get Element Type

get_elementType(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Returns the element type name from the ID.

ARGUMENTS

ID integer REQUIRED	The ID of the element.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: name : The name of the element type.

Example Usage:

from nim_core.nim_api import get_elementType

# Example: retrieving the name of the element type with ID=2
response = get_elementType(ID=2)

for elem in response:
    print(f"Element Type Name: {elem.get('name')}")

Example Response:

[
    {
        "name": "RENDERS"
    }
]

Find Elements

find_elements(name: str = '', path: str = '', jobID: str = '', showID: str = '', shotID: str = '', assetID: str = '', taskID: str = '', renderID: str = '', elementTypeID: str = '', ext: str = '', metadata: str = '', nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

A search function for elements. Provided arguments will filter the list of elements.

ARGUMENTS

name string OPTIONAL	Find matching the element name.
path string OPTIONAL	Find matching the element path.
jobID integer OPTIONAL	Find all elements that are children of a job by job ID.
showID integer OPTIONAL	Find all elements that are children of a show by show ID.
shotID integer OPTIONAL	Find all elements that are children of a shot by shot ID.
assetID integer OPTIONAL	Find all elements that are children of an asset by asset ID.
taskID integer OPTIONAL	Find all elements that are associated to a task by task ID.
renderID integer OPTIONAL	Find all elements that are associated to a render by render ID.
elementTypeID integer OPTIONAL	Find all elements with an element type matching the element type ID.
ext string OPTIONAL	Find all elements with a matching file extension.
metadata string OPTIONAL	Find elements with matching metadata. Format: {“Key” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The ID of the element. userID : The ID of the user who created the element. jobID : The ID of the job. assetID : The ID of the asset. shotID : The ID of the shot. taskID : The ID of the task. renderID : The ID of the render. elementTypeID : The ID of the element type. name : The name of the element. path : The path to the element. datetime : The date and time the element was created. startFrame : The start frame of the element. endFrame : The end frame of the element. handles : The handles of the element. padding : The padding of the element. isPublished : Indicates if the element is published. 1 = Published 0 = Not Published metadata : A dictionary of metadata associated with the element.

Example Usage:

from nim_core.nim_api import find_elements

# Example: searching for elements with a matching assetID and file extension
response = find_elements(assetID='816', ext='.wav')

for elem in response:
    print(f"Element ID: {elem.get('ID')}, Name: {elem.get('name')}")

Example Response:

[
    {
        "ID": 8026,
        "userID": 1,
        "jobID": null,
        "assetID": 816,
        "shotID": null,
        "taskID": null,
        "renderID": null,
        "elementTypeID": 7,
        "name": "sound_ref.wav",
        "path": "/path/to/elements/",
        "datetime": "2021-05-24 22:03:15",
        "startFrame": 1,
        "endFrame": 250,
        "handles": 0,
        "padding": 0,
        "isPublished": 0,
        "metadata": "{}"
    }
]

Get Elements

get_elements(parent: str = 'shot', parentID: int = None, elementTypeID: int = None, getLastElement: bool = False, isPublished: bool = False, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves all elements for a particular type given a parent type and ID.

Note

If elementTypeID is not provided, the query will return elements for all types.

ARGUMENTS

parent string REQUIRED	Parent item of the element. Possible values: shot, asset, task, render.
parentID integer REQUIRED	ID of the parent item.
elementTypeID integer OPTIONAL	ID of the element type.
getLastElement boolean OPTIONAL default: False	Return only the last published element. True = Return only the last published element False = Return all elements
isPublished boolean OPTIONAL default: False	Return only the published elements. True = Return only published elements False = Return all elements
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The ID of the element. userID : The ID of the user who created the element. jobID : The ID of the job. assetID : The ID of the asset. shotID : The ID of the shot. taskID : The ID of the task. renderID : The ID of the render. elementTypeID : The ID of the element type. elementType : The name of the element type. name : The name of the element. path : The path to the element. datetime : The date and time the element was created. startFrame : The start frame of the element. endFrame : The end frame of the element. handles : The handles of the element. padding : The padding of the element. full_path : The full path to the element. isPublished : Indicates if the element is published. 1 = Published 0 = Not Published

Example Usage:

from nim_core.nim_api import get_elements

# Example: retrieving the last published elements for a render with ID=3330
response = get_elements(parent="render", parentID=3330, getLastElement=True, isPublished=True)

for elem in response:
    print(f"Element ID: {elem.get('ID')}, Name: {elem.get('name')}")

Example Response:

[
    {
        "ID": 6527,
        "userID": 1,
        "jobID": null,
        "assetID": null,
        "shotID": null,
        "taskID": null,
        "renderID": 3330,
        "elementTypeID": 1,
        "elementType": "COMPS",
        "name": "SH_01_FX_v04.#####.exr",
        "path": "/path/to/RENDER",
        "datetime": "2018-02-14 05:42:59",
        "startFrame": 1,
        "endFrame": 150,
        "handles": 8,
        "padding": 0,
        "full_path": "/path/to/RENDER/SH_01_FX_v04.#####.exr",
        "isPublished": 1
    }
]

Add Element

add_element(parent: str = 'shot', parentID: int = None, userID: int = None, typeID: str = '', path: str = '', name: str = '', startFrame: int = None, endFrame: int = None, handles: int = None, isPublished: bool = False, metadata: str = '', nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds an element to an asset, shot, task, or render.

ARGUMENTS

parent string REQUIRED default: shot	Parent of the element. Possible values: shot, asset, task, render.
parentID integer REQUIRED	ID of the parent object.
userID integer OPTIONAL	ID of the user who created the element.
typeID integer REQUIRED	ID of the element type to associate with the element.
path string REQUIRED	Folder path to the element.
name string REQUIRED	Name of the element.
startFrame integer OPTIONAL	If a sequence, this is the start frame.
endFrame integer OPTIONAL	If a sequence, this is the end frame.
handles integer OPTIONAL	If a sequence, this is the handle length.
isPublished boolean OPTIONAL default: False	Should element be flagged as published. True = Published False = Not Published
metadata string OPTIONAL	Dictionary of metadata (Internal). Format: {“Key” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

result boolean	Indicates whether the operation was successful.
ID string	The ID of the newly created element.
error string	Contains any error messages if result is false.

Example Usage:

from nim_core.nim_api import add_element

# Example: adding an element to an asset with ID=816, of element type ID=7
response = add_element(
    parent='asset',
    parentID=816,
    typeID='7',
    path='/path/to/elements/',
    name='sound_ref.wav'
)

if response.get("result"):
    print(f"Element created successfully with ID: {response.get('ID')}")
else:
    print(f"Error: {response.get('error')}")

Example Response:

{
    "result": true,
    "ID": "1234",
    "error": ""
}

Update Element

update_element(ID: int = None, userID: int = None, jobID: int = None, assetID: int = None, shotID: int = None, taskID: int = None, renderID: int = None, elementTypeID: int = None, name: str = None, path: str = None, startFrame: int = None, endFrame: int = None, handles: int = None, isPublished: bool = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing element by element ID.

ARGUMENTS

ID integer REQUIRED	The ID of the element to update.
userID integer OPTIONAL	The ID of the user.
jobID integer OPTIONAL	The ID of the job.
assetID integer OPTIONAL	The ID of the asset.
shotID integer OPTIONAL	The ID of the shot.
taskID integer OPTIONAL	The ID of the task.
renderID integer OPTIONAL	The ID of the render.
elementTypeID integer OPTIONAL	The ID of the element type.
name string OPTIONAL	The name of the element.
path string OPTIONAL	The path to the element.
startFrame integer OPTIONAL	The start frame of the element.
endFrame integer OPTIONAL	The end frame of the element.
handles integer OPTIONAL	The handles of the element.
isPublished boolean OPTIONAL default: False	Indicates if the element should be flagged as published. True = Published False = Not Published
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean

Indicates whether the operation was successful.

Example Usage:

from nim_core.nim_api import update_element

# Example: updating an element with ID=8026, changing its name
response = update_element(ID=8026, name="sound_ref_updated.wav")

if response.get("success"):
    print("Element updated successfully.")
else:
    print("Failed to update element.")

Example Response:

{
    "success": true
}

Delete Element

delete_element(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an existing element by element ID.

ARGUMENTS

ID integer REQUIRED	The ID of the element to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import delete_element

# Example: deleting an element with ID=8026
response = delete_element(ID=8026)

if response.get("success"):
    print("Element deleted successfully.")
else:
    print(f"Failed to delete element. Error: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": ""
}

Render

Add Render

add_render(jobID: int = 0, itemType: str = 'shot', taskID: int = 0, fileID: int = 0, renderKey: str = '', renderName: str = '', renderType: str = '', renderComment: str = '', outputDirs: list = None, outputFiles: list = None, elementTypeID: int = 0, start_datetime: str = None, end_datetime: str = None, avgTime: str = '', totalTime: str = '', frame: int = 0, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Logs a render to a given taskID.

ARGUMENTS

jobID integer OPTIONAL	ID of the job to log the render.
itemType string REQUIRED default: shot	Determines if the render is associated with an asset or shot. Possible values: asset, shot.
taskID integer REQUIRED	ID of the task to log the render.
fileID integer OPTIONAL	ID of a file to associate with the render.
renderKey string OPTIONAL	Unique key for render to link to external database or render management software.
renderName string OPTIONAL	Name of the render.
renderType string OPTIONAL	Type of render. When used with Deadline Render Manager, values could be mayaPlugin, nukePlugin, etc.
renderComment string OPTIONAL	Comment to add to the render.
outputDirs json array OPTIONAL	Array of output directories from the render.
outputFiles json array OPTIONAL	Array of output files from the render.
elementTypeID integer OPTIONAL	ID of the element type to use for the render.
start_datetime datetime OPTIONAL	Datetime value for the start of the render.
end_datetime datetime OPTIONAL	Datetime value for the end of the render.
avgTime string OPTIONAL	Average time of the render.
totalTime string OPTIONAL	Total time of the render.
frame integer OPTIONAL	The total frame count of the render.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.
ID string	The ID of the newly created render.

Example Usage:

from nim_core.nim_api import add_render

# Example: adding a render for taskID=123, with a name and comment
response = add_render(
    taskID=123,
    renderName="TestRender",
    renderComment="Testing new render setup"
)

if response.get("success"):
    print(f"Render created successfully with ID: {response.get('ID')}")
else:
    print(f"Error: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": "",
    "ID": "1234"
}

Upload Render Icon

upload_renderIcon(renderID: int = None, renderKey: str = '', img: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Uploads an icon for a render.

ARGUMENTS

renderID integer OPTIONAL	ID of the render to add the icon. Required if renderKey is not passed.
renderKey string OPTIONAL	RenderKey of the render to add the icon. Required if renderID is not passed.
img string REQUIRED	Local file path to the icon file to upload.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.
iconPath string	The path to the uploaded icon.

Example Usage:

from nim_core.nim_api import upload_renderIcon

# Example: uploading a render icon from a local file path
response = upload_renderIcon(renderID=5678, img="/path/to/icon.jpg")

if response["success"]:
    print(f"Render icon uploaded successfully. Icon path: {response['iconPath']}")
else:
    print(f"Error uploading render icon: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "iconPath": "media/jobs/1234/render/5678/icon/render_icon.jpg"
}

Get Last Shot Render

get_lastShotRender(shotID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the latest render for a shot.

ARGUMENTS

shotID integer REQUIRED	ID of the shot to retrieve the last render.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the render.
jobID integer	The ID of the associated job.
class string	The class of the render.
taskID integer	The ID of the associated task.
fileID integer	The ID of the associated file.
userID integer	The ID of the user who created the render.
renderKey string	The render key.
renderName string	The name of the render.
renderType string	The type of the render.
comment string	The comment for the render.
date datetime	The date of the render.
outputDirs json array	The output directories of the render.
outputFiles json array	The output files of the render.
frames integer	The total frame count of the render.
start_datetime datetime	The start datetime of the render.
end_datetime datetime	The end datetime of the render.
avgTime string	The average time of the render.
totalTime string	The total time of the render.
iconPath string	The path to the render icon.

Example Usage:

from nim_core.nim_api import get_lastShotRender

# Example: retrieving the latest render for a shot with ID=1234
response = get_lastShotRender(shotID=1234)

if response:
    for render_info in response:
        print(f"Last render ID: {render_info.get('ID')}, Name: {render_info.get('renderName')}")
else:
    print("No render data returned.")

Example Response:

[
    {
        "ID": 3645,
        "jobID": null,
        "class": null,
        "taskID": 22680,
        "fileID": null,
        "userID": 1,
        "renderKey": null,
        "deadlineID": null,
        "renderName": "My Render",
        "renderType": null,
        "comment": null,
        "date": "2025-02-21 23:51:24",
        "outputDirs": null,
        "outputFiles": null,
        "frames": null,
        "start_datetime": null,
        "end_datetime": null,
        "avgTime": null,
        "totalTime": null,
        "iconPath": null
    }
]

Review

Get Review Item Types

get_reviewItemTypes(nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves the ID and name for all review item types.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list	A list of dictionaries. Each dictionary includes: ID : The ID of the review item type name : The name of the review item type

Example Usage:

from nim_core.nim_api import get_reviewItemTypes

# Example: retrieving all review item types
response = get_reviewItemTypes()

for item_type in response:
    print(f"Item Type ID: {item_type.get('ID')}, Name: {item_type.get('name')}")

Example Response:

[
    {
        "ID": 1,
        "name": "Review"
    },
    {
        "ID": 2,
        "name": "Edit"
    },
    {
        "ID": 3,
        "name": "Reference"
    }
]

Get Review Item Statuses

get_reviewStatuses(nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves available review item statuses.

ARGUMENTS

nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any generated error messages if success is false.
data list	A list of dictionaries. Each dictionary includes: ID : The ID of the review item status. name : The name of the review item status. priority : The priority of the review item status. bgcolor : The background color of the review item status. textcolor : The text color of the review item status.

Example Usage:

from nim_core.nim_api import get_reviewStatuses

response = get_reviewStatuses()

if response["success"]:
    for status in response["data"]:
        print(f"Review Status: {status['name']} (ID: {status['ID']})")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 2,
            "name": "Approved",
            "priority": 2,
            "bgcolor": "#65a467",
            "textcolor": "#000000"
        },
        {
            "ID": 3,
            "name": "Ready for Posting",
            "priority": 0,
            "bgcolor": "#6c546f",
            "textcolor": "#ffffff"
        }
    ]
}

Get Task Review Items

get_taskReviewItems(taskID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves review items for the specified taskID.

ARGUMENTS

taskID integer REQUIRED	ID of the task to retrieve review items.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The unique identifier for the review item. name : The name of the review item. filepath : The filepath to the review item. iconPath : The path to the review icon. dailiesMP4 : The path of the source mp4 if available. 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. comment : The text of the render comment.

Example Usage:

from nim_core.nim_api import get_taskReviewItems

# Example: retrieving review items for taskID=1234
response = get_taskReviewItems(taskID=1234)

if response:
    for review_item in response:
        print(f"Review Item ID: {review_item.get('ID')}, Name: {review_item.get('name')}")
else:
    print("No review items returned.")

Example Response:

[
    {
        "ID": 4665,
        "name": "SH_01_FX_v04",
        "filepath": null,
        "iconPath": "/media/jobs/4557/review/render/3330/202105/a249233b_icon.jpg",
        "dailiesMP4": "media/jobs/4557/review/render/3330/202105/a249233b_icon.mp4",
        "submitted": 0,
        "renderID": 3330,
        "renderName": "SH_01_FX_v04.mp4",
        "frames": "150",
        "avgTime": null,
        "totalTime": null,
        "renderDate": "2018-02-12 21:36:11",
        "renderIconPath": "/media/jobs/4557/dailies/17789/436db3df_icon.jpg",
        "comment": ""
    }
]

Upload Review Item

upload_reviewItem(taskID: int = None, renderID: int = None, renderKey: str = None, itemID: int = None, itemType: str = None, path: str = None, name: str = None, description: str = None, reviewItemTypeID: int = 0, reviewItemStatusID: int = 0, keywords: list = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Uploads a review item to a given context.

Note

The uploaded file must be an image, PDF, or video.

ARGUMENTS

taskID integer OPTIONAL	The task ID to associate with the review item. If taskID is passed, a new render will be created to associate with the review item This argument exists to maintain legacy compatibility. It is recommended to use the itemType and itemID argument instead.
renderID integer OPTIONAL	Used to associate with an existing render. This argument exists to maintain legacy compatibility. It is recommended to use the itemType and itemID argument instead.
renderKey string OPTIONAL	Used to associate with a logged render from a render manager. This can be used instead of the render ID. In the case of Deadline, this would be the Deadline job ID.
itemID integer REQUIRED	ID of the parent item.
itemType string REQUIRED	The type of parent item. Valid values: user, job, show, shot, task, render.
path string REQUIRED	The path to the file to upload.
name string OPTIONAL	The name of the review item.
description string OPTIONAL	The description of the review item.
reviewItemTypeID integer OPTIONAL	The ID for the review item type.
reviewItemStatusID integer OPTIONAL	The ID for the review item status.
keywords list OPTIONAL	An array of keywords to associate. Format: [“keyword1”,”keyword2”]
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
ID string	The ID of the newly created review item.
itemType string	The type of the parent item.
itemID string	The ID of the parent item.
mediaType string	The type of the media (e.g., image, pdf, video).

Example Usage:

from nim_core.nim_api import upload_reviewItem

# Example: uploading a review item to a task with ID=22679, with name and description
response = upload_reviewItem(
    itemID=22679,
    itemType="task",
    name="ReviewItemName",
    description="My new review item"
    # path could be used internally to supply a local file path
)

if response.get("success"):
    print(f"Review item created with ID: {response.get('ID')}")
else:
    print(f"Error: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": "",
    "ID": "5170",
    "itemType": "task",
    "itemID": "22679",
    "mediaType": "video"
}

Upload Review Note

upload_reviewNote(ID: int = None, name: str = '', img: str = None, note: str = '', frame: int = 0, time: int = - 1, userID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Uploads a note to an existing review item with an optional associated image.

Note

The uploaded file must be an image.

ARGUMENTS

ID integer REQUIRED	ID of the review item to add the note.
name string OPTIONAL	The name of the note.
img string OPTIONAL	Local file path to the image for the note.
note string OPTIONAL	The text of the note.
frame integer OPTIONAL default: 0	Frame number to associate with the note.
time string OPTIONAL default: -1	Time in the movie to associate with the note. If this note is not frame specific, -1 can be used.
userID integer REQUIRED	User ID of the note owner.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true, false
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import upload_reviewNote

# Example: uploading a note with an image to review item ID=1234, userID=5678
response = upload_reviewNote(
    ID=1234,
    userID=5678,
    name="NoteName",
    note="This is a note text",
    frame=100,
    time=100,
    img="/path/to/image.jpg"
)

if response.get("success"):
    print("Review note uploaded successfully.")
else:
    print(f"Error uploading review note: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": ""
}

Get Review Items

get_reviewItems(parentType: str = None, parentID: int = None, allChildren: int = None, name: str = None, description: str = None, date: str = None, type: str = None, typeID: int = None, status: str = None, statusID: int = None, keyword: str = None, keywordID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the child review items and details for the given parent item.

Note

• type or typeID can be used to filter the returned review items by the given review type name or review type ID.

• status or statusID can be used to filter the returned review items by the given status name or review status ID.

• keyword or keywordID can be used to filter the returned review items by the given keyword name or review keyword ID.

ARGUMENTS

parentType string REQUIRED	The type of the parent item. Valid values: user, job, dev, asset, show, shot, task, render.
parentID integer REQUIRED	The ID of the parent item.
allChildren integer OPTIONAL	Determines if review items associated with child items should be returned. For example, if parentType is a show, setting this to 1 would return review items on the show as well as child shots, tasks, and renders. Possible values: 0 (no) or 1 (yes).
name string OPTIONAL	Filters the returned review items by the given name.
description string OPTIONAL	Filters the returned review items to items that contain the given string.
date date OPTIONAL	Filters the returned review items by the given date. Format: yyyy-mm-dd
typeID integer OPTIONAL	Filters the returned review items by the given review type ID.
type string OPTIONAL	Filters the returned review items by the given review type name.
statusID integer OPTIONAL	Filters the returned review items by the given review status ID.
status string OPTIONAL	Filters the returned review items by the given review status name.
keywordID integer OPTIONAL	Filters the returned review items by the given review keyword ID.
keyword string OPTIONAL	Filters the returned review items by the given review keyword name.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true, false
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of dictionaries. Each dictionary includes: 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 associated review item type ID. reviewItemType : The name of the review item type. reviewItemGroupID : The group ID for review items belonging to a set of versions. reviewItemStatusID : The associated review item status ID. reviewItemStatus : The name of the review item status. 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 : The width of the media. height : The 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 creator’s user ID. creatorFullName : The creator’s full name. itemType : The type of parent this review item is associated with. itemID : The ID of the parent item. mediaType : The type of media (e.g., image, pdf, video). mediaPath : The path to the uploaded media. keywordIDs : The IDs of the associated keywords. keywords : The names of the associated keywords.

Example Usage:

from nim_core.nim_api import get_reviewItems

# Example: retrieving review items for an asset with ID=1, including all child items
response = get_reviewItems(parentType="asset", parentID=1, allChildren=1)

if response["success"]:
    for item in response["data"]:
        print(f"Review Item ID: {item.get('ID')}, Name: {item.get('name')}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 5159,
            "renderKey": null,
            "name": "Car Review Item",
            "description": null,
            "reviewItemTypeID": 1,
            "reviewItemGroupID": 0,
            "reviewItemStatusID": 3,
            "iconPath": "/media/jobs/5083/review/job/202501/2b09333a_icon.jpg",
            "mp4": null,
            "ogv": null,
            "webm": null,
            "filmstrip": "",
            "width": 960,
            "height": 640,
            "duration": "0.000000000000",
            "frames": 0,
            "frame_rate": "0.000000000000",
            "date": "2025-01-28 18:22:26",
            "creatorUserID": 1,
            "itemType": "job",
            "itemID": 5083,
            "mediaType": "image",
            "mediaPath": "media/jobs/5083/review/job/202501/2b09333a_icon.png",
            "keywordIDs": "4",
            "keywords": "Cars",
            "reviewItemType": "Edit",
            "reviewItemStatus": "Ready for Posting",
            "creatorFullName": "John Doe"
        }
    ]
}

Get Review Item

get_reviewItem(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns the details for the given review item ID.

ARGUMENTS

ID integer REQUIRED	ID of the review item.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true, false
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
data dictionary	A dictionary containing the details of the review item including: 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 associated review item type ID. reviewItemType : The name of the review item type. reviewItemGroupID : The group ID for review items belonging to a set of versions. reviewItemStatusID : The associated review item status ID. reviewItemStatus : The name of the review item status. 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 : The width of the media. height : The 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 creator’s user ID. creatorFullName : The creator’s full name. itemType : The type of parent this review item is associated with. itemID : The ID of the parent item. mediaType : The type of media (e.g., image, pdf, video). mediaPath : The path to the uploaded media. keywordIDs : The IDs of the associated keywords. keywords : The names of the associated keywords.

Example Usage:

from nim_core.nim_api import get_reviewItem

# Example: retrieving details for review item with ID=5159
response = get_reviewItem(ID=5159)

if response["success"]:
    review_data = response.get("data", {})
    print(f"Review Item Name: {review_data.get('name')}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": {
        "ID": 5159,
        "renderKey": null,
        "name": "example_review_item",
        "description": null,
        "reviewItemTypeID": 1,
        "reviewItemType": "Daily",
        "reviewItemGroupID": 0,
        "reviewItemStatusID": 3,
        "reviewItemStatus": "Ready for Posting",
        "iconPath": "/media/jobs/5083/review/job/202501/example_icon.jpg",
        "mp4": null,
        "ogv": null,
        "webm": null,
        "filmstrip": "",
        "width": 960,
        "height": 640,
        "duration": "0.000000000000",
        "frames": 0,
        "frame_rate": "0.000000000000",
        "date": "2025-01-28 18:22:26",
        "creatorUserID": 1,
        "creatorFullName": "John Doe",
        "itemType": "job",
        "itemID": 5083,
        "mediaType": "image",
        "mediaPath": "media/jobs/5083/review/job/202501/example_image.png",
        "keywordIDs": "4",
        "keywords": "example_keyword"
    }
}

Get Review Item Notes

get_reviewItemNotes(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns all notes for a given review item ID.

ARGUMENTS

ID integer REQUIRED	ID of the review item.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true, false
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of dictionaries. Each dictionary includes: ID : The ID of the note. type : The type of the note. item_ID : The ID of the review item. date : The date the note was created. user_ID : The ID of the user who created the note. user_full_name : The full name of the user who created the note. subject : The subject of the note. note : The text of the note. isHTML : Indicates if the note is in HTML format. 0 = no 1 = yes renderID : The ID of the associated render. img_path : The path to the image associated with the note. note_img_path : The path to the note annotation image (a transparent image that can be overlaid on the review item). frame : The frame number associated with the note. time : The time associated with the note. parentID : The ID of the parent note if this is a reply. isAddressed : Indicates if the note has been addressed. 0 = no 1 = yes

Example Usage:

from nim_core.nim_api import get_reviewItemNotes

# Example: retrieving notes for review item with ID=5159
response = get_reviewItemNotes(ID=5159)

if response["success"]:
    for note_data in response["data"]:
        print(f"Note ID: {note_data.get('ID')}, Text: {note_data.get('note')}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 13166,
            "type": "dailies",
            "item_ID": 5159,
            "date": "2025-01-28 18:30:19",
            "user_ID": 1,
            "subject": "",
            "note": "",
            "isHTML": 0,
            "renderID": 0,
            "img_path": "/media/jobs/5159/review/job/202501/notes/example_image.jpg",
            "note_img_path": "/media/jobs/5159/review/job/202501/notes/example_note_annotation.png",
            "frame": 1,
            "time": 0,
            "parentID": null,
            "isAddressed": 0,
            "user_full_name": "John Doe"
        }
    ]
}

Get Review Bins

get_reviewBins(context: str = None, contextID: int = None, limit: int = 0, offset: int = 0, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Returns all review bins and their items within a specific context.

ARGUMENTS

context string REQUIRED	The context of the review for which you want to retrieve bins. Valid options are user, job, dev, asset, show, and shot. user sets the context to the user dashboard review. When API Keys are required, contextID must be the same as the API user’s userID, and the user must have the viewDashboardReview permission unless they are a root user. When the dev context is used, set the contextID to the corresponding job ID.
contextID integer REQUIRED	The ID of the context item.
limit integer OPTIONAL default: 0	Maximum rows to return. 0 = no limit
offset integer OPTIONAL default: 0	Number of rows to skip before returning.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
total_count integer	The total number of rows that match the search criteria.
data dict	A dictionary containing details of review bins. Each bin is a dictionary with the following keys: ID : The unique identifier of the bin name : The name of the bin creationDate : Timestamp when the bin was created createdByUserID : ID of the user who created the bin createdByFullName : Full name of the user who created the bin modifiedDate : Timestamp of the bin’s most recent update modifiedByUserID : ID of the user who most recently updated the bin modifiedByFullName : Full name of the user who most recently updated the bin autoUpdateVersions : A flag indicating if version updates happen automatically. 1 for true, 0 for false. reviewItems : A list of review items within the bin. Each item is a dictionary containing: ID : Unique item identifier name : Name or label for the review item creationDate : Timestamp when the review item was created createdByUserID : ID of the user who created the item createdByFullName : Name of the user who created the item position : The item’s position in the bin

Example Usage:

from nim_core.nim_api import get_reviewBins

response = get_reviewBins(context="job", contextID=1, limit=10, offset=0)

if response["success"]:
    for bin_data in response["data"]:
        print(f"Bin Name: {bin_data['name']}, Created By: {bin_data['createdByFullName']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": "",
    "total_count": 1,
    "data": [
        {
            "ID": 10,
            "name": "Test Bin",
            "creationDate": "2025-02-03 12:00:00",
            "createdByUserID": 2,
            "createdByFullName": "John Doe",
            "modifiedDate": "2025-02-04 15:30:00",
            "modifiedByUserID": 3,
            "modifiedByFullName": "Jane Smith",
            "autoUpdateVersions": 0,
            "reviewItems": [
                {
                    "ID": 100,
                    "name": "First Review Item",
                    "creationDate": "2025-02-03 12:30:00",
                    "createdByUserID": 2,
                    "createdByFullName": "John Doe",
                    "position": 1
                }
            ]
        }
    ]
}

Add Review Bin

add_reviewBin(context: str = None, contextID: int = None, name: str = None, autoUpdateVersions: int = 0, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Creates a new review bin for a specific context and returns the ID of the newly created bin.

ARGUMENTS

context string REQUIRED	The context in which to create a new review bin. Valid options are user, job, dev, asset, show, and shot. user sets the context to the user dashboard review. When API Keys are required, contextID must be the same as the API user’s userID, and the user must have the viewDashboardReview permission unless they are a root user. When the dev context is used, set the contextID to the corresponding job ID.
contextID integer REQUIRED	The ID of the context item.
name string REQUIRED	The name of the review bin.
autoUpdateVersions integer OPTIONAL default: 0	Flag to automatically update versions in the bin when new versions are added. 1 = Automatically update versions 0 = Do not update versions
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.
data dict	A dictionary containing the ID of the newly created bin: ID : The unique identifier of the new bin

Example Usage:

from nim_core.nim_api import add_reviewBin

response = add_reviewBin(context="job", contextID=1, name="Test Bin")

if response["success"]:
    print(f"New Review Bin ID: {response['data']['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": "",
    "data": {
        "ID": 10
    }
}

Update Review Bin

update_reviewBin(ID: int = None, name: str = None, autoUpdateVersions: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing review bin with new values for name and/or auto-update settings.

ARGUMENTS

ID integer REQUIRED	The ID of the review bin to update.
name string OPTIONAL	The new name of the review bin.
autoUpdateVersions integer OPTIONAL	Flag to automatically update versions in the bin when new versions are added. 1 = Automatically update versions 0 = Do not update versions
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import update_reviewBin

response = update_reviewBin(ID=1, name="Test Bin", autoUpdateVersions=1)

if response["success"]:
    print("Review bin updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Delete Review Bin

delete_reviewBin(ID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an existing review bin.

ARGUMENTS

ID integer REQUIRED	The ID of the review bin to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_reviewBin

response = delete_reviewBin(ID=1)

if response["success"]:
    print("Review bin deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Add Review Bin Item

add_reviewBinItem(binID: int = None itemID: int = None, position: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds an existing review item to a review bin.

ARGUMENTS

binID integer REQUIRED	The ID of the review bin to update.
itemID integer REQUIRED	The ID of the review item to add to the bin. The review item must be associated with the same context as the review bin.
position integer OPTIONAL	The position to place the review item in the bin. Valid values are 1 or greater. If the position is greater than the number of review items in the bin, the review item is placed at the end of the bin. If not provided, the review item is added to the end of the bin.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import add_reviewBinItem

response = add_reviewBinItem(binID=1, itemID=1, position=1)

if response["success"]:
    print("Review item added successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Position Review Bin Item

position_reviewBinItem(binID: int = None, itemID: int = None, position: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Moves a review item to a new position in a review bin.

ARGUMENTS

binID integer REQUIRED	The ID of the review bin to update.
itemID integer REQUIRED	The ID of the review item to move.
position integer REQUIRED	The position to place the review item in the bin. Valid values are 1 or greater. If the position is greater than the number of review items in the bin, the review item is placed at the end of the bin.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import position_reviewBinItem

response = position_reviewBinItem(binID=1, itemID=1, position=2)

if response["success"]:
    print("Review item repositioned successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Remove Review Bin Item

remove_reviewBinItem(binID: int = None, itemID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Removes a review item from a review bin. This does not delete the review item; it is simply removed from the bin.

ARGUMENTS

binID integer REQUIRED	The ID of the review bin containing the review item.
itemID integer REQUIRED	The ID of the review item to remove.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any generated error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import remove_reviewBinItem

response = remove_reviewBinItem(binID=1, itemID=1)

if response["success"]:
    print("Review item removed successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": True,
    "error": ""
}

Timecards

Get Timecards

get_timecards(startDate: str = None, endDate: str = None, jobID: int = None, userID: int = None, username: str = None, taskTypeID: int = None, taskType: str = None, taskID: int = None, locationID: int = None, location: str = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → list

Retrieves a timecard, or array of timecards, based on search criteria.

Note

• A user can be passed by either username or userID. If both are passed the userID will be used.

• A task type 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 jobID is provided, the startDate and endDate are not required.

• If jobID is not provided, both startDate and endDate must be provided.

ARGUMENTS

startDate date OPTIONAL	The start date for the timecard search. Format: yyyy-mm-dd Required if jobID is not provided.
endDate date OPTIONAL	The end date for the timecard search. Format: yyyy-mm-dd Required if jobID is not provided.
jobID integer OPTIONAL	The ID of the job. Required if startDate and endDate are not provided.
userID integer OPTIONAL	The ID of the user.
username string OPTIONAL	The username of the user.
taskTypeID integer OPTIONAL	The ID of the task type.
taskType string OPTIONAL	The name of the task type.
taskID integer OPTIONAL	The ID of the task.
locationID integer OPTIONAL	The ID of the location.
location string OPTIONAL	The name of the location.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

list

A list of dictionaries. Each dictionary includes: ID : The ID of the timecard. date : The date of the timecard. userID : The ID of the user. username : The username of the user. user_full_name : The full name of the user. start_time : The start time of the timecard. end_time : The end time of the timecard. hrs : The total hours worked. break_hrs : The break hours. total_hrs : The total hours including breaks. ot : The overtime hours. dt : The double time hours. jobID : The ID of the job. jobnumber : The job number. jobname : The job name. taskTypeID : The ID of the associated task type. taskType : The name of the associated task type. taskID : The ID of the associated task. locationID : The ID of the associated location. location : The name of the associated location. description : The description of the work done. submittedID : The ID of the person who the timecard was submitted to. submittee : The name of the person who the timecard was submitted to. submittedTime : The datetime the timecard was submitted. approverID : The ID of the person who approved the timecard. approver : The name of the person who approved the timecard. approvalTime : The datetime the timecard was approved. disputedID : The ID of the person who disputed the timecard. disputer : The name of the person who disputed the timecard. disputedTime : The datetime the timecard was disputed. disputedNote : The note explaining the dispute. status : The status of the timecard. customKeys : An array of custom keys.

Example Usage:

from nim_core.nim_api import get_timecards

# Example: retrieving timecards by date range
response = get_timecards(startDate="2017-11-30", endDate="2017-12-01")

if isinstance(response, list):
    for tc in response:
        print(f"Timecard ID: {tc.get('ID')}, Date: {tc.get('date')}")
else:
    print("No timecard data returned.")

Example Response:

[
    {
        "ID": 1234,
        "date": "2017-11-30",
        "userID": 123,
        "username": "john.doe",
        "user_full_name": "John Doe",
        "start_time": "09:00:00",
        "end_time": "17:00:00",
        "hrs": "8.00",
        "break_hrs": "0.00",
        "total_hrs": "8.00",
        "ot": "0.00",
        "dt": "0.00",
        "jobID": 0,
        "jobnumber": null,
        "jobname": null,
        "taskTypeID": 18,
        "taskType": "EDIT",
        "taskID": 0,
        "locationID": 2,
        "location": "Los Angeles",
        "description": "",
        "submittedID": 0,
        "submittee": null,
        "submittedTime": null,
        "approverID": 0,
        "approver": null,
        "approvalTime": null,
        "disputedID": 0,
        "disputer": null,
        "disputedTime": null,
        "disputedNote": "",
        "status": "NOT SUBMITTED",
        "customKeys": []
    }
]

Add Timecards

add_timecard(date: str = None, userID: int = None, username: str = None, jobID: int = None, taskTypeID: int = None, taskType: str = None, taskID: int = None, startTime: str = None, endTime: str = None, hrs: float = None, breakHrs: float = None, ot: float = None, dt: float = None, locationID: int = None, location: str = None, description: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Adds a new timecard.

Note

• A user can be passed by either username or userID. If both are passed the userID will be used.

• A task type 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 task’s values will override userID, jobID, and taskTypeID.

ARGUMENTS

date date REQUIRED	The date of the timecard. Format: YYYY-MM-DD
userID integer OPTIONAL	The ID of the user to associate with the timecard.
username string OPTIONAL	The username of the user to associate with the timecard.
jobID integer OPTIONAL	The ID of the job to associate with the timecard.
taskTypeID integer OPTIONAL	The ID of the task type to associate with the timecard.
taskType string OPTIONAL	The name of the task type to associate with the timecard.
taskID integer OPTIONAL	The ID of the task to associate with the timecard. If provided, overrides userID, jobID, and taskTypeID with values from the task.
startTime string OPTIONAL	The start time of the timecard. Range: 00:00:00 to 23:59:59
endTime string OPTIONAL	The end time of the timecard. Range: 00:00:00 to 23:59:59
hrs decimal OPTIONAL	The total hours worked, including break hours, overtime, and double time. Maximum value: 24
breakHrs decimal OPTIONAL	The break hours. Value must be less than hrs.
ot decimal OPTIONAL	The overtime hours. Value must be less than hrs - breakHrs The default label in the UI for this field is Overtime 1. The label can be changed in the UI.
dt decimal OPTIONAL	The double time hours. Value must be less than hrs - (breakHrs + ot) The default label in the UI for this field is Overtime 2. The label can be changed in the UI.
locationID integer OPTIONAL	The ID of the location to associate with the timecard.
location string OPTIONAL	The name of the location to associate with the timecard.
description string OPTIONAL	The description of the work done.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID string	The ID of the newly created timecard.
success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import add_timecard

# Example: adding a timecard for userID=123 on date=2017-11-30
response = add_timecard(
    date="2017-11-30",
    userID=123,
    startTime="09:00:00",
    endTime="17:00:00",
    hrs=8.0
)

if response["success"]:
    print(f"New timecard created. ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": "1234",
    "success": true,
    "error": ""
}

Update Timecard

update_timecard(timecardID: int = None, date: str = None, userID: int = None, username: str = None, jobID: int = None, taskTypeID: int = None, taskType: str = None, taskID: int = None, startTime: str = None, endTime: str = None, hrs: float = None, breakHrs: float = None, ot: float = None, dt: float = None, locationID: int = None, location: str = None, description: str = None, customKeys: dict = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Updates an existing timecard.

Note

• A user can be passed by either username or userID. If both are passed the userID will be used.

• A task type 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 task’s values will override userID, jobID, and taskTypeID.

ARGUMENTS

timecardID integer REQUIRED	The ID of the timecard to update.
date date OPTIONAL	The date of the timecard. Format: YYYY-MM-DD
userID integer OPTIONAL	The ID of the user to associate with the timecard.
username string OPTIONAL	The username of the user to associate with the timecard.
jobID integer OPTIONAL	The ID of the job to associate with the timecard.
taskTypeID integer OPTIONAL	The ID of the task type to associate with the timecard.
taskType string OPTIONAL	The name of the task type to associate with the timecard.
taskID integer OPTIONAL	The ID of the task to associate with the timecard. If provided, overrides userID, jobID, and taskTypeID with values from the task.
startTime string OPTIONAL	The start time of the timecard. Range: 00:00:00 to 23:59:59
endTime string OPTIONAL	The end time of the timecard. Range: 00:00:00 to 23:59:59
hrs decimal OPTIONAL	The total hours worked, including break hours, overtime, and double time. Maximum value: 24
breakHrs decimal OPTIONAL	The break hours. Value must be less than hrs.
ot decimal OPTIONAL	The overtime hours. Value must be less than hrs - breakHrs. The default label in the UI for this field is Overtime 1. The label can be changed in the UI.
dt decimal OPTIONAL	The double time hours. Value must be less than hrs - (breakHrs + ot). The default label in the UI for this field is Overtime 2. The label can be changed in the UI.
locationID integer OPTIONAL	The ID of the location to associate with the timecard.
location string OPTIONAL	The name of the location to associate with the timecard.
description string OPTIONAL	The description of the work done.
customKeys dictionary OPTIONAL	A dictionary of custom keys. Format: {“Custom Key Name” : “Value”}
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID string	The ID of the updated timecard.
success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import update_timecard

# Example: updating an existing timecard with ID=1234 to have new hours
response = update_timecard(
    timecardID=1234,
    date="2017-11-30",
    userID=123,
    startTime="09:00:00",
    endTime="18:00:00",
    hrs=8.5
)

if response["success"]:
    print(f"Timecard {response['ID']} updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": "1234",
    "success": true,
    "error": ""
}

Delete Timecard

delete_timecard(timecardID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Deletes an existing timecard.

ARGUMENTS

timecardID integer REQUIRED	The ID of the timecard to delete.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful.
error string	Contains any error messages if success is false.

Example Usage:

from nim_core.nim_api import delete_timecard

# Example: deleting a timecard with ID=1234
response = delete_timecard(timecardID=1234)

if response.get("success"):
    print("Timecard deleted successfully.")
else:
    print(f"Error deleting timecard: {response.get('error')}")

Example Response:

{
    "success": true,
    "error": ""
}

Get Timecard Info

get_timecardInfo(timecardID: int = None, nimURL: str = None, apiUser: str = None, apiKey: str = None) → dict

Retrieves information for an existing timecard.

ARGUMENTS

timecardID integer REQUIRED	The ID of the timecard to retrieve.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

ID integer	The ID of the timecard.
date date	The date of the timecard.
userID integer	The ID of the user associated with the timecard.
username string	The username of the user associated with the timecard.
user_full_name string	The full name of the user associated with the timecard.
start_time string	The start time of the timecard.
end_time string	The end time of the timecard.
hrs decimal	The total hours worked.
break_hrs decimal	The break hours.
total_hrs decimal	The total hours including breaks.
ot decimal	The overtime hours. The default label in the UI for this field is Overtime 1. The label can be changed in the UI.
dt decimal	The double time hours. The default label in the UI for this field is Overtime 2. The label can be changed in the UI.
jobID integer	The ID of the job associated with the timecard.
jobnumber string	The job number associated with the timecard.
jobname string	The job name associated with the timecard.
taskTypeID integer	The ID of the task type associated with the timecard.
taskType string	The name of the task type associated with the timecard.
taskID integer	The ID of the task associated with the timecard.
locationID integer	The ID of the location associated with the timecard.
location string	The name of the location associated with the timecard.
description string	The description of the work done.
submittedID integer	The ID of the person who the timecard was submitted to.
submittedTime datetime	The datetime the timecard was submitted.
approverID integer	The ID of the person who approved the timecard.
approvalTime datetime	The datetime the timecard was approved.
disputedID integer	The ID of the person who disputed the timecard.
disputedTime datetime	The datetime the timecard was disputed.
disputedNote string	The note explaining the dispute.
approver string	The name of the person who approved the timecard.
submittee string	The name of the person who the timecard was submitted to.
disputer string	The name of the person who disputed the timecard.
status string	The status of the timecard.
customKeys array	An array of custom keys.

Example Usage:

from nim_core.nim_api import get_timecardInfo

# Example: retrieving info for a timecard with ID=1
response = get_timecardInfo(timecardID=1)

if isinstance(response, dict):
    print("Timecard ID:", response.get("ID"))
    print("User:", response.get("username"))
else:
    print("No data returned.")

Example Response:

{
    "ID": 1,
    "date": "2008-01-03",
    "userID": 1,
    "username": "john.doe",
    "user_full_name": "John Doe",
    "start_time": "09:00:00",
    "end_time": "19:00:00",
    "hrs": "10.00",
    "break_hrs": "0.00",
    "total_hrs": "10.00",
    "ot": "0.00",
    "dt": "0.00",
    "jobID": null,
    "jobnumber": null,
    "jobname": null,
    "taskTypeID": null,
    "taskType": null,
    "taskID": 0,
    "locationID": null,
    "location": null,
    "description": null,
    "submittedID": 0,
    "submittedTime": null,
    "approverID": 0,
    "approvalTime": null,
    "disputedID": 0,
    "disputedTime": null,
    "disputedNote": "",
    "approver": null,
    "submittee": null,
    "disputer": null,
    "status": "NOT SUBMITTED",
    "customKeys": []
}

Exchange Rates

Get Exchange Rates

get_exchangeRates(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Get Exchange Rates based on the row ID or the date.

Note

• Arguments need to be passed as keyword arguments.

  Example: get_exchangeRates(ID=1)

ARGUMENTS

ID integer OPTIONAL	The ID of the exchange rate row. Required if date is not provided. If both ID and date are provided, the ID will be used.
date date OPTIONAL	Will return the exchange rate used for the date. The date does not have to be the exact date of the row. The exchange rate row selected will be the closest date before or equal to the date entered. Format: YYYY-MM-DD Required if ID is not provided. If both ID and date are provided, the ID will be used.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
data list	A list of dictionaries. Each dictionary includes: ID : The unique identifier for the exchange rate row. date : The date of the exchange rate. exchange rate : The exchange rate for each currency is represented as a key/value pair with the currency code as the key and the exchange rate as the value. (e.g, “USD”: “1.000000”, “EUR”: “0.824160”, etc.)

Example Usage:

from nim_core.nim_api import get_exchangeRates

response = get_exchangeRates(ID=1)

if response["success"]:
    for rate in response["data"]:
        print(f"Exchange Rate ID: {rate['ID']}, Date: {rate['date']}, Rates: {rate['USD']}, {rate['EUR']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": "",
    "data": [
        {
            "ID": 5,
            "date": "2021-01-01",
            "USD": "1.000000",
            "EUR": "0.824160",
            "JPY": "103.599220",
            "GBP": "0.731370",
            "AUD": "1.299900",
            "CHF": "0.890000",
            "CAD": "1.274000",
            "MXN": "19.882200",
            "CNY": null,
            "NZD": null,
            "SEK": null,
            "RUB": null,
            "HKD": null,
            "NOK": null,
            "SGD": null,
            "TRY": null,
            "KRW": null,
            "ZAR": null,
            "BRL": null,
            "INR": null,
            "ARS": null,
            "BGN": null,
            "CZK": null,
            "DKK": null,
            "HRK": null,
            "HUF": null
        }
    ]
}

Add Exchange Rates

add_exchangeRates(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Creates a new exchange rate entry.

Note

Arguments need to be passed as keyword arguments.

Example: add_exchangeRates(date=”2021-01-01”, USD=”1.000000”, EUR=”0.824160”)

ARGUMENTS

date date REQUIRED	The date of the exchange rate. This exchange rate will be used for all items that fall on or after this date until the next exchange rate date is passed. Format: YYYY-MM-DD
USD float OPTIONAL	The exchange rate for USD.
EUR float OPTIONAL	The exchange rate for EUR.
JPY float OPTIONAL	The exchange rate for JPY.
GBP float OPTIONAL	The exchange rate for GBP.
AUD float OPTIONAL	The exchange rate for AUD.
CHF float OPTIONAL	The exchange rate for CHF.
CAD float OPTIONAL	The exchange rate for CAD.
MXN float OPTIONAL	The exchange rate for MXN.
CNY float OPTIONAL	The exchange rate for CNY.
NZD float OPTIONAL	The exchange rate for NZD.
SEK float OPTIONAL	The exchange rate for SEK.
RUB float OPTIONAL	The exchange rate for RUB.
HKD float OPTIONAL	The exchange rate for HKD.
NOK float OPTIONAL	The exchange rate for NOK.
SGD float OPTIONAL	The exchange rate for SGD.
TRY float OPTIONAL	The exchange rate for TRY.
KRW float OPTIONAL	The exchange rate for KRW.
ZAR float OPTIONAL	The exchange rate for ZAR.
BRL float OPTIONAL	The exchange rate for BRL.
INR float OPTIONAL	The exchange rate for INR.
ARS float OPTIONAL	The exchange rate for ARS.
BGN float OPTIONAL	The exchange rate for BGN.
CZK float OPTIONAL	The exchange rate for CZK.
DKK float OPTIONAL	The exchange rate for DKK.
HRK float OPTIONAL	The exchange rate for HRK.
HUF float OPTIONAL	The exchange rate for HUF.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.
ID integer	The ID of the newly created item.

Example Usage:

from nim_core.nim_api import add_exchangeRates

response = add_exchangeRates(date="2025-01-01", USD=1.0, EUR=0.85, JPY=110.0)

if response["success"]:
    print(f"New exchange rate ID: {response['ID']}")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "ID": 62,
    "success": true,
    "error": ""
}

Update Exchange Rates

update_exchangeRates(nimURL=None, apiUser=None, apiKey=None, **kwargs)

Updates existing exchange rates based on the provided ID.

Note

Arguments need to be passed as keyword arguments.

Example: update_exchangeRates(ID=1, USD=1.0, EUR=0.85, JPY=110.0)

ARGUMENTS

ID integer REQUIRED	The ID of the exchange rate row to update.
date date OPTIONAL	The date to use for the exchange rate row. Format: YYYY-MM-DD
USD float OPTIONAL	The exchange rate for USD. Setting this value to 0 will remove the exchange rate for USD.
EUR float OPTIONAL	The exchange rate for EUR. Setting this value to 0 will remove the exchange rate for EUR.
JPY float OPTIONAL	The exchange rate for JPY. Setting this value to 0 will remove the exchange rate for JPY.
GBP float OPTIONAL	The exchange rate for GBP. Setting this value to 0 will remove the exchange rate for GBP.
AUD float OPTIONAL	The exchange rate for AUD. Setting this value to 0 will remove the exchange rate for AUD.
CHF float OPTIONAL	The exchange rate for CHF. Setting this value to 0 will remove the exchange rate for CHF.
CAD float OPTIONAL	The exchange rate for CAD. Setting this value to 0 will remove the exchange rate for CAD.
MXN float OPTIONAL	The exchange rate for MXN. Setting this value to 0 will remove the exchange rate for MXN.
CNY float OPTIONAL	The exchange rate for CNY. Setting this value to 0 will remove the exchange rate for CNY.
NZD float OPTIONAL	The exchange rate for NZD. Setting this value to 0 will remove the exchange rate for NZD.
SEK float OPTIONAL	The exchange rate for SEK. Setting this value to 0 will remove the exchange rate for SEK.
RUB float OPTIONAL	The exchange rate for RUB. Setting this value to 0 will remove the exchange rate for RUB.
HKD float OPTIONAL	The exchange rate for HKD. Setting this value to 0 will remove the exchange rate for HKD.
NOK float OPTIONAL	The exchange rate for NOK. Setting this value to 0 will remove the exchange rate for NOK.
SGD float OPTIONAL	The exchange rate for SGD. Setting this value to 0 will remove the exchange rate for SGD.
TRY float OPTIONAL	The exchange rate for TRY. Setting this value to 0 will remove the exchange rate for TRY.
KRW float OPTIONAL	The exchange rate for KRW. Setting this value to 0 will remove the exchange rate for KRW.
ZAR float OPTIONAL	The exchange rate for ZAR. Setting this value to 0 will remove the exchange rate for ZAR.
BRL float OPTIONAL	The exchange rate for BRL. Setting this value to 0 will remove the exchange rate for BRL.
INR float OPTIONAL	The exchange rate for INR. Setting this value to 0 will remove the exchange rate for INR.
ARS float OPTIONAL	The exchange rate for ARS. Setting this value to 0 will remove the exchange rate for ARS.
BGN float OPTIONAL	The exchange rate for BGN. Setting this value to 0 will remove the exchange rate for BGN.
CZK float OPTIONAL	The exchange rate for CZK. Setting this value to 0 will remove the exchange rate for CZK.
DKK float OPTIONAL	The exchange rate for DKK. Setting this value to 0 will remove the exchange rate for DKK.
HRK float OPTIONAL	The exchange rate for HRK. Setting this value to 0 will remove the exchange rate for HRK.
HUF float OPTIONAL	The exchange rate for HUF. Setting this value to 0 will remove the exchange rate for HUF.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import update_exchangeRates

response = update_exchangeRates(ID=62, EUR=0.85, JPY=110.0)

if response["success"]:
    print(f"Exchange rates updated successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}

Delete Exchange Rates

delete_exchangeRates(nimURL=None, apiUser=None, apiKey=None, **kwargs) → dict

Deletes an existing exchange rate row based on the provided parameters.

Note

Arguments need to be passed as keyword arguments.

Example: delete_exchangeRates(ID=62)

ARGUMENTS

ID integer OPTIONAL	The ID of the exchange rate row to delete. Required if date is not provided. If both ID and date are provided, the ID will be used.
date date OPTIONAL	Selects the exchange rate row to delete based on the row used for the date. The date does not have to be the exact date of the row. The exchange rate row deleted will have the closest date before or equal to the date entered. Format: YYYY-MM-DD Required if ID is not provided. If both ID and date are provided, the ID will be used.
nimURL string OPTIONAL	Override for nimURL setting in the user’s preferences. Including nimURL will override the default NIM API URL and skip the reading of saved user preferences.
apiUser string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.
apiKey string OPTIONAL	Required if nimURL is set and Require API Keys is enabled in NIM.

RETURN

success boolean	Indicates whether the operation was successful. Possible values: true or false.
error string	Contains any error messages if success is false. If success is true, this field is typically an empty string.

Example Usage:

from nim_core.nim_api import delete_exchangeRates

response = delete_exchangeRates(ID=8978)

if response["success"]:
    print("Exchange rate deleted successfully.")
else:
    print(f"Error: {response['error']}")

Example Response:

{
    "success": true,
    "error": ""
}