Ayon Backend

https://github.com/ynput/ayon-backend
Admin
Ayon Backend is the Python server backend for the Ayon project management and pipeline system.
Tokens:58,999
Snippets:745
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Integration Example: Get Folder Details

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/dependencies.md

Demonstrates fetching folder details using CurrentUser, ProjectName, and FolderID dependencies. Requires authentication and validates project and folder identifiers.

```python
from fastapi import APIRouter
from ayon_server.api.dependencies import (
    CurrentUser,
    ProjectName,
    FolderID,
    AllowGuests,
    CurrentUserOptional,
)

router = APIRouter(prefix="/projects")

@router.get("/{project_name}/folders/{folder_id}")
async def get_folder(
    user: CurrentUser,
    project_name: ProjectName,
    folder_id: FolderID,
) -> dict:
    """Get folder details. Requires authentication."""
    # user is authenticated
    # project_name is validated and accessible
    # folder_id is validated format
    return {"folder": folder_id}
```

--------------------------------

### Get Project Details Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieving project details returns comprehensive information including configuration and hierarchy.

```json
{
  "name": "myproject",
  "code": "PROJ",
  "active": true,
  "config": { /* project configuration */ },
  "hierarchy": [ /* entity hierarchy */ ],
  "anatomy": { /* project anatomy */ }
}
```

--------------------------------

### Install Addon

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Install a specific addon by its name and version.

```http
POST /api/addons/install
{
  "addonName": "addon_name",
  "addonVersion": "1.0.0"
}
```

--------------------------------

### POST /addons/install

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Initiates the installation of a new addon.

```APIDOC
## POST /addons/install

### Description
Install a new addon.

### Method
POST

### Endpoint
/api/addons/install

### Request Body
- **addonName** (string) - Required
- **addonVersion** (string) - Required

### Request Example
```json
{
  "addonName": "new_addon",
  "addonVersion": "1.0.0"
}
```

### Response
#### Success Response (202 Accepted)
Installation process started.

### Status Codes
- `202`: Installation started
- `400`: Invalid request
```

--------------------------------

### PostgreSQL Database Access Examples

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/OVERVIEW.md

Examples demonstrating how to interact with the PostgreSQL database using the `Postgres` library. Includes simple queries, fetching single rows, scalar values, and transactions.

```python
from ayon_server.lib.postgres import Postgres

# Simple query
rows = await Postgres.fetch(
    "SELECT * FROM public.users WHERE active = $1",
    True
)

# Single row
user = await Postgres.fetchone(
    "SELECT * FROM public.users WHERE name = $1",
    "admin"
)

# Scalar value
count = await Postgres.fetchval(
    "SELECT COUNT(*) FROM public.users"
)

# Transaction
async with Postgres.transaction() as conn:
    await conn.execute("INSERT INTO ...")
    await conn.execute("UPDATE ...")
```

--------------------------------

### Install Addon Request

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Submit a request to install a new addon, specifying its name and version.

```json
{
  "addonName": "new_addon",
  "addonVersion": "1.0.0"
}
```

--------------------------------

### Install Addon

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Installs a specified addon with a given version.

```APIDOC
## POST /api/addons/install

### Description
Installs an addon.

### Method
POST

### Endpoint
/api/addons/install

### Parameters
#### Request Body
- **addonName** (string) - Required - The name of the addon to install.
- **addonVersion** (string) - Required - The version of the addon to install.
```

--------------------------------

### Integration Example: Public Endpoint with Guests

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/dependencies.md

Example of a public endpoint that allows both authenticated users and guests. It uses CurrentUserOptional and AllowGuests dependencies.

```python
@router.get("/{project_name}/public", dependencies=[AllowGuests])
async def get_public_info(
    user: CurrentUserOptional,
    project_name: ProjectName,
) -> dict:
    """Public endpoint that allows guests."""
    if user:
        return {"message": f"Hello {user.name}"}
    return {"message": "Hello guest"}
```

--------------------------------

### GET /addons

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all installed addons, with an option to include version information.

