Note: For more information about the Shotgun API, see our API documentation.
The Shotgun Application Programming Interface (API) enables users to easily integrate their tools with Shotgun. Through it you can create automated processes, integrate with many third party software packages, and communicate with existing tools within your studio. Because the needs of every studio are very different, the Shotgun API provides powerful, low-level functionality and leaves most of the business logic to you.
The API follows the CRUD pattern, allowing your script to run Create, Read, Update, and Delete actions for a single entity type. Many operations include the ability to define filters, columns to return, and sort results.
In order to communicate with the Shotgun server via the API, your script can authenticate with the server either by providing a user’s credentials or by utilizing a script key. You can generate new script keys from the Scripts page, listed in the Admin menu:
Pro tip: Register your scripts separately and have individual API keys for each. This will help you to monitor each of your scripts and the actions they are performing much more accurately in the event logs.
Common first projects
You can download the API at https://github.com/shotgunsoftware/python-api. Some common first projects include:
- Creating a Version and linking it to a Shot. Allows you to automate the submission of new renders for review.
- Uploading a thumbnail. Everything on your site can have an up-to-date thumbnail without manually adding them.
- Integrating Shotgun with your code repository such as SVN. Utilize Shotgun to project manage any software development.
Some things you can’t do with the API
- Access or alter permission rules, for security reasons
- Read or alter page settings
- Access filter or query settings for individual pages or widgets
- Interact with the UI
- Add, edit, or remove conditional formatting rules
- Create or edit query fields
Action Menu Items (AMIs)
If you write a script that you want to easily launch from within the Shotgun interface, you can do so via AMIs. These are customizable options that appear in context menus you get when right-clicking on a row of data. When clicked, they will send a contextual data dump to a web server or a custom browser protocol handler, where you can then run custom business logic.
You can set up different AMIs for different entities, and can restrict access to them by project or by permission group.
Event Trigger Daemon
Every action performed in Shotgun (either by a user or an API script) generates an Event. The Event Daemon can monitor that event stream and then execute specific API scripts based on conditions you define. Some examples include:
- Automatically changing downstream Task statuses based on the status of upstream Tasks.
- Recalculating relevant cut duration fields when values change.
- Performing file packaging and transfer operations when a Shot is set to a particular status.
For more information about the Shotgun API, see these articles:
- Download the Shotgun API from GitHub
- Shotgun API documentation
- Shotgun-dev list (Public)
- Shotgun Event Daemon sample code
- Writing event driven triggers
- Shotgun schema
- API best practices
Contribute and collaborate
Have you made some amazing tools with Shotgun you want to share with the world? Awesome! We have an active and vibrant developer community who love to share and collaborate with each other. To get involved:
- Join the Shotgun-dev list.
- Post your code to GitHub (make sure your code isn’t pipeline specific, is well documented, and has a README in either .txt or .mdk format).
- Post a link and description to the dev list. The dev community and Shotgun developers will check it out, provide feedback, and sing your praises.
We are constantly amazed and inspired by many of the tools and integrations made by our clients. Show us what you can do!