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
{
  • "detail": [
    ]
}

Unset Primary Preset

Unset the primary preset.

path Parameters
preset_name
required
string (Preset Name)

Responses

Response samples

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

Bundles

List Bundles

query Parameters
archived
boolean (Archived)
Default: false

Include archived bundles

Responses

Response samples

Content type
application/json
{
  • "bundles": [
    ],
  • "productionBundle": "my_superior_bundle",
  • "stagingBundle": "my_superior_bundle",
  • "devBundles": [
    ]
}

Create New Bundle

query Parameters
force
boolean (Force)
Default: false

Force creation of bundle

header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
name
required
string (Name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Name of the bundle

createdAt
string <date-time> (Createdat)
object (Addons)
installerVersion
string (Installerversion)
object (Dependency packages)

mapping of platform:dependency_package_filename

object (Addondevelopment)
isProduction
boolean (Isproduction)
Default: false
isStaging
boolean (Isstaging)
Default: false
isArchived
boolean (Isarchived)
Default: false
isDev
boolean (Isdev)
Default: false
activeUser
string (Activeuser)

Responses

Request samples

Content type
application/json
{
  • "name": "my_superior_bundle",
  • "createdAt": "2024-07-26T15:07:26.708670",
  • "addons": {
    },
  • "installerVersion": "1.2.3",
  • "dependencyPackages": {
    },
  • "addonDevelopment": {
    },
  • "isProduction": false,
  • "isStaging": false,
  • "isArchived": false,
  • "isDev": false,
  • "activeUser": "admin"
}

Response samples

Content type
application/json
null

Check Bundle Compatibility

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

Name of the bundle

createdAt
string <date-time> (Createdat)
object (Addons)
installerVersion
string (Installerversion)
object (Dependency packages)

mapping of platform:dependency_package_filename

object (Addondevelopment)
isProduction
boolean (Isproduction)
Default: false
isStaging
boolean (Isstaging)
Default: false
isArchived
boolean (Isarchived)
Default: false
isDev
boolean (Isdev)
Default: false
activeUser
string (Activeuser)

Responses

Request samples

Content type
application/json
{
  • "name": "my_superior_bundle",
  • "createdAt": "2024-07-26T15:07:26.708670",
  • "addons": {
    },
  • "installerVersion": "1.2.3",
  • "dependencyPackages": {
    },
  • "addonDevelopment": {
    },
  • "isProduction": false,
  • "isStaging": false,
  • "isArchived": false,
  • "isDev": false,
  • "activeUser": "admin"
}

Response samples

Content type
application/json
{
  • "success": false,
  • "issues": [
    ]
}

Bundle Actions

Perform actions on bundles.

path Parameters
bundle_name
required
string (Bundle Name)
Request Body schema: application/json
action
required
string (Action)
Value: "promote"

Responses

Request samples

Content type
application/json
{
  • "action": "promote"
}

Response samples

Content type
application/json
null

Delete Existing Bundle

path Parameters
bundle_name
required
string (Bundle Name)

Responses

Response samples

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

Update Bundle

path Parameters
bundle_name
required
string (Bundle Name)
query Parameters
build
Array of strings (Request build)
Items Enum: "windows" "linux" "darwin"

Build dependency packages for selected platforms

force
boolean (Force)
Default: false

Force creation of bundle

header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
object (Addons)
installerVersion
string (Installerversion)
object (Dependency packages)

mapping of platform:dependency_package_filename

isProduction
boolean (Isproduction)
isStaging
boolean (Isstaging)
isArchived
boolean (Isarchived)
isDev
boolean (Isdev)
activeUser
string (Activeuser)
object (Addondevelopment)

Responses

Request samples

Content type
application/json
{
  • "addons": {
    },
  • "installerVersion": "1.2.3",
  • "dependencyPackages": {
    },
  • "isProduction": false,
  • "isStaging": false,
  • "isArchived": false,
  • "isDev": false,
  • "activeUser": "admin",
  • "addonDevelopment": {
    }
}

Response samples

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

Ynput Cloud

Get Ynput Cloud Info

Check whether the Ynput Cloud key is set and return the Ynput Cloud info

Responses

Response samples

Content type
application/json
{
  • "instanceId": "string",
  • "instanceName": "Ayon - staging",
  • "orgId": "string",
  • "orgName": "Ynput",
  • "collectSaturatedMetrics": false,
  • "managed": false,
  • "subscriptions": [
    ]
}

Set Ynput Cloud Key

Store the Ynput cloud key in the database and return the user info

Request Body schema: application/json
key
required
string (Key)

Ynput cloud key

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "instanceId": "string",
  • "instanceName": "Ayon - staging",
  • "orgId": "string",
  • "orgName": "Ynput",
  • "collectSaturatedMetrics": false,
  • "managed": false,
  • "subscriptions": [
    ]
}

Delete Ynput Cloud Key

Remove the Ynput cloud key from the database

Responses

Response samples

Content type
application/json
null

Connect To Ynput Cloud

Redirect to Ynput cloud authorization page

query Parameters
origin_url
required
string (Origin Url)

Responses