```APIDOC
## GET /addons

### Description
List all installed addons.

### Method
GET

### Endpoint
/api/addons

### Query Parameters
#### Query Parameters
- **includeVersion** (boolean) - Optional - Include version info

### Response
#### Success Response (200 OK)
- **addons** (array)
  - **name** (string)
  - **versions** (array of strings)
  - **enabled** (boolean)

### Response Example
```json
{
  "addons": [
    {
      "name": "addon_name",
      "versions": ["1.0.0", "1.1.0"],
      "enabled": true
    }
  ]
}
```

### Auth
Not required (AllowGuests)
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/server-app.md

An example of a GraphQL query to retrieve project information, including its name, code, and associated folders with their statuses. Requires authentication.

```graphql
query {
  project(name: "myproject") {
    name
    code
    folders {
      name
      status
    }
  }
}
```

--------------------------------

### List Installed Addons

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieve a list of all installed addons, with an option to include version information.

```json
{
  "addons": [
    {
      "name": "addon_name",
      "versions": ["1.0.0", "1.1.0"],
      "enabled": true
    }
  ]
}
```

--------------------------------

### Create Project Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Upon successful creation, the server returns the details of the newly created project.

```json
{
  "name": "newproject",
  "code": "NEW",
  "active": true
}
```

--------------------------------

### Start Ayon Backend Server

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/README.md

Run the Ayon backend server using the Python module.

```bash
python -m ayon_server
```

--------------------------------

### Login Response Model Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/authentication.md

An example of the JSON response structure returned after a successful login. It includes a detail message, the JWT access token, and user information.

```json
{
  "detail": "Logged in as admin",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "name": "admin",
    "fullName": "Administrator",
    "email": "admin@example.com",
    "active": true,
    "isManager": true,
    "isService": false,
    "isGuest": false
  }
}
```

--------------------------------

### Example Ayon Environment Variables

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/configuration.md

Illustrates the format for setting Ayon configuration options via environment variables. These variables are used for server startup configuration.

```bash
# Example environment variables
export AYON_HTTP_LISTEN_PORT=8000
export AYON_POSTGRES_URL="postgres://user:pass@db:5432/ayon"
export AYON_REDIS_URL="redis://cache:6379"
export AYON_LOG_LEVEL=INFO
export AYON_AUTH_PASS_COMPLEX=true
export AYON_SESSION_TTL=259200
```

--------------------------------

### Loading and Creating Entities

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/OVERVIEW.md

Examples of loading existing entities (Project, Folder) by name or ID, and creating new entities. Includes saving new entities with user context.

```python
from ayon_server.entities import ProjectEntity, FolderEntity

# Load by name
project = await ProjectEntity.load("myproject")

# Load by ID in project
folder = await FolderEntity.load("folder_id", "myproject")

# Create new
folder = FolderEntity({
    "name": "new_folder",
    "projectName": "myproject",
})
await folder.save(user=current_user)
```

--------------------------------

### Login Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

A successful login returns a detail message, an access token, and user information.

```json
{
  "detail": "Logged in as admin",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "name": "admin",
    "fullName": "Administrator",
    "email": "admin@example.com",
    "active": true,
    "isService": false,
    "isGuest": false
  }
}
```

--------------------------------

### Create Project Request Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Use this JSON payload to create a new project, specifying its name, code, and configuration.

```json
{
  "name": "newproject",
  "code": "NEW",
  "config": {
    "roots": {
      "work": "/mnt/projects/work",
      "publish": "/mnt/projects/publish"
    }
  }
}
```

--------------------------------

### List Projects Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieving a list of projects returns an array of project objects, each with basic information.

```json
{
  "projects": [
    {
      "name": "myproject",
      "code": "PROJ",
      "active": true,
      "createdAt": "2023-01-15T10:30:00Z",
      "updatedAt": "2024-06-05T14:22:00Z",
      "hasHierarchy": false
    }
  ]
}
```

--------------------------------

### GET /system/info

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieve general information about the system, including version and environment details.

```APIDOC
## GET /system/info

### Description
Get system information.

### Method
GET

### Endpoint
/api/system/info

### Response
#### Success Response (200 OK)
```json
{
  "version": "1.15.5",
  "pythonVersion": "3.11.0",
  "startTime": "2024-06-01T10:00:00Z",
  "environment": "production"
}
```

### Auth
Not required (AllowGuests)
```

--------------------------------

### Create and Save New Folder

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/entity-classes.md

Example of creating and saving a new folder within a project. Requires loading the parent project first.

```python
from ayon_server.entities import FolderEntity, ProjectEntity

# Load parent project
project = await ProjectEntity.load("myproject")
```

--------------------------------

### Example Semantic Commit: Feature

Source: https://github.com/ynput/ayon-backend/blob/develop/CONTRIBUTING.md

An example of a semantic commit message for adding a new feature to the settings.

```git
feat(settings): add settings copy

```

--------------------------------

### Get Documentation

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves the API documentation.

```APIDOC
## GET /api/docs

### Description
Retrieves the API documentation.

### Method
GET

### Endpoint
/api/docs
```

--------------------------------

### Get Documentation

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve API documentation, likely in HTML format.

```http
GET /api/docs
```

--------------------------------

### Create Custom Router Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/server-app.md

Demonstrates how to create and register a custom API router using FastAPI. This allows for modular API extensions, with routes automatically discovered and mounted under the `/api/` prefix.

```python
from fastapi import APIRouter
from ayon_server.api.dependencies import CurrentUser, ProjectName

router = APIRouter(prefix="/custom", tags=["Custom"])

@router.get("/projects/{project_name}/info")
async def get_project_info(
    user: CurrentUser,
    project_name: ProjectName,
) -> dict:
    """Get custom project information."""
    return {
        "project": project_name,
        "user": user.name,
        "access": "granted"
    }

