Skip to main content
API docs by Redocly

Ayon server (1.3.1)

Download OpenAPI specification:Download

Ynput: info@ynput.io URL: https://ynput.io License: Apache License 2.0 Terms of Service

Open VFX and Animation pipeline server

Authentication

Authentication endpoints. Most of the endpoints require authentication.

There are two methods of authentication:

  • Clients, such as the web interface or Ayon launcher use Authorization header with Bearer <token> value. Token is obtained by calling the /auth/login endpoint. When not in use, the token expires after one day.
  • Services use x-api-key header with the API key value. API key is generated in the user settings and can be revoked at any time.

Services can additionally use x-as-user header to impersonate another user. This is useful for services that need to create data on behalf of another user.

Login

Login using name/password credentials.

Returns access token and user information. The token is used for authentication in other endpoints. It is valid for 24 hours, but it is extended automatically when the user is active.

Token may be revoked by calling the logout endpoint or using session manager.

Returns 401 response if the credentials are invalid.

Request Body schema: application/json
name
required
string (User name)

Username

password
required
string (Password)

Password

Responses

Request samples

Content type
application/json
{
  • "name": "admin",
  • "password": "SecretPassword.123"
}

Response samples

Content type
application/json
{
  • "detail": "Logged in as NAME",
  • "error": "Unauthorized",
  • "token": "TOKEN",
  • "user": {
    }
}

Logout

Log out the current user.

Responses

Response samples

Content type
application/json
{
  • "detail": "Logged out"
}

List Active Sessions

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Projects

Project is a collection of folders and other entities. Each project has a unique name, which is used as its identifier.

To address an entity within the project, you need to provide both the project name and the entity ID.

Operations

Process multiple operations (create / update / delete) in a single request.

All operations are processed in the order they are provided in the request. If can_fail is set to False, the processing stops on the first error and all previous operations are rolled back. If can_fail is set to True, the processing continues and all operations are committed.

The response contains the list of operations with their success status. In case of failure, the error message is provided for each operation.

This endpoint normally does not return error response, unless there is a problem with the request itself or an unhandled exception. Do not rely on a status code to determine if the operation was successful.

Always check the success field of the response.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
Array of objects (Operations)
canFail
boolean (Canfail)
Default: false

Responses

Request samples

Content type
application/json
{
  • "operations": [
    ],
  • "canFail": false
}

Response samples

Content type
application/json
{
  • "operations": [
    ],
  • "success": true
}

Get Project Anatomy

Retrieve a project anatomy.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$

Responses

Response samples

Content type
application/json
{
  • "roots": [
    ],
  • "templates": {
    },
  • "attributes": {
    },
  • "folder_types": [
    ],
  • "task_types": [
    ],
  • "link_types": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ]
}

Set Project Anatomy

Set a project anatomy.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
Array of objects (Roots)
Default: [{"name":"work","windows":"C:/projects","linux":"/mnt/share/projects","darwin":"/Volumes/projects"}]

Setup root paths for the project

object (Templates)

Path templates configuration

object (Attributes)

Attributes configuration

Array of objects (Folder types)

Folder types configuration

Array of objects (Task types)

Task types configuration

Array of objects (Link types)

Link types configuration

Array of objects (Statuses)

Statuses configuration

Array of objects (Tags)

Tags configuration

Responses

Request samples