Response samples

Content type
application/json
null

Desktop

List Dependency Packages

Return a list of dependency packages

Responses

Response samples

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

Create Dependency Package

query Parameters
url
string (Url)

URL to the addon zip file

overwrite
boolean (Overwrite)
Deprecated
Default: false

Deprecated. Use the force.

force
boolean (Force)
Default: false

Force install the package if it already exists

Request Body schema: application/json
filename
required
string (Filename)
platform
required
string (Platform)
Enum: "windows" "linux" "darwin"
size
integer (Size)
checksum
string (Checksum)
checksumAlgorithm
string (Checksumalgorithm)
Enum: "md5" "sha1" "sha256"
Array of objects (Sources)

List of sources to download the file from. Server source is added automatically by the server if the file is uploaded.

installerVersion
required
string (Installer version)

Version of the Ayon installer this package is created with

object (Source addons)

mapping of addon_name:addon_version used to create the package

object (Python modules)

mapping of module_name:module_version used to create the package

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "platform": "windows",
  • "size": 0,
  • "checksum": "string",
  • "checksumAlgorithm": "md5",
  • "sources": [
    ],
  • "installerVersion": "1.2.3",
  • "sourceAddons": {
    },
  • "pythonModules": {
    }
}

Response samples

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

Download Dependency Package

Download dependency package.

Use this endpoint to download dependency package stored on the server.

path Parameters
filename
required
string (Filename)

Responses

Response samples

Content type
application/json
null

Upload Dependency Package

Upload a dependency package to the server.

path Parameters
filename
required
string (Filename)

Responses

Response samples

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

Delete Dependency Package

Delete a dependency package from the server. If there is an uploaded package, it will be deleted as well.

path Parameters
filename
required
string (Filename)

Responses

Response samples

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

Update Dependency Package

Update dependency package sources

path Parameters
filename
required
string (Filename)
Request Body schema: application/json
Array of objects (Sources)

List of sources to download the file from. Server source is added automatically by the server if the file is uploaded.

Array
type
required
string (Source type)
Enum: "server" "http"

If set to server, the file is stored on the server. If set to http, the file is downloaded from the specified URL.

url
string (Download URL)

URL to download the file from. Only used if type is url

Responses

Request samples

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

Response samples

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

List Installers

query Parameters
version
string (Version)

Version of the package

platform
string (Platform)
Enum: "windows" "linux" "darwin"

Platform of the package

variant
string (Variant)
Enum: "production" "staging"

Responses

Response samples

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

Create Installer

query Parameters
url
string (Url)

URL to the addon zip file

overwrite
boolean (Overwrite)
Deprecated
Default: false

Deprecated. Use the force

force
boolean (Force)
Default: false

Overwrite existing installer

Request Body schema: application/json
filename
required
string (Filename)
platform
required
string (Platform)
Enum: "windows" "linux" "darwin"
size
integer (Size)
checksum
string (Checksum)
checksumAlgorithm
string (Checksumalgorithm)
Enum: "md5" "sha1" "sha256"
Array of objects (Sources)

List of sources to download the file from. Server source is added automatically by the server if the file is uploaded.

version
required
string (Version)

Version of the installer

pythonVersion
required
string (Python version)

Version of Python that the installer is created with

object (Python modules)

mapping of module name:version used to create the installer

object (Runtime Python modules)

mapping of module_name:module_version used to run the installer

Responses

Request samples

Content type
application/json
{
  • "filename": "string",
  • "platform": "windows",
  • "size": 0,
  • "checksum": "string",
  • "checksumAlgorithm": "md5",
  • "sources": [
    ],
  • "version": "1.2.3",
  • "pythonVersion": "3.11",
  • "pythonModules": {
    },
  • "runtimePythonModules": {
    }
}

Response samples

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

Download Installer File

path Parameters
filename
required
string (Filename)

Responses

Response samples

Content type
application/json
null

Upload Installer File

path Parameters
filename
required
string (Filename)

Responses

Response samples

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

Delete Installer File

path Parameters
filename
required
string (Filename)

Responses

Response samples

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

Patch Installer

Update sources for an installer

path Parameters
filename
required
string (Filename)
Request Body schema: application/json
Array of objects (Sources)

List of sources to download the file from. Server source is added automatically by the server if the file is uploaded.

Array
type
required
string (Source type)
Enum: "server" "http"

If set to server, the file is stored on the server. If set to http, the file is downloaded from the specified URL.

url
string (Download URL)

URL to download the file from. Only used if type is url

Responses

Request samples

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

Response samples

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

Events

Enroll

Enroll for a new job.

Enroll for a new job by providing a source topic and target topic. Used by workers to get a new job to process. If there is no job available, request returns 204 (no content).

Non-error response is returned because having nothing to do is not an error and we don't want to spam the logs.

Request Body schema: application/json
sourceTopic
required
string (Source topic) ^[a-zA-Z][a-zA-Z0-9_\.\*]{2,64}$
targetTopic
required
string (Target topic) ^[a-zA-Z][a-zA-Z0-9_\.\*]{2,64}$
sender
required
string (Sender)
description
string (Description)