# In your API module, export the router:
# __all__ = ["router"]
```

--------------------------------

### Subscription Client Setup

Source: https://github.com/ynput/ayon-backend/blob/develop/static/graphiql/index.html

Initializes a WebSocket client for GraphQL subscriptions if enabled. It uses the converted endpoint URL and reconnection options.

```javascript
var subscriptionsEndpoint = httpUrlToWebSockeUrl(fetchURL);
//var subscriptionsEnabled = JSON.parse('{SUBSCRIPTION\_ENABLED }}')
var subscriptionsEnabled = false;
const subscriptionsClient = subscriptionsEnabled ? new window.SubscriptionsTransportWs.SubscriptionClient(
    subscriptionsEndpoint,
    {
      reconnect: true
    }
) : null;
```

--------------------------------

### GET /versions

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all versions within a project, with optional filtering.

```APIDOC
## GET /versions

### Description
List all versions.

### Method
GET

### Endpoint
/api/projects/{project_name}/versions

#### Query Parameters
- **productId** (string) - Optional - Filter by product ID
- **status** (string) - Optional - Filter by status

### Response
#### Success Response (200 OK)
- **versions** (array) - A list of version objects
  - **id** (string) - Version ID
  - **version** (integer) - Version number
  - **productId** (string) - The ID of the product this version belongs to
  - **status** (string) - The status of the version
  - **createdAt** (string) - Timestamp of creation