Content type
application/json
{
  • "roots": [
    ],
  • "templates": {
    },
  • "attributes": {
    },
  • "folder_types": [
    ],
  • "task_types": [
    ],
  • "link_types": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

List Projects

Return a list of available projects.

query Parameters
page
integer (Page) >= 1
Default: 1
length
integer (Records per page)

If not provided, the result will not be limited

library
boolean (Show library projects)

If not provided, return projects regardless the flag

active
boolean (Show active projects)

If not provided, return projects regardless the flag

order
string (Attribute to order the list by)
Enum: "name" "createdAt" "updatedAt"
desc
boolean (Sort in descending order)
Default: false
name
string (Filter by name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
Example: name=forest

Limit the result to project with the matching name, or its part. % character may be used as a wildcard

Responses

Response samples

Content type
application/json
{
  • "detail": "Showing LENGTH of COUNT projects",
  • "count": 1,
  • "projects": [
    ]
}

Deploy Project

Create a new project using the provided anatomy object.

Main purpose is to take an anatomy object and transform its contents to the project entity (along with additional data such as the project name).

Request Body schema: application/json
name
required
string (Name)

Project name

code
required
string (Code)

Project code

required
object (Anatomy)

Project anatomy

library
boolean (Library)
Default: false

Library project

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "code": "string",
  • "anatomy": {
    },
  • "library": false
}

Response samples

Content type
application/json
null

Get Project

Retrieve a project by its name.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$

Responses

Response samples

Content type
application/json
{
  • "name": "awesome_project",
  • "code": "prj",
  • "library": false,
  • "folderTypes": [
    ],
  • "taskTypes": [
    ],
  • "linkTypes": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ],
  • "config": { },
  • "attrib": {
    },
  • "data": { },
  • "active": true,
  • "ownAttrib": [
    ],
  • "createdAt": "2023-01-01T00:00:00+00:00",
  • "updatedAt": "2023-01-01T00:00:00+00:00"
}

Create Project

Create a new project.

Since project has no ID, and a unique name is used as its identifier, use PUT request with the name provided in the URL to create a new project.

This is different from the rest of the entities, which use POST requests to create new entities with a unique ID.

Important: this endpoint only creates a project entity. It does not handle creating its anatomy and assigning users to the project, so it should be used only in special cases, when you need a granular control over a project creation process. Use Deploy project ([POST] /api/projects) for general usage.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
code
required
string (Project code) ^[a-zA-Z0-9_]*$
library
boolean (Library)
Default: false
folderTypes
Array of any (Folder types)
taskTypes
Array of any (Task types)
Array of objects (Link types)
statuses
Array of any (Statuses)
tags
Array of any (Tags)

List of tags available to set on entities.

config
object (Project config)
Default: {}
object (Project attributes)
data
object (Project auxiliary data)
active
boolean (Project active)
Default: true

Whether the project is active

Responses

Request samples

Content type
application/json
{
  • "code": "prj",
  • "library": false,
  • "folderTypes": [
    ],
  • "taskTypes": [
    ],
  • "linkTypes": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ],
  • "config": { },
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

Content type
application/json
null

Delete Project

Delete a given project including all its entities.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Update Project

Patch a project.

Use a PATCH request to partially update a project. For example change the name or a particular key in 'data'.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
code
string (Project code) ^[a-zA-Z0-9_]*$
library
boolean (Library)
Default: false
folderTypes
Array of any (Folder types)
taskTypes
Array of any (Task types)
Array of objects (Link types)
statuses
Array of any (Statuses)
tags
Array of any (Tags)

List of tags available to set on entities.

config
object (Project config)
Default: {}
object (Project attributes)
data
object (Project auxiliary data)
active
boolean (Project active)
Default: true

Whether the project is active

Responses

Request samples

Content type
application/json
{
  • "code": "prj",
  • "library": false,
  • "folderTypes": [
    ],
  • "taskTypes": [
    ],
  • "linkTypes": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ],
  • "config": { },
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Project Stats

Retrieve a project statistics by its name.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$

Responses

Response samples

Content type
application/json
null

Get Project Roots Overrides

Return overrides for project roots.

This endpoint is used to get overrides for project roots. The result is an a dictionary with site_id as a key and a dictionary with root names as keys and root paths as values.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$

Responses

Response samples

Content type
application/json
{
  • "property1": {
    },
  • "property2": {
    }
}

Set Project Roots Overrides

Set overrides for project roots.

path Parameters
site_id
required
string (Site Id)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Response samples

Content type
application/json
null

Get Project Site Roots

Return roots for a project on a specific site.

Thist takes in account roots declared in the project anatomy as well as site overrides. The result is combined and returned as a dictionary with root names as keys and root paths as values.