Short, human readable description of the target event

sequential
boolean (Sequential)
Default: false

Ensure events are processed in sequential order

object (Filter)

Filter source events

maxRetries
integer (Max retries)
Default: 3
debug
boolean (Debug)
Default: false

Responses

Request samples

Content type
application/json
{
  • "sourceTopic": "ftrack.update",
  • "targetTopic": "ftrack.sync_to_ayon",
  • "sender": "workerservice01",
  • "description": "Sync Ftrack project to Ayon",
  • "sequential": true,
  • "filter": {
    },
  • "maxRetries": 3,
  • "debug": false
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "dependsOn": "string",
  • "hash": "string",
  • "status": "pending"
}

Post Event

Request Body schema: application/json
topic
required
string (Topic) ^[a-zA-Z][a-zA-Z0-9_\.\*]{2,64}$

Topic of the event

sender
string (Sender)

Identifier of the process that sent the event.

hash
string (Hash)

Deterministic hash of the event topic and summary/payload

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

Name of the project if the event belong to one.

dependsOn
string (Depends on) = 32 characters

ID of the event this event depends on.

description
string (Description)

Short, human-readable description of the event and its state

summary
object (Summary)

Arbitrary topic-specific data sent to clients in real time

payload
object (Payload)

Full event payload. Only avaiable in REST endpoint.

finished
boolean (Finished)
Default: true

Is event finished (one shot event)

store
boolean (Store)
Default: true

Set to False for fire-and-forget events

Responses

Request samples

Content type
application/json
{
  • "topic": "media.import",
  • "sender": "service-processor-01",
  • "hash": "string",
  • "project": "MyProject",
  • "dependsOn": "69dd9b85a522fcedc14203ea95f54f52",
  • "description": "Importing file 3 of 10",
  • "summary": { },
  • "payload": { },
  • "finished": true,
  • "store": true
}

Response samples

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

Get Event

Get event by ID.

Return event data with given ID. If event is not found, 404 is returned.