#### Response Example
{
  "versions": [
    {
      "id": "version_id_32chars",
      "version": 1,
      "productId": "product_id_32chars",
      "status": "Published",
      "createdAt": "2024-06-01T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Logout Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

A successful logout returns a confirmation message.

```json
{
  "detail": "Logged out successfully"
}
```

--------------------------------

### Get System Info

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves general information about the Ayon system.

```APIDOC
## GET /api/system/info

### Description
Retrieves information about the Ayon system.

### Method
GET

### Endpoint
/api/system/info

### Response
#### Success Response (200)
- **version** (string) - The Ayon server version.
- **pythonVersion** (string) - The Python version used by the server.
- **startTime** (string) - The timestamp when the server started.

#### Response Example
```json
{
  "version": "1.15.5",
  "pythonVersion": "3.11.0",
  "startTime": "2024-06-01T10:00:00Z"
}
```
```

--------------------------------

### GraphQL Query Request

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Example request for executing a GraphQL query to retrieve project information.

```json
{
  "query": "query { project(name: \"myproject\") { name } }"
}
```

--------------------------------

### Get Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves details for a specific project by its name.

```APIDOC
## GET /api/projects/{project_name}

### Description
Retrieves details for a specific project.

### Method
GET

### Endpoint
/api/projects/{project_name}

### Parameters
#### Path Parameters
- **project_name** (string) - Required - The name of the project to retrieve.
```

--------------------------------

### Get System Info

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve information about the Ayon system, including version, Python version, and startup time.

```http
GET /api/system/info

Response:
{
  "version": "1.15.5",
  "pythonVersion": "3.11.0",
  "startTime": "2024-06-01T10:00:00Z"
}
```

--------------------------------

### Querying Users in a Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/OVERVIEW.md

Example of querying user data from the database, specifically filtering for active users within a project context.

```python
from ayon_server.lib.postgres import Postgres

# Users in a project
users = await Postgres.fetch(
    "SELECT * FROM public.users WHERE active = $1",
    True
)
```

--------------------------------

### Check Server System Info

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/server-app.md

Use this command to get general information about the server's status and configuration. No authentication is required.

```bash
curl http://localhost:5000/api/system/info
```

--------------------------------

### Get Specific Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve details for a specific project by its name.

```http
GET /api/projects/{project_name}
```

--------------------------------

### Protected Endpoint Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/authentication.md

Demonstrates how to create an endpoint that requires authentication. The `CurrentUser` dependency injects the authenticated user's data.

```python
from ayon_server.api.dependencies import CurrentUser

@router.get("/profile")
async def get_profile(user: CurrentUser) -> dict:
    """Get authenticated user's profile."""
    return {
        "name": user.name,
        "email": user.attrib.email,
        "isManager": user.is_manager,
    }
```

--------------------------------

### Set Environment Variables for Configuration

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/README.md

Provides examples of environment variables used to configure the Ayon server. These variables control database connections, ports, and logging levels.

```bash
export AYON_POSTGRES_URL="postgres://user:pass@host/db"
export AYON_REDIS_URL="redis://host:6379"
export AYON_HTTP_LISTEN_PORT=5000
export AYON_LOG_LEVEL=INFO
```

--------------------------------

### Create Custom API Module

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Example of creating a custom API module in Python using FastAPI, defining a router with a GET endpoint.

```python
from fastapi import APIRouter

router = APIRouter(prefix="/mymodule")

@router.get("/info")
async def get_info() -> dict:
    return {"message": "Hello"}
```

--------------------------------

### GET /projects

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all projects in the Ayon system. Supports filtering by active status.

```APIDOC
## GET /projects

### Description
List all projects.

### Method
GET

### Endpoint
/api/projects

### Query Parameters
- **active** (boolean) - Optional - Filter by active status

### Response
#### Success Response (200 OK)
- **projects** (array) - List of project objects.
  - **name** (string)
  - **code** (string)
  - **active** (boolean)
  - **createdAt** (string) - ISO 8601 format
  - **updatedAt** (string) - ISO 8601 format
  - **hasHierarchy** (boolean)

#### Response Example
```json
{
  "projects": [
    {
      "name": "myproject",
      "code": "PROJ",
      "active": true,
      "createdAt": "2023-01-15T10:30:00Z",
      "updatedAt": "2024-06-05T14:22:00Z",
      "hasHierarchy": false
    }
  ]
}
```

### Status Codes
- `200`: Success
- `401`: Not authenticated
```

--------------------------------

### List Folders Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieving a list of folders returns an array of folder objects, each with its ID, parent, name, and other properties.

```json
{
  "folders": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p",
      "parentId": null,
      "name": "shots",
      "label": "Shots",
      "folderType": "Folder",
      "thumbnailId": null,
      "status": "In Progress",
      "active": true
    }
  ]
}
```

--------------------------------

### Login Request Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Use this JSON payload to authenticate with the Ayon server using username and password.

```json
{
  "name": "admin",
  "password": "SecurePassword123"
}
```

--------------------------------

### Create and Save FolderEntity

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/entity-classes.md

Demonstrates how to create a new FolderEntity instance and save it to the database. Requires project name and basic folder details.

```python
from ayon_server.entities import FolderEntity

folder = FolderEntity(
    {
        "name": "shots",
        "label": "Shots",
        "folderType": "Folder",
        "projectName": "myproject",
        "parentId": None,
        "status": "Active",
    }
)

await folder.save()
```

--------------------------------

### Cookie Authentication

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Example of how an access token might be sent via a Cookie header.

```http
Cookie: accessToken=token-value
```

--------------------------------

### Create Protected Endpoint Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/server-app.md

Shows how to create a protected API endpoint that requires authentication. It defines a response model using `OPModel` and uses `CurrentUser` dependency to access authenticated user details.

```python
from fastapi import APIRouter
from ayon_server.api.dependencies import CurrentUser
from ayon_server.types import OPModel, Field

router = APIRouter(prefix="/mymodule")

class ResponseModel(OPModel):
    message: str = Field(..., description="Response message")
    user: str = Field(..., description="Authenticated user")

@router.get(
    "/protected",
    response_model=ResponseModel,
    summary="Protected endpoint",
    description="This endpoint requires authentication"
)
async def protected_endpoint(user: CurrentUser) -> ResponseModel:
    """Access protected resource."""
    return ResponseModel(
        message="Access granted",
        user=user.name
    )

# Export for auto-registration
__all__ = ["router"]
```

--------------------------------

### Example Semantic Commit: Fix

Source: https://github.com/ynput/ayon-backend/blob/develop/CONTRIBUTING.md

An example of a semantic commit message for fixing an issue in authentication.

```git
fix(auth): fix session expiration

```

--------------------------------

### Load and Access Ayon Configuration

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/configuration.md

Demonstrates how to load the Ayon configuration and access individual settings or check feature flags. This code should be run at server startup.

```python
from ayon_server.config.ayonconfig import load_config, ayonconfig

# Get current configuration
config = ayonconfig

# Access a setting
listen_port = config.http_listen_port
db_url = config.postgres_url

# Check if feature enabled
if config.audit_trail:
    # Enable audit logging
    pass
```

--------------------------------

### Build and execute an update query using SQLTool

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/database-redis.md

This example demonstrates using SQLTool to dynamically build an UPDATE query from a dictionary of fields and values, which is then executed via the Postgres class. Ensure you have imported SQLTool and datetime.

```python
from ayon_server.utils import SQLTool
from datetime import datetime

# Build update query
updates = {"status": "published", "updatedAt": datetime.utcnow()}
query, values = SQLTool.build_update_query(updates)

await Postgres.execute(
    f"UPDATE project_myproject.versions SET {query} WHERE id = $1",
    *values,
    "version_id"
)
```

--------------------------------

### API Key Creation Response

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/authentication.md

Example response after successfully creating an API key. Includes the key's ID, the secret key, its name, and creation timestamp.

```json
{
  "id": "api_key_id",
  "key": "ayon_sk_...",
  "name": "Integration API Key",
  "createdAt": "2024-06-05T10:30:00Z"
}
```

--------------------------------

### GET /addons/{addon_name}/{version}/schema/{project_name}

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves the project settings schema for a specific addon version.

```APIDOC
## GET /addons/{addon_name}/{version}/schema/{project_name}

### Description
Get addon project settings schema.

### Method
GET

### Endpoint
/api/addons/{addon_name}/{version}/schema/{project_name}

### Response
#### Success Response (200 OK)
Schema for addon project settings.
```

--------------------------------

### Example Semantic Commit: Feature (No Scope)

Source: https://github.com/ynput/ayon-backend/blob/develop/CONTRIBUTING.md

An example of a semantic commit message for adding a video preview endpoint without specifying a scope.

```git
feat: add video preview endpoint

```

--------------------------------

### System Info Response

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Response format for retrieving system information, including Ayon version, Python version, start time, and environment.

```json
{
  "version": "1.15.5",
  "pythonVersion": "3.11.0",
  "startTime": "2024-06-01T10:00:00Z",
  "environment": "production"
}
```

--------------------------------

### Token Authentication Callback Response Example

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

The callback handler for token authentication returns a success message, a new token, and user details.

```json
{
  "detail": "Token authenticated",
  "token": "new-access-token",
  "user": { /* user object */ }
}
```

--------------------------------

### API Key Authentication Header

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Examples of using an API key for authentication via the X-API-Key or Authorization header.

```http
X-API-Key: your-api-key
```

```http
Authorization: ApiKey your-api-key
```

--------------------------------

### Create API Key Request

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/authentication.md

Example of a POST request to create an API key for a user. The request body should contain the desired name for the API key.

```json
{
  "name": "Integration API Key"
}
```

--------------------------------

### get_folder

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/dependencies.md

Get folder details. Requires authentication.

```APIDOC
## GET /projects/{project_name}/folders/{folder_id}

### Description
Get folder details. Requires authentication.

### Method
GET

### Endpoint
`/projects/{project_name}/folders/{folder_id}`

### Parameters
#### Path Parameters
- **project_name** (ProjectName) - Required - The name of the project.
- **folder_id** (FolderID) - Required - The ID of the folder.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **folder** (dict) - Details of the folder.

### Request Example
None

### Response Example
```json
{
  "folder": "folder_id"
}
```
```

--------------------------------

### GET /accessGroups/_schema

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves the schema definition for access groups.

```APIDOC
## GET /accessGroups/_schema

### Description
Get access group schema.

### Method
GET

### Endpoint
/api/accessGroups/_schema

### Response
#### Success Response (200 OK)
- **schema** (object) - Schema definition for access groups

### Response Example
```json
{
  "schema": { /* schema definition */ }
}
```
```

--------------------------------

### Create Product

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Create a new product within a project. Requires product name, type, and associated folder ID.

```http
POST /api/projects/{project_name}/products
{
  "name": "main",
  "type": "render",
  "folderId": "{folder_id}"
}
```

--------------------------------

### GET /representations

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all representations for a project, with optional filtering.

```APIDOC
## GET /representations

### Description
List all representations.

### Method
GET

### Endpoint
/api/projects/{project_name}/representations

#### Query Parameters
- **versionId** (string) - Optional - Filter by version ID

### Response
#### Success Response (200 OK)
- **representations** (array) - A list of representation objects
  - **id** (string) - Representation ID
  - **name** (string) - Representation name
  - **versionId** (string) - The ID of the version this representation belongs to
  - **files** (array) - References to the files associated with this representation

#### Response Example
{
  "representations": [
    {
      "id": "repr_id_32chars",
      "name": "main",
      "versionId": "version_id_32chars",
      "files": [ /* file references */ ]
    }
  ]
}
```

--------------------------------

### Create New Product

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Creates a new product within a project. Requires product name, type, and folder ID.

```json
{
  "name": "newproduct",
  "type": "render",
  "folderId": "folder_id_32chars"
}
```

```json
{
  "id": "new_product_id",
  "name": "newproduct"
}
```

--------------------------------

### Cache Data with Redis

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/README.md

Demonstrates how to set and get data from the Redis cache. This is useful for storing frequently accessed data with a Time-To-Live (TTL).

```python
from ayon_server.lib.redis import Redis

await Redis.set("key", data, ttl=3600)
value = await Redis.get("key")
```

--------------------------------

### FastAPI Dependency Injection for Auth and Validation

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/OVERVIEW.md

Example of using FastAPI dependencies for authentication (`CurrentUser`) and validation (`ProjectName`, `FolderID`). Parameters are automatically validated.

```python
from ayon_server.api.dependencies import (
    CurrentUser,  # Authenticated user (required)
    ProjectName,  # Validated project name
    FolderID,  # Validated folder ID
)

@router.get("/projects/{project_name}/folders/{folder_id}")
async def get_folder(
    user: CurrentUser,
    project_name: ProjectName,
    folder_id: FolderID,
) -> dict:
    # Parameters are automatically validated
    return {"folder": folder_id}
```

--------------------------------

### Get Avatar

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves the avatar image for a specific user.

```APIDOC
## GET /api/users/{user_name}/avatar

### Description
Retrieves the avatar image for a user.

### Method
GET

### Endpoint
/api/users/{user_name}/avatar

### Parameters
#### Path Parameters
- **user_name** (string) - Required - The name of the user whose avatar is being retrieved.
```

--------------------------------

### Get User

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves details for a specific user by their name.

```APIDOC
## GET /api/users/{user_name}

### Description
Retrieves details for a specific user.

### Method
GET

### Endpoint
/api/users/{user_name}

### Parameters
#### Path Parameters
- **user_name** (string) - Required - The name of the user to retrieve.
```

--------------------------------

### Create Version

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Create a new version for a product. Specify product ID, version number, and status.

```http
POST /api/projects/{project_name}/versions
{
  "productId": "{product_id}",
  "version": 1,
  "status": "Published"
}
```

--------------------------------

### Create Product

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Creates a new product within a specified project.

```APIDOC
## POST /api/projects/{project_name}/products

### Description
Creates a new product within a project.

### Method
POST

### Endpoint
/api/projects/{project_name}/products

### Parameters
#### Path Parameters
- **project_name** (string) - Required - The name of the project.

#### Request Body
- **name** (string) - Required - The name of the product.
- **type** (string) - Required - The type of the product (e.g., 'render').
- **folderId** (string) - Required - The ID of the folder this product belongs to.
```

--------------------------------

### GET /users/{user_name}

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves details for a specific user by their username.

```APIDOC
## GET /users/{user_name}

### Description
Get user details.

### Method
GET

### Endpoint
/api/users/{user_name}

### Parameters
#### Path Parameters
- **user_name** (string) - Required - Username

### Response
#### Success Response (200 OK)
- **name** (string)
- **fullName** (string)
- **email** (string)
- **active** (boolean)
- **isManager** (boolean)
- **avatarUrl** (string)
- **accessGroups** (object) - access groups

### Response Example
```json
{
  "name": "admin",
  "fullName": "Administrator",
  "email": "admin@example.com",
  "active": true,
  "isManager": true,
  "avatarUrl": "https://example.com/avatar.jpg",
  "accessGroups": { /* access groups */ }
}
```

### Status Codes
- `200`: Success
- `404`: User not found
```

--------------------------------

### GraphQL Explorer CSS and Initialization

Source: https://github.com/ynput/ayon-backend/blob/develop/static/graphiql/index.html

Basic CSS for the GraphiQL container and JavaScript for initializing the explorer with a fetcher. It sets up the fetch URL and retrieves an access token.

```html
html, body { height: 100%; margin: 0; overflow: hidden; width: 100%; } #graphiql { height: 100vh; }
```

```javascript
var fetchURL = "/graphql";
var accessToken = localStorage.getItem("accessToken")
```

--------------------------------

### GET /workfiles

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all workfiles within a project, with optional filtering.

```APIDOC
## GET /workfiles

### Description
List all workfiles.

### Method
GET

### Endpoint
/api/projects/{project_name}/workfiles

#### Query Parameters
- **taskId** (string) - Optional - Filter by task ID
- **user** (string) - Optional - Filter by user

### Response
#### Success Response (200 OK)
```

--------------------------------

### Create Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Create a new project in the Ayon system. Requires a project name, code, and configuration details.

```http
PUT /api/projects/{project_name}
{
  "code": "PROJ",
  "config": { /* config */ }
}
```

--------------------------------

### Get OpenAPI Schema

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves the OpenAPI specification for the Ayon API.

```APIDOC
## GET /api/openapi.json

### Description
Retrieves the OpenAPI specification for the Ayon API.

### Method
GET

### Endpoint
/api/openapi.json

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
```

--------------------------------

### List Versions in a Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve a list of all versions for products within a specified project.

```http
GET /api/projects/{project_name}/versions
```

--------------------------------

### Create Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Creates a new project with the specified name and configuration.

```APIDOC
## PUT /api/projects/{project_name}

### Description
Creates a new project.

### Method
PUT

### Endpoint
/api/projects/{project_name}

### Parameters
#### Path Parameters
- **project_name** (string) - Required - The name of the project to create.

#### Request Body
- **code** (string) - Required - A short code for the project.
- **config** (object) - Required - Configuration details for the project.
```

--------------------------------

### Get Folder

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves details for a specific folder within a project.

```APIDOC
## GET /api/projects/{project_name}/folders/{folder_id}

### Description
Retrieves details for a specific folder.

### Method
GET

### Endpoint
/api/projects/{project_name}/folders/{folder_id}

### Parameters
#### Path Parameters
- **project_name** (string) - Required - The name of the project.
- **folder_id** (string) - Required - The ID of the folder.
```

--------------------------------

### Create and Save a New Folder Entity

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/entity-classes.md

Demonstrates how to instantiate and save a new FolderEntity to the database. Ensure the 'current_user' object is available in the scope.

```python
from ayon_server.entities import FolderEntity

# Create new folder
folder = FolderEntity(
    {
        "name": "shots",
        "label": "Shots",
        "folderType": "Folder",
        "projectName": "myproject",
        "status": "Active",
    }
)

# Save to database
await folder.save(user=current_user)

print(f"Created folder: {folder.id}")
```

--------------------------------

### Get User Avatar

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve the avatar image for a specific user.

```http
GET /api/users/{user_name}/avatar
```

--------------------------------

### POST /projects

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Creates a new project with specified name, code, and configuration.

```APIDOC
## POST /projects

### Description
Create a new project.

### Method
POST

### Endpoint
/api/projects

### Request Body
- **name** (string) - Required - Name of the new project
- **code** (string) - Required - Project code
- **config** (object) - Optional - Project configuration
  - **roots** (object)
    - **work** (string)
    - **publish** (string)

### Request Example
```json
{
  "name": "newproject",
  "code": "NEW",
  "config": {
    "roots": {
      "work": "/mnt/projects/work",
      "publish": "/mnt/projects/publish"
    }
  }
}
```

### Response
#### Success Response (201 Created)
- **name** (string) - Name of the created project.
- **code** (string) - Code of the created project.
- **active** (boolean) - Active status of the created project.

#### Response Example
```json
{
  "name": "newproject",
  "code": "NEW",
  "active": true
}
```

### Status Codes
- `201`: Project created
- `400`: Invalid request
- `403`: Insufficient permissions
- `409`: Project already exists
```

--------------------------------

### Get Specific User

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve details for a specific user by their username.

```http
GET /api/users/{user_name}
```

--------------------------------

### GraphiQL Initialization with Subscriptions

Source: https://github.com/ynput/ayon-backend/blob/develop/static/graphiql/index.html

Renders the GraphiQL component with a fetcher that supports subscriptions. It integrates the subscription client with the main fetcher.

```javascript
const graphQLFetcherWithSubscriptions = window.GraphiQLSubscriptionsFetcher.graphQLFetcher(
    subscriptionsClient,
    graphQLFetcher
);
ReactDOM.render(
    React.createElement(GraphiQLWithExtensions.GraphiQLWithExtensions, {
      fetcher: graphQLFetcherWithSubscriptions,
    }),
    document.getElementById('graphiql'),
);
```

--------------------------------

### POST /products

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Creates a new product within a project.

```APIDOC
## POST /products

### Description
Create a new product.

### Method
POST

### Endpoint
/api/projects/{project_name}/products

#### Request Body
- **name** (string) - Required - Name of the new product
- **type** (string) - Required - Type of the product
- **folderId** (string) - Required - The ID of the folder to associate the product with

### Request Example
{
  "name": "newproduct",
  "type": "render",
  "folderId": "folder_id_32chars"
}

### Response
#### Success Response (201 Created)
- **id** (string) - The ID of the newly created product
- **name** (string) - The name of the newly created product

#### Response Example
{
  "id": "new_product_id",
  "name": "newproduct"
}
```

--------------------------------

### ColorRGBA_hex Type

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/types.md

Represents a color in RGBA hex format. Example: #ff0000ff.

```python
class ColorRGBA_hex(str):
    """Color in RGBA hex format. Example: #ff0000ff"""
```

--------------------------------

### ColorRGB_hex Type

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/types.md

Represents a color in RGB hex format. Example: #ff0000.

```python
class ColorRGB_hex(str):
    """Color in RGB hex format. Example: #ff0000"""
```

--------------------------------

### GET /users/{user_name}/avatar

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves the avatar image for a specific user.

```APIDOC
## GET /users/{user_name}/avatar

### Description
Get user avatar image.

### Method
GET

### Endpoint
/api/users/{user_name}/avatar

### Response
#### Success Response (200 OK)
Image file of the user's avatar.

### Status Codes
- `200`: Avatar found
- `404`: No avatar
```

--------------------------------

### List Products in a Project

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve a list of all products within a specified project.

```http
GET /api/projects/{project_name}/products
```

--------------------------------

### Format and Check Backend Code

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/README.md

Format the ayon_server directory using ruff format and then check for linting issues with ruff check.

```bash
ruff format ayon_server/
ruff check ayon_server/
```

--------------------------------

### GET /workfiles/{workfile_id}

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves the details of a specific workfile using its ID.

```APIDOC
## GET /workfiles/{workfile_id}

### Description
Get workfile details.

### Method
GET

### Endpoint
/workfiles/{workfile_id}

### Response
#### Success Response (200 OK)
Details of the workfile.
```

--------------------------------

### POST /versions

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Creates a new version for a product.

```APIDOC
## POST /versions

### Description
Create a new version.

### Method
POST

### Endpoint
/api/projects/{project_name}/versions

#### Request Body
- **productId** (string) - Required - The ID of the product to associate the version with
- **version** (integer) - Required - The version number
- **status** (string) - Optional - The initial status of the version

### Request Example
{
  "productId": "product_id",
  "version": 2,
  "status": "Work in Progress"
}

### Response
#### Success Response (201 Created)
```

--------------------------------

### Get Access Group Schema

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieve the schema definition for access groups.

```json
{
  "schema": { /* schema definition */ }
}
```

--------------------------------

### Get User Details

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieve detailed information for a specific user by their username.

```json
{
  "name": "admin",
  "fullName": "Administrator",
  "email": "admin@example.com",
  "active": true,
  "isManager": true,
  "avatarUrl": "https://example.com/avatar.jpg",
  "accessGroups": { /* access groups */ }
}
```

--------------------------------

### GET /folders/{folder_id}

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves the details of a specific folder using its ID.

```APIDOC
## GET /folders/{folder_id}

### Description
Get folder details.

### Method
GET

### Endpoint
/folders/{folder_id}

#### Path Parameters
- **folder_id** (string) - Required - Folder ID (32-char hex)

### Response
#### Success Response (200 OK)
- **id** (string) - Folder ID
- **name** (string) - Folder name
- **label** (string) - Folder label
- **folderType** (string) - Type of the folder
- **parentId** (string) - ID of the parent folder (null if root)
- **status** (string) - Current status of the folder
- **active** (boolean) - Whether the folder is active
- **attribs** (object) - Custom attributes

#### Response Example
{
  "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p",
  "name": "shots",
  "label": "Shots",
  "folderType": "Folder",
  "parentId": null,
  "status": "In Progress",
  "active": true,
  "attribs": { /* custom attributes */ }
}
```

--------------------------------

### Create New Version

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Creates a new version for a product. Requires product ID, version number, and status.

```json
{
  "productId": "product_id",
  "version": 2,
  "status": "Work in Progress"
}
```

--------------------------------

### Get Activities

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieves activities (comments) for a specific entity type and ID.

```APIDOC
## GET /api/activities/{entity_type}/{entity_id}

### Description
Retrieves activities (comments) for a specific entity.

### Method
GET

### Endpoint
/api/activities/{entity_type}/{entity_id}

### Parameters
#### Path Parameters
- **entity_type** (string) - Required - The type of the entity.
- **entity_id** (string) - Required - The ID of the entity.
```

--------------------------------

### GET /tokenauth

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Callback handler for token authentication flow. Does not require authentication.

```APIDOC
## GET /tokenauth

### Description
Callback handler for token authentication flow.

### Method
GET

### Endpoint
/api/auth/tokenauth

### Query Parameters
- **q** (string) - Required - Token for authentication callback

### Response
#### Success Response (200 OK)
- **detail** (string) - Message indicating successful token authentication.
- **token** (string) - New access token.
- **user** (object) - User object.

#### Response Example
```json
{
  "detail": "Token authenticated",
  "token": "new-access-token",
  "user": { /* user object */ }
}
```

### Status Codes
- `200`: Token valid
- `400`: Missing token parameter
- `401`: Invalid token

### Auth
Not required (AllowGuests)
```

--------------------------------

### Load Project and Folder Entities

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/README.md

Shows how to load Project and Folder entities using their respective class methods. These entities represent data within the Ayon system.

```python
from ayon_server.entities import ProjectEntity, FolderEntity

project = await ProjectEntity.load("myproject")
folder = await FolderEntity.load("folder_id", "myproject")
```

--------------------------------

### Create Version

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Creates a new version for a product.

```APIDOC
## POST /api/projects/{project_name}/versions

### Description
Creates a new version for a product.

### Method
POST

### Endpoint
/api/projects/{project_name}/versions

### Parameters
#### Path Parameters
- **project_name** (string) - Required - The name of the project.

#### Request Body
- **productId** (string) - Required - The ID of the product this version belongs to.
- **version** (integer) - Required - The version number.
- **status** (string) - Optional - The status of the version (e.g., 'Published').
```

--------------------------------

### Receive WebSocket Messages

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Example of a message received over the WebSocket, indicating a project update.

```json
{
  "topic": "project_updated",
  "data": { /* entity data */ }
}
```

--------------------------------

### Query Folders Using SQL

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/api-reference/entity-classes.md

Illustrates how to directly query the database for folder information using a raw SQL statement via the Postgres helper. This method is useful for complex queries not directly supported by entity methods.

```python
from ayon_server.lib.postgres import Postgres

# Query using SQL directly
query = """
SELECT id, name, label FROM project_myproject.folders
WHERE parent_id IS NULL
ORDER BY name
"""
rows = await Postgres.fetch(query)

for row in rows:
    print(f"{row['name']}: {row['label']}")
```

--------------------------------

### GET /events/{event_id}

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieve detailed information about a specific event using its ID.

```APIDOC
## GET /events/{event_id}

### Description
Get event details.

### Method
GET

### Endpoint
/api/events/{event_id}

### Response
#### Success Response (200 OK)
```

--------------------------------

### List All Versions

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Retrieves a list of all versions for products within a project. Can be filtered by product ID or status.

```json
{
  "versions": [
    {
      "id": "version_id_32chars",
      "version": 1,
      "productId": "product_id_32chars",
      "status": "Published",
      "createdAt": "2024-06-01T10:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /users/{user_name}/apikeys

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/endpoints.md

Lists all API keys associated with a specific user.

```APIDOC
## GET /users/{user_name}/apikeys

### Description
List API keys for user.

### Method
GET

### Endpoint
/api/users/{user_name}/apikeys

### Response
#### Success Response (200 OK)
- **apiKeys** (array)
  - **id** (string)
  - **name** (string)
  - **createdAt** (string)

### Response Example
```json
{
  "apiKeys": [
    {
      "id": "key_id",
      "name": "Production API",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Get OpenAPI Schema

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve the OpenAPI specification for the Ayon API. Requires authentication.

```http
GET /api/openapi.json
Authorization: Bearer {token}
```

--------------------------------

### Get Activities for Entity

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve all activities associated with a specific entity type and ID.

```http
GET /api/activities/{entity_type}/{entity_id}
```

--------------------------------

### Get Specific Folder

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Retrieve details for a specific folder within a project by its ID.

```http
GET /api/projects/{project_name}/folders/{folder_id}
```

--------------------------------

### Create Folder

Source: https://github.com/ynput/ayon-backend/blob/develop/_autodocs/QUICK-START.md

Create a new folder within a project. Specify name, label, type, and status.

```http
POST /api/projects/{project_name}/folders
{
  "name": "shots",
  "label": "Shots",
  "folderType": "Folder",
  "status": "Active"
}
```
Tokens:
Raw