As the site also defines the platform, the result is specific to the platform of the site.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
platform
string (Platform)
Enum: "windows" "linux" "darwin"
header Parameters
x-ayon-site-id
string (Site ID)

Site ID may be specified either as a query parameter (site_id or site) or in a header.

Responses

Response samples

Content type
application/json
{
  • "property1": "string",
  • "property2": "string"
}

Folders

Endpoints for managing folders.

Get Folder

Retrieve a folder by its ID.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
folder_id
required
string (Folder ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "bush",
  • "label": "bush",
  • "folderType": "Asset",
  • "parentId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "path": "/assets/characters/xenomorph",
  • "attrib": {
    },
  • "data": { },
  • "active": true,
  • "ownAttrib": [
    ],
  • "status": "In progress",
  • "tags": [
    ],
  • "createdAt": "2023-01-01T00:00:00+00:00",
  • "updatedAt": "2023-01-01T00:00:00+00:00"
}

Delete Folder

Delete a folder.

Returns 409 error in there's a published product in the folder or any of its subfolders. Otherwise, deletes the folder and all its subfolders.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
folder_id
required
string (Folder ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
query Parameters
force
boolean (Force)
Default: false

Allow recursive deletion

header Parameters
x-sender
string (X-Sender)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Update Folder

Patch (partially update) a folder.

Once there is a version published, the folder's name and hierarchy cannot be changed.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
folder_id
required
string (Folder ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
name
string (Folder name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
label
string (Folder label) ^[^';]*$
folderType
string (Folder type)
parentId
string (Parent ID) ^[0-f]{32}$

Parent folder ID in the hierarchy

thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
status
string (Folder status)

Status of the folder

tags
Array of strings (Folder tags)

Tags assigned to the the folder

object (Folder attributes)
data
object (Folder auxiliary data)
active
boolean (Folder active)
Default: true

Whether the folder is active

Responses

Request samples

Content type
application/json
{
  • "name": "bush",
  • "label": "bush",
  • "folderType": "Asset",
  • "parentId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Folder List

Return all folders in the project. Fast.

This is a similar endpoint to /hierarchy, but the result is a flat list. additionally, this endpoint should be faster since it uses a cache. The cache is updated every time a folder is created, updated, or deleted.

The endpoint handles ACL and also returns folder attributes.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
attrib
boolean (Attrib)
Default: false

Responses

Response samples

Content type
application/json
{
  • "detail": "string",
  • "folders": [
    ]
}

Create Folder

Create a new folder.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
id
string (Entity ID) ^[0-f]{32}$

Explicitly set the ID of the entity

name
required
string (Folder name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
label
string (Folder label) ^[^';]*$
folderType
string (Folder type)
parentId
string (Parent ID) ^[0-f]{32}$

Parent folder ID in the hierarchy

thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
status
string (Folder status)

Status of the folder

tags
Array of strings (Folder tags)

Tags assigned to the the folder

object (Folder attributes)
data
object (Folder auxiliary data)
active
boolean (Folder active)
Default: true

Whether the folder is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "bush",
  • "label": "bush",
  • "folderType": "Asset",
  • "parentId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

Content type
application/json
{
  • "id": "af10c8f0e9b111e9b8f90242ac130003"
}

Get Folder Hierarchy

Return a folder hierarchy of a project.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
search
string (Search query)
Default: ""
Example: search=forest

Full-text search query used to limit the result

types
string (Type filter)
Default: ""
Example: types=AssetBuild,Shot,Sequence

Comma separated list of folder_types to show

Responses

Response samples

Content type
application/json
{
  • "detail": "string",
  • "projectName": "string",
  • "hierarchy": [
    ]
}

Attributes

Endpoints related to attribute configuration.

Warning: data does not reflect the active configuration of the attributes. The server needs to be restarted in order the changes become active.

Get Attribute List

Return a list of attributes and their configuration.

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ]
}

Set Attribute List

Set the attribute configuration for all (or ao of) attributes

Request Body schema: application/json
Array of objects (Attributes configuration)
deleteMissing
boolean (Delete missing)
Default: false

Delete custom attributes not includedin the payload from the database.

Responses

Request samples

Content type
application/json
{
  • "attributes": [
    ],
  • "deleteMissing": false
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Attribute Config

Return the configuration for a single attribute.

path Parameters
attribute_name
required
string (Attribute name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "name": "my_attribute",
  • "position": 12,
  • "scope": [
    ],
  • "builtin": false,
  • "data": {
    }
}

Set Attribute Config

Update attribute configuration

path Parameters
attribute_name
required
string (Attribute name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
Request Body schema: application/json
position
required
integer (Positon)

Default order

Array of strings or strings (Scope)

List of entity types the attribute is available on

builtin
boolean (Builtin)
Default: false

Is attribute builtin. Built-in attributes cannot be removed.

required
object (AttributeData)

Base API model.

Responses

Request samples

Content type
application/json
{
  • "position": 12,
  • "scope": [
    ],
  • "builtin": false,
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Attribute

path Parameters
attribute_name
required
string (Attribute name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Addon settings

Addon configuration, site and project overrides...

Get Addon Project Settings Schema

Return the JSON schema of the addon settings.

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{ }

Get Addon Project Settings

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
as
string (As)
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{ }

Set Addon Project Settings

Set the project overrides of the given addon.

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Request Body schema: application/json
object (Payload)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Addon Project Overrides

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
as
string (As)
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
null

Modify Project Overrides

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Request Body schema: application/json
action
required
string (Action)
Enum: "delete" "pin"
path
required
Array of strings (Path)

Responses

Request samples

Content type
application/json
{
  • "action": "delete",
  • "path": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Delete Addon Project Overrides

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Raw Addon Project Overrides

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{ }

Set Raw Addon Project Overrides

Set raw studio overrides for an addon.

Warning: this endpoint is not intended for general use and should only be used by administrators. It bypasses the normal validation and processing that occurs when modifying studio overrides through the normal API.

It won't trigger any events or validation checks, and may result in unexpected behaviour if used incorrectly.

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
variant
string (Variant)
Default: "production"
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Request Body schema: application/json
object (Payload)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Addon Site Settings Schema

Return the JSON schema of the addon site settings.

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)

Responses

Response samples

Content type
application/json
{ }

Get Addon Site Settings

Return the JSON schema of the addon site settings.

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
query Parameters
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{ }

Set Addon Site Settings

path Parameters
addon_name
required
string (Addon Name)
version
required
string (Version)
query Parameters
site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Request Body schema: application/json
object (Payload)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Addon Settings Schema

Return the JSON schema of the addon settings.

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"

Responses

Response samples

Content type
application/json
{ }

Get Addon Studio Settings

Return the settings (including studio overrides) of the given addon.

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"
as
string (As)

Responses

Response samples

Content type
application/json
{ }

Set Addon Studio Settings

Set the studio overrides for the given addon.

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"
Request Body schema: application/json
object (Payload)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Addon Studio Overrides

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"
as
string (As)

Responses

Response samples

Content type
application/json
null

Modify Studio Overrides

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"
Request Body schema: application/json
action
required
string (Action)
Enum: "delete" "pin"
path
required
Array of strings (Path)

Responses

Request samples

Content type
application/json
{
  • "action": "delete",
  • "path": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Delete Addon Studio Overrides

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"

Responses

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

Get Raw Addon Studio Overrides

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"

Responses

Response samples

Content type
application/json
{ }

Set Raw Addon Studio Overrides

Set raw studio overrides for an addon.

Warning: this endpoint is not intended for general use and should only be used by administrators. It bypasses the normal validation and processing that occurs when modifying studio overrides through the normal API.

It won't trigger any events or validation checks, and may result in unexpected behaviour if used incorrectly.

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
variant
string (Variant)
Default: "production"
Request Body schema: application/json
object (Payload)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "code": 401,
  • "detail": "Not logged in"
}

List Addons

List all available addons.

query Parameters
details
boolean (Show details)
Default: false

Responses

Response samples

Content type
application/json
{
  • "addons": [
    ]
}

Configure Addons

Request Body schema: application/json
object (VariantCopyRequest)

Base API model.

addonName
required
string (Addonname)

Addon name

copyFrom
required
string (Copyfrom)
Enum: "production" "staging"

Source variant

copyTo
required
string (Copyto)
Enum: "production" "staging"

Destination variant

Responses

Request samples

Content type
application/json
{
  • "copyVariant": {
    }
}

Response samples

Content type
application/json
null

Get All Addons Settings Deprecated

Return all addon settings for the project.

query Parameters
variant
string (Settings variant)
Default: "production"
Enum: "production" "staging"
project
string (Project) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
site
string (Site) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "settings": {
    },
  • "versions": {
    }
}

Get All Site Settings Deprecated

Return site settings for all enabled addons.

Those are 'global' site settings (from addon.site_settings_model) with no project overrides. When site is not specified, it will return the default settings provided by the model.

query Parameters
variant
string (Settings variant)
Default: "production"
Enum: "production" "staging"
site
string (Site) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "settings": {
    },
  • "versions": {
    }
}

Get All Settings

query Parameters
bundle_name
string (Bundle name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Production if not set

project_name
string (Project name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Studio settings if not set

variant
string (Variant)
Default: "production"
summary
boolean (Summary)
Default: false

Summary mode

site_id
string (Site ID)

Site ID may be specified a query parameter. Both site_id and its's alias site are supported.

Responses

Response samples

Content type
application/json
{
  • "bundleName": "string",
  • "addons": [
    ]
}

Secrets

Sensitive information, like passwords or API keys, can be securely stored in secrets, which are only accessible by administrators and services. This makes them an ideal location for storing this type of data.

For addons needing access to secrets, using the 'secret name' in settings instead of the actual value is recommended. Consequently, updating secrets won't require any changes to the addon configuration.

Get List Of Secrets

Return a list of stored secrets

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Secret

Return a secret value

path Parameters
secret_name
required
string (Secret name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Save Secret

Create or update a secret value

path Parameters
secret_name
required
string (Secret name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
Request Body schema: application/json
name
string (Secret name)
value
string (Secret value)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "value": "string"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Secret

Delete a secret

path Parameters
secret_name
required
string (Secret name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Access Groups

Get Access Group Schema

Responses

Response samples

Content type
application/json
null

Get Access Groups

Get a list of access group for a given project

path Parameters
project_name
required
string (Project name)

Responses

Response samples

Content type
application/json
[
  • { }
]

Get Access Group

Get an access group definition

path Parameters
access_group_name
required
string (Access group name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
project_name
required
string (Project name)

Responses

Response samples

Content type
application/json
{
  • "create": {
    },
  • "read": {
    },
  • "update": {
    },
  • "publish": {
    },
  • "delete": {
    },
  • "attrib_read": {
    },
  • "attrib_write": {
    },
  • "endpoints": {
    }
}

Save Access Group

Create or update an access group.

Use _ as a project name to save a global access group.

path Parameters
access_group_name
required
string (Access group name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
project_name
required
string (Project name)
Request Body schema: application/json
object (Restrict folder creation)

Whitelist folders a user can create

object (Restrict folder read)

Whitelist folders a user can read

object (Restrict folder update)

Whitelist folders a user can update

object (Restrict publishing)

Whitelist folders a user can publish to

object (Restrict folder delete)

Whitelist folders a user can delete

object (Restrict attribute read)

Whitelist attributes a user can read

object (Restrict attribute update)

Whitelist attributes a user can write

object (Restrict REST endpoints)

Whitelist REST endpoints a user can access

Responses

Request samples

Content type
application/json
{
  • "create": {
    },
  • "read": {
    },
  • "update": {
    },
  • "publish": {
    },
  • "delete": {
    },
  • "attrib_read": {
    },
  • "attrib_write": {
    },
  • "endpoints": {
    }
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Access Group

Delete an access group

path Parameters
access_group_name
required
string (Access group name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
project_name
required
string (Project name)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Actions

List Available Actions For Context

Get available actions for a context.

This endpoint is used to get a list of actions that can be performed on a given context. The context is defined by the project name, entity type, and entity ids. The resulting list is then displayed to the user, who can choose to run one of the actions.

Simple actions are actions that do not require any additional computation, so the list may be returned relatively quickly.

Dynamic actions are actions that require additional computation to determine if they are available, so they cannot be listed as quickly as simple actions.

Simple actions may be pinned to the entity sidebar.

query Parameters
mode
string (Action List Mode)
Default: "simple"
Enum: "simple" "dynamic" "all"
Request Body schema: application/json
projectName
required
string (Projectname)

The name of the project

entityType
required
string (Entitytype)
Enum: "folder" "product" "version" "representation" "task" "workfile"

The type of the entity

entitySubtypes
Array of strings (Entitysubtypes)

List of subtypes present in the entity list

entityIds
required
Array of strings (Entity IDs)

The IDs of the entities

Responses

Request samples

Content type
application/json
{
  • "projectName": "my_project",
  • "entityType": "folder",
  • "entitySubtypes": [
    ],
  • "entityIds": [
    ]
}

Response samples

Content type
application/json
{
  • "actions": [
    ]
}

List All Actions

Get a list of all available actions.

This endpoint is used to get a list of all available actions, regardless the context they are available in. In order to get this list, addon has to implement "get_all_actions" method.

This endpoint is used for managing actions (e.g. enable/disable/statistics...)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Execute Action

Run an action.

This endpoint is used to run an action on a context. This is called from the frontend when the user selects an action to run.

query Parameters
addonName
required
string (Addon Name)
addonVersion
required
string (Addon Version)
variant
string (Action Variant)
Default: "production"
identifier
required
string (Action Identifier)
Request Body schema: application/json
projectName
required
string (Projectname)

The name of the project

entityType
required
string (Entitytype)
Enum: "folder" "product" "version" "representation" "task" "workfile"

The type of the entity

entitySubtypes
Array of strings (Entitysubtypes)

List of subtypes present in the entity list

entityIds
required
Array of strings (Entity IDs)

The IDs of the entities

Responses

Request samples

Content type
application/json
{
  • "projectName": "my_project",
  • "entityType": "folder",
  • "entitySubtypes": [
    ],
  • "entityIds": [
    ]
}

Response samples

Content type
application/json
{
  • "type": "launcher",
  • "success": true,
  • "message": "Action executed successfully",
  • "uri": "ayon-launcher://action?server_url=http%3A%2F%2Flocalhost%3A8000%2F&token=eyJaaaa"
}

Take Action

called by launcher

This is called by the launcher when it is started via ayon-launcher://action?server_url=...&token=... URI

Launcher connects to the server using the server url and uses the token to get the action event (token is the event.hash)

The server then gets the event payload and updates the event status to in_progress and returns the event payload to the launcher.

Launcher is then responsible for executing the action based on the payload and updating the event status to finished or failed

path Parameters
token
required
string (Action Token) [a-f0-9]{64}

Responses

Response samples

Content type
application/json
{
  • "eventId": "aae4b3d4-7b7b-4b7b-8b7b-7b7b7b7b7b7b",
  • "actionIdentifier": "launch-maya",
  • "args": [
    ],
  • "context": {
    },
  • "addonName": "maya",
  • "addonVersion": "1.5.6",
  • "variant": "production",
  • "userName": "john.doe"
}

Activity feed

Post Project Activity

Create an activity.

Comment on an entity for example. Or subscribe for updates (later)

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
entity_type
required
string (Entity Type)
entity_id
required
string (Entity ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
id
string (Id)

Explicitly set the ID of the activity

activityType
required
string (Activitytype)
Enum: "comment" "reviewable" "status.change" "assignee.add" "assignee.remove" "version.publish"
body
string (Body)
Default: ""
files
Array of strings (Files)
timestamp
string <date-time> (Timestamp)
data
object (Data)

Additional data

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "activityType": "comment",
  • "body": "This is a comment",
  • "files": [
    ],
  • "timestamp": "2021-01-01T00:00:00Z",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "id": "123"
}

Delete Project Activity

Delete an activity.

Only the author or an administrator of the activity can delete it.

path Parameters
activity_id
required
string (Activity Id)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

Content type
application/json
null

Patch Project Activity

Edit an activity.

Only the author of the activity can edit it.

path Parameters
activity_id
required
string (Activity Id)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
body
required
string (Body)
files
Array of strings (Files)

Responses

Request samples

Content type
application/json
{
  • "body": "This is a comment",
  • "files": [
    ]
}

Response samples

Content type
application/json
null

Suggest Entity Mention

Suggests entity mentions based on the given entity type.

This is triggered when the user begins commenting on a task, folder, or version. It populates the suggestions dropdown with relevant entities that the user can mention.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
entityType
required
string (Entitytype)
Enum: "folder" "task" "version"
entityId
required
string (Entityid)

Responses

Request samples

Content type
application/json
{
  • "entityType": "task",
  • "entityId": "af3e4b3e-1b1b-4b3b-8b3b-3b3b3b3b3b3b"
}

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "tasks": [
    ],
  • "versions": [
    ]
}

Addons

Delete Addon

Delete an addon

path Parameters
addon_name
required
string (Addon Name)
query Parameters
purge
boolean (Purge all data related to the addon)
Default: false

Responses

Response samples

Content type
application/json
null

Delete Addon Version

Delete an addon version

path Parameters
addon_name
required
string (Addon Name)
addon_version
required
string (Addon Version)
query Parameters
purge
boolean (Purge all data related to the addon)
Default: false

Responses

Response samples

Content type
application/json
null

Get Installed Addons List

Get a list of installed addons

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "restartRequired": true
}

Upload Addon Zip File

Upload an addon zip file and install it

query Parameters
url
string (URL to the addon zip file)
addonName
string (Addon name)
addonVersion
string (Addon version)

Responses

Response samples

Content type
application/json
{
  • "eventId": "string"
}

Anatomy

Get Anatomy Schema

Returns the anatomy JSON schema.

The schema is used to display the anatomy preset editor form.

Responses

Response samples

Content type
application/json
{ }

Get Anatomy Presets

Return a list of stored anatomy presets.

Responses

Response samples

Content type
application/json
{
  • "version": "string",
  • "presets": [
    ]
}

Get Anatomy Preset

Returns the anatomy preset with the given name.

  • Use __builtin__ character as a preset name to return the builtin preset.
  • Use __primary__ character as a preset name to return the primary preset.
  • _ is an alias for built in preset (deprecated, kept for backward compatibility).
path Parameters
preset_name
required
string (Preset Name)

Responses

Response samples

Content type
application/json
{
  • "roots": [
    ],
  • "templates": {
    },
  • "attributes": {
    },
  • "folder_types": [
    ],
  • "task_types": [
    ],
  • "link_types": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ]
}

Update Anatomy Preset

Create/update an anatomy preset with the given name.

path Parameters
preset_name
required
string (Preset Name)
Request Body schema: application/json
Array of objects (Roots)
Default: [{"name":"work","windows":"C:/projects","linux":"/mnt/share/projects","darwin":"/Volumes/projects"}]

Setup root paths for the project

object (Templates)

Path templates configuration

object (Attributes)

Attributes configuration

Array of objects (Folder types)

Folder types configuration

Array of objects (Task types)

Task types configuration

Array of objects (Link types)

Link types configuration

Array of objects (Statuses)

Statuses configuration

Array of objects (Tags)

Tags configuration

Responses

Request samples

Content type
application/json
{
  • "roots": [
    ],
  • "templates": {
    },
  • "attributes": {
    },
  • "folder_types": [
    ],
  • "task_types": [
    ],
  • "link_types": [
    ],
  • "statuses": [
    ],
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Anatomy Preset

Delete the anatomy preset with the given name.

path Parameters
preset_name
required
string (Preset Name)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Set Primary Preset

Set the given preset as the primary preset.

path Parameters
preset_name
required
string (Preset Name)

Responses

Response samples

Content type
application/json