path Parameters
event_id
required
string (Event ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003

Responses

Response samples

Content type
application/json
{
  • "id": "af10c8f0e9b111e9b8f90242ac130003",
  • "hash": "string",
  • "topic": "string",
  • "sender": "service-processor-01",
  • "project": "MyProject",
  • "user": "admin",
  • "dependsOn": "69dd9b85a522fcedc14203ea95f54f52",
  • "status": "pending",
  • "retries": 0,
  • "description": "Importing file 3 of 10",
  • "summary": { },
  • "payload": { },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

Update Existing Event

Update existing event.

path Parameters
event_id
required
string (Event ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
Request Body schema: application/json
sender
string (Sender)

Identifier of the process that sent the event.

projectName
string (Project name)
Deprecated

Deprecated use 'project' instead

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

Name of the project if the event belong to one.

user
string (User name)
status
string (Status)
Enum: "pending" "in_progress" "finished" "failed" "aborted" "restarted"
description
string (Description)

Short, human-readable description of the event and its state

summary
object (Summary)
payload
object (Payload)
progress
number (Progress) [ 0 .. 100 ]

Percentage of progress. Transmitted to clients in real time.

retries
integer (Retries)

Force number of attempted retries

Responses

Request samples

Content type
application/json
{
  • "sender": "service-processor-01",
  • "projectName": "string",
  • "project": "MyProject",
  • "user": "admin",
  • "status": "in_progress",
  • "description": "Importing file 3 of 10",
  • "summary": { },
  • "payload": { },
  • "progress": 42,
  • "retries": 1
}

Response samples

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

Query

Request Body schema: application/json
entity
required
string (Entity)
Enum: "event" "project" "user" "folder" "product" "task" "version" "representation" "workfile"
object (Filter)

Filter events

limit
integer (Limit)
Default: 100

Maximum number of events to return

offset
integer (Offset)
Default: 0

Offset of the first event to return

Responses

Request samples

Content type
application/json
{
  • "entity": "event",
  • "filter": {
    },
  • "limit": 100,
  • "offset": 0
}

Response samples

Content type
application/json
[
  • { }
]

Project files

Upload Project File

Handle uploading a file to a project.

Used for comment attachments, etc. Files are stored in the uploads directory (defined in ayon config). Each file is associated with its author, project and optionally an activity.

The request accepts additional headers for the file metadata:

  • Content-Type: The MIME type of the file (required)
  • X-File-Id: The ID of the file (optional, will be generated if not provided)
  • X-File-Name: The name of the file including the extension (required)
  • X-Activity-Id: The ID of the activity the file is associated with (optional)
path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
header Parameters
x-file-id
string (X-File-Id)
x-file-name
required
string (X-File-Name)
x-activity-id
string (X-Activity-Id)
content-type
required
string (Content-Type)

Responses

Response samples

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

Get Project File

Get a project file (comment attachment etc.)

The preview query parameter can be used to get a preview of the file (if available).

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

Responses

Response samples

Content type
application/json
null

Delete Project File

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

Responses

Response samples

Content type
application/json
null

Get Project File Head

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

Responses

Response samples

Content type
application/json
null

Get Project File Thumbnail

Get a project file (comment attachment etc.)

The preview query parameter can be used to get a preview of the file (if available).

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

Responses

Response samples

Content type
application/json
null

User inbox

Manage Inbox Item

Manage inbox items

Request Body schema: application/json
projectName
required
string (Projectname)
ids
Array of strings (List of items)

List of reference_ids of items to be managed

status
required
string (Status)
Enum: "unread" "read" "inactive"

Status to set for the items

Responses

Request samples

Content type
application/json
{
  • "projectName": "string",
  • "ids": [
    ],
  • "status": "unread"
}

Response samples

Content type
application/json
null

Market

Market Addon List

Responses

Response samples

Content type
application/json
null

Market Addon Detail

path Parameters
addon_name
required
string (Addon Name)

Responses

Response samples

Content type
application/json
null

Market Addon Version Detail

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

Responses

Response samples

Content type
application/json
null

Onboarding

Create First Admin

Create the first user and log in.

When Ayon is started for the first time, there is no admin user. in that case /api/system/info contains {"noAdmin_user": true}.

The frontend will display a form to create the first admin user. using this endpoint. It will also log in the user and return the same response as /api/auth/login, so the frontend can continue in logged-in mode.

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

Username

adminPassword
required
string (Password)

Password

adminFullName
string (Full name)
Default: ""

Full name

adminEmail
string (Administrator email)
Default: ""

Responses

Request samples

Content type
application/json
{
  • "adminName": "admin",
  • "adminPassword": "SecretPassword.123",
  • "adminFullName": "Administrator",
  • "adminEmail": "admin@example.com"
}

Response samples

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

Abort Onboarding

Abort the onboarding process (disable nag screen)

Responses

Response samples

Content type
application/json
null

Restart Onboarding

Restart the onboarding process

Responses

Response samples

Content type
application/json
null

Get Releases

Get the releases

Responses

Response samples

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

Get Release Info

Get the release info

path Parameters
release_name
required
string (Release Name)

Responses

Response samples

Content type
application/json
{
  • "name": "2023.08-2D",
  • "label": "2D Animation",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "addons": [
    ],
  • "installers": [
    ],
  • "dependencyPackages": [
    ]
}

Products

Get Product

Retrieve a product by its ID.

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

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "modelMain",
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "productType": "model",
  • "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 Product

Delete a product.

This will also delete all the product's versions and representations.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
product_id
required
string (Product ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

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

Update Product

Patch (partially update) a product.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
product_id
required
string (Product ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
name
string (Name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Name of the product

folderId
string (Folder ID) ^[0-f]{32}$

ID of the parent folder

productType
string (Product type) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Product

status
string (Product status)

Status of the product

tags
Array of strings (Product tags)

Tags assigned to the the product

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

Whether the product is active

Responses

Request samples

Content type
application/json
{
  • "name": "modelMain",
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "productType": "model",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Create Product

Create a new product.

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 (Name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Name of the product

folderId
required
string (Folder ID) ^[0-f]{32}$

ID of the parent folder

productType
required
string (Product type) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

Product

status
string (Product status)

Status of the product

tags
Array of strings (Product tags)

Tags assigned to the the product

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

Whether the product is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "modelMain",
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "productType": "model",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Project dashboard

Get Project Entity Counts

Retrieve entity counts for a given project.

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

Responses

Response samples

Content type
application/json
{
  • "folders": 10,
  • "products": 98,
  • "versions": 512,
  • "representations": 4853,
  • "tasks": 240,
  • "workfiles": 190
}

Get Project Health

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

Responses

Response samples

Content type
application/json
{
  • "completion": {
    },
  • "storageUsage": {
    },
  • "tasks": {
    },
  • "statuses": {
    }
}

Get Project Activity

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
query Parameters
days
integer (Days)
Default: 50

Number of days to retrieve activity for

Responses

Response samples

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

Get Project Users

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

Responses

Response samples

Content type
application/json
{
  • "teamSizeActive": 0,
  • "teamSizeTotal": 0,
  • "usersWithAccessActive": 0,
  • "usersWithAccessTotal": 0,
  • "roles": {
    }
}

Representations

Representation Context Filter

Return representation IDs matching the given criteria.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
names
Array of strings (Representation names)
versionIds
Array of strings (Version IDs)
Array of objects (Context filters)

Responses

Request samples

Content type
application/json
{
  • "names": [
    ],
  • "versionIds": [
    ],
  • "context": [
    ]
}

Response samples

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

Get Representation

Retrieve a representation by its ID.

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

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "ma",
  • "versionId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "files": [
    ],
  • "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 Representation

Delete a representation.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
representation_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

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

Update Representation

Patch (partially update) a representation.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
representation_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
name
string (Name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

The name of the representation

versionId
string (Version ID) ^[0-f]{32}$

ID of the parent version

Array of objects (Files)

List of files

status
string (Representation status)

Status of the representation

tags
Array of strings (Representation tags)

Tags assigned to the the representation

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

Whether the representation is active

Responses

Request samples

Content type
application/json
{
  • "name": "ma",
  • "versionId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "files": [
    ],
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Create Representation

Create a new representation.

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 (Name) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...

The name of the representation

versionId
required
string (Version ID) ^[0-f]{32}$

ID of the parent version

Array of objects (Files)

List of files

status
string (Representation status)

Status of the representation

tags
Array of strings (Representation tags)

Tags assigned to the the representation

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

Whether the representation is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "ma",
  • "versionId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "files": [
    ],
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

URIs

Resolve Uris

Resolve a list of ayon:// URIs to entities.

Each URI starts with ayon://{project_name}/{path} which determines the requested folder.

Schemes ayon:// and ayon+entity:// are equivalent (ayon is a shorter alias).

Additional query arguments [product, version, representation] or [task, workfile] are allowed. Note that arguments from product/version/representations cannot be mixed with task/workfile arguments.

Implicit wildcards

The response contains a list of resolved URIs with the requested entities. One URI can match multiple entities - for example when product and representation are requested, the response will contain all matching representations from all versions of the product.

Explicit wildcards

It is possible to use a * wildcard for querying multiple entities at the deepest level of the data structure:

ayon://my_project/assets/characters?product=setdress?version=* will return all versions of the given product.

Representation paths

When a representation is requested, the response will contain the resolved file path, and if the request contains X-ayon-site-id header and resolve_roots is set to true, in the request, the server will resolve the file path to the actual absolute path.

query Parameters
pathOnly
boolean (Pathonly)
Default: false

Return only file paths

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.

Request Body schema: application/json
resolveRoots
boolean (Resolve roots)
Default: false

If x-ayon-site-id header is provided, resolve representation path roots

uris
required
Array of strings (URIs)

List of uris to resolve

Responses

Request samples

Content type
application/json
{
  • "resolveRoots": false,
  • "uris": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

Get Project Entity Uris

Return a list of Ayon URIs for the given entity IDs.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
entityType
required
string (Entity type)
Enum: "folder" "product" "version" "representation" "task" "workfile"
ids
Array of strings (Entity IDs)

Responses

Request samples

Content type
application/json
{
  • "entityType": "folder",
  • "ids": [
    ]
}

Response samples

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

Reviewables

Get Reviewables For Product

Returns a list of reviewables for a given product.

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Reviewables For Version

Returns a list of reviewables for a given version.

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

Responses

Response samples

Content type
application/json
{
  • "id": "1a3b34ce-1b2c-4d5e-6f7a-8b9c0d1e2f3a",
  • "name": "v001",
  • "version": 1,
  • "status": "In Review",
  • "productId": "1a3b34ce-1b2c-4d5e-6f7a-8b9c0d1e2f3a",
  • "productName": "Product Name",
  • "productType": "Product Type",
  • "reviewables": [
    ]
}

Upload Reviewable

Uploads a reviewable for a given version.

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

Label

header Parameters
content-type
required
string (Content-Type)
x-file-name
required
string (X-File-Name)
x-sender
string (X-Sender)

Responses

Response samples

Content type
application/json
{
  • "fileId": "string",
  • "activityId": "string",
  • "filename": "string",
  • "label": "string",
  • "mimetype": "string",
  • "availability": "unknown",
  • "mediaInfo": { },
  • "createdFrom": "string",
  • "processing": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "author": {
    }
}

Sort Version Reviewables

Change the order of reviewables of a given version.

In the payload, provide a list of activity ids (reviewables) in the order you want them to appear in the UI.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
version_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
Request Body schema: application/json
sort
Array of strings (Reviewables Order)

List of reviewable (activity) ids in the order you want them to appear in the UI.

Responses

Request samples

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

Response samples

Content type
application/json
null

Get Reviewables For Task

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Reviewables For Folder

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
[
  • {
    }
]

Update Reviewable

Update an existing reviewable,

Currently it is only possible to update the label of a reviewable.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
version_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
activity_id
required
string (Activity ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
Request Body schema: application/json
label
string (Reviewable Label)

Responses

Request samples

Content type
application/json
{
  • "label": "Shoulder detail"
}

Response samples

Content type
application/json
null

Services

List Services

Responses

Response samples

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

Spawn Service

path Parameters
name
required
string (Name)
Request Body schema: application/json
addonName
required
string (Addon name)
addonVersion
required
string (Addon version)
service
required
string (Service)
hostname
required
string (Host)
object (ServiceConfigModel)

Base API model.

Responses

Request samples

Content type
application/json
{
  • "addonName": "ftrack",
  • "addonVersion": "2.0.0",
  • "service": "leecher",
  • "hostname": "worker03",
  • "config": {
    }
}

Response samples

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

Delete Service

path Parameters
name
required
string (Name)

Responses

Response samples

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

Patch Service

path Parameters
service_name
required
string (Service Name)
Request Body schema: application/json
shouldRun
boolean (Shouldrun)
object (ServiceConfigModel)

Base API model.

Responses

Request samples

Content type
application/json
{
  • "shouldRun": true,
  • "config": {
    }
}

Response samples

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

List Hosts

Return a list of all hosts.

A host is an instance of Ayon Service Host (ASH) that is capable of running addon services. A host record in the database is created automatically when the host sends a heartbeat to the API.

Responses

Response samples

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

Host Heartbeat

Send a heartbeat from a host.

This endpoint is called by ASH to send a heartbeat to the API. The heartbeat contains information about the host, its health and the state of its services

Request Body schema: application/json
hostname
required
string (Hostname)
required
object (HostHealthModel)

Base API model.

services
Array of strings (List of running services)

Responses

Request samples

Content type
application/json
{
  • "hostname": "string",
  • "health": {
    },
  • "services": [
    ]
}

Response samples

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

System

Get Sites

Get list of sites

query Parameters
platform
string (Platform)
Enum: "windows" "linux" "darwin"
hostname
string (Hostname)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Site Info

Return site information.

This is the initial endpoint that is called when the user opens the page. It returns information about the site, the current user and the configuration.

If the user is not logged in, only the message of the day and the API version are returned.

Responses

Response samples

Content type
application/json
{
  • "motd": "Hello and welcome to Ayon!",
  • "loginPageBackground": "https://i.insider.com/602ee9d81a89f20019a377c6?width=1136&format=jpeg",
  • "loginPageBrand": "/static/brand.svg",
  • "releaseInfo": {
    },
  • "version": "string",
  • "uptime": 0,
  • "noAdminUser": true,
  • "onboarding": true,
  • "passwordRecoveryAvailable": true,
  • "user": {
    },
  • "attributes": [
    ],
  • "sites": [
    ],
  • "ssoOptions": [
    ]
}

Get Production Metrics

Get production related metrics

query Parameters
system
boolean (System)
Default: false

Collect system metrics

saturated
boolean (Saturated)
Default: false

Collect saturated (more granular) metrics

Responses

Response samples

Content type
application/json
{
  • "version": "1.3.1+202407231806",
  • "releaseInfo": {
    },
  • "uptime": 518163,
  • "system": {
    },
  • "userCounts": {
    },
  • "projectCounts": 1,
  • "projects": [
    ],
  • "averageProjectEventCount": 0,
  • "installedAddons": [
    ],
  • "eventTopics": {
    },
  • "productionBundle": {
    },
  • "studioSettingsOverrides": [
    ],
  • "services": [
    ]
}

Get System Metrics

Get system metrics in Prometheus format

Responses

Response samples

Content type
application/json
null

Request Server Restart

Responses

Response samples

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

Get Restart Required

Get the server restart required flag.

This will return whether the server requires a restart, and the reason for it.

Responses

Response samples

Content type
application/json
{
  • "required": true,
  • "reason": "string"
}

Set Restart Required

Set the server restart required flag.

This will notify the administrators that the server needs to be restarted. When the server is ready to restart, the administrator can use restart_server (using /api/system/restart) to trigger server.restart_requested event, which (captured by messaging) will trigger restart_server function and restart the server.

Human-readable reason for the restart can be provided in the reason field.

Request Body schema: application/json
required
required
boolean (Required)

Whether the server requires a restart

reason
string (Reason)

The reason for the restart

Responses

Request samples

Content type
application/json
{
  • "required": true,
  • "reason": "string"
}

Response samples

Content type
application/json
null

Tasks

Get Task

Retrieve a task by its ID.

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

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "modeling",
  • "label": "Modeling of a model",
  • "taskType": "Modeling",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "assignees": [
    ],
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "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 Task

Delete a task.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
task_id
required
string (Task ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

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

Update Task

Patch (partially update) a task.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
task_id
required
string (Task ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)
Request Body schema: application/json
name
string (Folder ID) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
label
string (Task label) ^[^';]*$
taskType
string (Task type)
thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
assignees
Array of strings (Assignees)

List of users assigned to the task

folderId
string (Folder ID) ^[0-f]{32}$

Folder ID

status
string (Task status)

Status of the task

tags
Array of strings (Task tags)

Tags assigned to the the task

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

Whether the task is active

Responses

Request samples

Content type
application/json
{
  • "name": "modeling",
  • "label": "Modeling of a model",
  • "taskType": "Modeling",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "assignees": [
    ],
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Create Task

Create a new task.

Use a POST request to create a new task (with a new id).

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 ID) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
label
string (Task label) ^[^';]*$
taskType
required
string (Task type)
thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
assignees
Array of strings (Assignees)

List of users assigned to the task

folderId
string (Folder ID) ^[0-f]{32}$

Folder ID

status
string (Task status)

Status of the task

tags
Array of strings (Task tags)

Tags assigned to the the task

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

Whether the task is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "name": "modeling",
  • "label": "Modeling of a model",
  • "taskType": "Modeling",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "assignees": [
    ],
  • "folderId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Assign Users To Task

Change the list of users assigned to a task.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
task_id
required
string (Task ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
Request Body schema: application/json
mode
required
string (Mode)
Enum: "add" "remove" "set"

What to do with the list of users

users
required
Array of strings (Users)

List of user names

Responses

Request samples

Content type
application/json
{
  • "mode": "add",
  • "users": [
    ]
}

Response samples

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

Teams

Get Teams

Get all teams in a project.

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Teams

Update teams.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
Array
name
required
string (Name)

Team name

Array of objects (Members)

Team members

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

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

Save Team

Save a team.

path Parameters
team_name
required
string (Team Name)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
required
Array of objects (Team members)
Array
name
required
string (User's name)
leader
boolean (Is user a leader)
Default: false
roles
Array of strings (User's role)

Responses

Request samples

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

Response samples

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

Delete Team

Delete a team.

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

Responses

Response samples

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

Save Team Member

Save a team member.

path Parameters
team_name
required
string (Team Name)
member_name
required
string (Member Name)
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
Request Body schema: application/json
name
required
string (User's name)
leader
boolean (Is user a leader)
Default: false
roles
Array of strings (User's role)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "leader": false,
  • "roles": [
    ]
}

Response samples

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

Delete Team Member

Delete a team member.

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

Responses

Response samples

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

Thumbnails

Create Thumbnail

Create a thumbnail.

This endpoint is used to create a thumbnail not associated with any entity. Returns the ID of the created thumbnail. which can be used to assign it to an entity.

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

Responses

Response samples

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

Get Thumbnail

Get a thumbnail by its ID.

This endpoint is used to retrieve a thumbnail by its ID. Since this is can be an security issue, this endpoint is only available to users with the manager role or higher.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
thumbnail_id
required
string (Thumbnail ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
query Parameters
placeholder
string (Placeholder)
Default: "empty"
Enum: "empty" "none"

Responses

Response samples

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

Update Thumbnail

Create or update a thumbnail with a specific ID.

This endpoint is used to create or update a thumbnail by its ID. Since this is can be an security issue, this endpoint is only available to users with the manager role or higher.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
thumbnail_id
required
string (Thumbnail ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
content-type
string (Content-Type)

Responses

Response samples

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

Get Folder Thumbnail

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
placeholder
string (Placeholder)
Default: "empty"
Enum: "empty" "none"

Responses

Response samples

Content type
application/json
null

Create Folder Thumbnail

Create a new thumbnail for a folder.

Returns a thumbnail ID, which is also saved into the entity database record.

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
content-type
string (Content-Type)

Responses

Response samples

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

Get Version Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
version_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
query Parameters
placeholder
string (Placeholder)
Default: "empty"
Enum: "empty" "none"

Responses

Response samples

Content type
application/json
null

Create Version Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
version_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
content-type
string (Content-Type)

Responses

Response samples

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

Get Workfile Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
workfile_id
required
string (Workfile ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
query Parameters
placeholder
string (Placeholder)
Default: "empty"
Enum: "empty" "none"

Responses

Response samples

Content type
application/json
null

Create Workfile Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
workfile_id
required
string (Workfile ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
content-type
string (Content-Type)

Responses

Response samples

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

Get Task Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
task_id
required
string (Task ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
query Parameters
placeholder
string (Placeholder)
Default: "empty"
Enum: "empty" "none"

Responses

Response samples

Content type
application/json
null

Create Task Thumbnail

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
task_id
required
string (Task ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
content-type
string (Content-Type)

Responses

Response samples

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

Users

Get Avatar

Retrieve the avatar for a given user.

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
null

Upload Avatar

Uploads a new avatar for the specified user.

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
null

Delete Avatar

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
null

Password Reset Request

Request Body schema: application/json
email
required
string (Email)
url
required
string (Url)

Responses

Request samples

Content type
application/json
{
  • "email": "you@somewhere.com",
  • "url": "string"
}

Response samples

Content type
application/json
null

Password Reset

Request Body schema: application/json
token
required
string (Token)
password
string (New password)

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "string"
}

Response samples

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

Get Current User

Return the current user information (based on the Authorization header). This is used for a profile page as well as as an initial check to ensure the user is still logged in.

Responses

Response samples

Content type
application/json
{
  • "name": "awesome_user",
  • "attrib": {
    },
  • "data": { },
  • "active": true,
  • "ownAttrib": [
    ],
  • "createdAt": "2023-01-01T00:00:00+00:00",
  • "updatedAt": "2023-01-01T00:00:00+00:00"
}

Get User

Return the current user information (based on the Authorization header). This is used for a profile page as well as as an initial check to ensure the user is still logged in.

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
Example
{
  • "name": "awesome_user",
  • "attrib": {
    },
  • "data": { },
  • "active": true,
  • "ownAttrib": [
    ],
  • "createdAt": "2023-01-01T00:00:00+00:00",
  • "updatedAt": "2023-01-01T00:00:00+00:00"
}

Create User

Create a new user.

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
object (User attributes)
data
object (User auxiliary data)
active
boolean (User active)
Default: true

Whether the user is active

password
string (Password)

Password for the new user

apiKey
string (Apikey)

API Key for the new service user

Responses

Request samples

Content type
application/json
{
  • "attrib": {
    },
  • "data": { },
  • "active": true,
  • "password": "string",
  • "apiKey": "string"
}

Response samples

Content type
application/json
null

Delete User

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
null

Patch User

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
object (User attributes)
data
object (User auxiliary data)
active
boolean (User active)
Default: true

Whether the user is active

Responses

Request samples

Content type
application/json
{
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

Content type
application/json
null

Change Password

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
password
string (Password)

New password

apiKey
string (API Key) ^[0-9a-f]{32}$

API Key to set to a service user

Responses

Request samples

Content type
application/json
{
  • "password": "5up3r5ecr3t_p455W0rd.123",
  • "apiKey": "1cb4f6a89012a4b6d8a01ee4f67ae0fb"
}

Response samples

Content type
application/json
null

Check Password

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
password
required
string (Password)

Responses

Request samples

Content type
application/json
{
  • "password": "5up3r5ecr3t_p455W0rd.123"
}

Response samples

Content type
application/json
null

Change User Name

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
newName
required
string (Newname) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

New user name

Responses

Request samples

Content type
application/json
{
  • "newName": "EvenBetterUser"
}

Response samples

Content type
application/json
null

Get User Sessions

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

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

Delete User Session

path Parameters
session_id
required
string (Session Id)
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$

Responses

Response samples

Content type
application/json
null

Assign Access Groups

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
Array of objects (Accessgroups)

List of access groups to assign

Array
project
required
string (Project)

Project name

accessGroups
required
Array of strings (Accessgroups)

List of access groups on the project

Responses

Request samples

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

Response samples

Content type
application/json
null

Set Frontend Preferences

path Parameters
user_name
required
string (User name) ^[a-zA-Z0-9][a-zA-Z0-9_\.\-]*[a-zA-Z0-9]$
Request Body schema: application/json
object (Patch Data)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Versions

Get Version

Retrieve a version by its ID.

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

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "version": 1,
  • "productId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "author": "john_doe",
  • "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 Version

Delete a version.

This will also delete all representations of the version.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
version_id
required
string (Version ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

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

Update Version

Patch (partially update) a version.

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

Version number

productId
string (Product ID) ^[0-f]{32}$

ID of the parent product

taskId
string (Task ID) ^[0-f]{32}$
thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
author
string (Author) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
status
string (Version status)

Status of the version

tags
Array of strings (Version tags)

Tags assigned to the the version

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

Whether the version is active

Responses

Request samples

Content type
application/json
{
  • "version": 1,
  • "productId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "author": "john_doe",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Create Version

Create a new version.

Use a POST request to create a new version (with a new id).

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

version
required
integer (Version)

Version number

productId
required
string (Product ID) ^[0-f]{32}$

ID of the parent product

taskId
string (Task ID) ^[0-f]{32}$
thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
author
string (Author) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
status
string (Version status)

Status of the version

tags
Array of strings (Version tags)

Tags assigned to the the version

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

Whether the version is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "version": 1,
  • "productId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "author": "john_doe",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Workfiles

Get Workfile

Retrieve a version by its ID.

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

Responses

Response samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "path": "{root['work']}/Project/workfiles/ma/modelMain_v001.ma",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "createdBy": "john_doe",
  • "updatedBy": "john_doe",
  • "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 Workfile

Delete a workfile.

path Parameters
project_name
required
string (Project name) ^[a-zA-Z0-9_]*$
workfile_id
required
string (Workfile ID) = 32 characters ^[0-9a-f]{32}$
Example: af10c8f0e9b111e9b8f90242ac130003
header Parameters
x-sender
string (X-Sender)

Responses

Response samples

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

Update Workfile

Patch (partially update) a workfile.

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

Path to the workfile

taskId
string (Task ID) ^[0-f]{32}$

ID of the parent task

thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
createdBy
string (Createdby) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
updatedBy
string (Updatedby) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
status
string (Workfile status)

Status of the workfile

tags
Array of strings (Workfile tags)

Tags assigned to the the workfile

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

Whether the workfile is active

Responses

Request samples

Content type
application/json
{
  • "path": "{root['work']}/Project/workfiles/ma/modelMain_v001.ma",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "createdBy": "john_doe",
  • "updatedBy": "john_doe",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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

Create Workfile

Create a new workfile.

Use a POST request to create a new workfile

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

path
required
string (Path)

Path to the workfile

taskId
required
string (Task ID) ^[0-f]{32}$

ID of the parent task

thumbnailId
string (Thumbnail ID) ^[0-f]{32}$
createdBy
string (Createdby) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
updatedBy
string (Updatedby) ^[a-zA-Z0-9_]([a-zA-Z0-9_\.\-]*[a-zA-Z0-9_])?...
status
string (Workfile status)

Status of the workfile

tags
Array of strings (Workfile tags)

Tags assigned to the the workfile

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

Whether the workfile is active

Responses

Request samples

Content type
application/json
{
  • "id": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "path": "{root['work']}/Project/workfiles/ma/modelMain_v001.ma",
  • "taskId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "thumbnailId": "c10d5bc73dcab7da4cba0f3e0b3c0aea",
  • "createdBy": "john_doe",
  • "updatedBy": "john_doe",
  • "status": "In progress",
  • "tags": [
    ],
  • "attrib": {
    },
  • "data": { },
  • "active": true
}

Response samples

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