Get Presets

This section covers endpoints for retrieving both individual presets and lists of presets.

🔹 Get Single Preset

Retrieve detailed information about a specific preset by its ID.

Endpoint Details

GET /api/v1/presets/{presetId}

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

Path Parameters

Parameter	Required	Description
presetId	Yes	Unique identifier of the preset to retrieve

🧩 Request Example

curl -X GET "https://openapi.onlive.site/api/v1/presets/123e4567-e89b-12d3-a456-426614174001" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

Field	Type	Description
id	string	Unique identifier for the preset
organizationId	string	Organization ID that owns this preset
title	string	The title of the preset
description	string	A detailed description of the preset
logo	string	URL to the preset logo
image	string	URL to the preset cover image
assets	array of strings	IDs of multimedia assets associated with this preset
products	array of strings	Product identifiers associated with this preset
effectId	string	ID of the effect applied to this preset
createdAt	string (ISO 8601)	Creation timestamp
updatedAt	string (ISO 8601)	Last update timestamp

Response Example

{
  "id": "123e4567-e89b-12d3-a456-426614174001",
  "organizationId": "123e4567-e89b-12d3-a456-426614174002",
  "title": "My Custom Preset",
  "description": "This preset contains settings for video streaming",
  "logo": "https://example.com/logo.png",
  "image": "https://example.com/cover.png",
  "assets": [
    "123e4567-e89b-12d3-a456-426614174003",
    "123e4567-e89b-12d3-a456-426614174004"
  ],
  "products": [
    "product1",
    "product2"
  ],
  "effectId": "effect123",
  "createdAt": "2025-05-28T10:15:30Z",
  "updatedAt": "2025-05-28T10:15:30Z"
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid preset ID format"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to access this preset"
}

404 Not Found

{
  "statusCode": 404,
  "message": "Preset not found",
  "error": "Not Found"
}

🔹 List Presets

Retrieve a paginated list of presets with optional filtering.

Endpoint Details

GET /api/v1/presets

🔒 Authentication

Header	Required	Description
Content-Type	Yes	Must be application/json
Authorization	Yes	Format: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

Query Parameters

Parameter	Type	Required	Description	Default
title	string	No	Filter presets by exact title match	-
search	string	No	Search presets by title or description	-
page	number	No	Page number for pagination	1
limit	number	No	Number of items per page	10

🧩 Request Example

curl -X GET "https://openapi.onlive.site/api/v1/presets?page=1&limit=10&search=streaming" \
-H "Content-Type: application/json" \
-H "Authorization: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature"

📥 Response Format (HTTP 200)

Field	Type	Description
items	array	Array of preset objects
meta	object	Pagination metadata
meta.totalItems	number	Total number of items matching the query
meta.itemCount	number	Number of items in the current page
meta.itemsPerPage	number	Number of items per page
meta.totalPages	number	Total number of pages
meta.currentPage	number	Current page number

Response Example

{
  "items": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "organizationId": "123e4567-e89b-12d3-a456-426614174002",
      "title": "My Custom Preset",
      "description": "This preset contains settings for video streaming",
      "logo": "https://example.com/logo.png",
      "image": "https://example.com/cover.png",
      "assets": [
        "123e4567-e89b-12d3-a456-426614174003",
        "123e4567-e89b-12d3-a456-426614174004"
      ],
      "products": ["product1", "product2"],
      "effectId": "effect123",
      "createdAt": "2025-05-28T10:15:30Z",
      "updatedAt": "2025-05-28T10:15:30Z"
    },
    {
      "id": "123e4567-e89b-12d3-a456-426614174005",
      "organizationId": "123e4567-e89b-12d3-a456-426614174002",
      "title": "Advanced Streaming Preset",
      "description": "Preset with advanced streaming capabilities",
      "logo": "https://example.com/advanced-logo.png",
      "image": "https://example.com/advanced-cover.png",
      "assets": [
        "123e4567-e89b-12d3-a456-426614174006"
      ],
      "products": ["product3"],
      "effectId": "effect456",
      "createdAt": "2025-05-27T14:22:10Z",
      "updatedAt": "2025-05-27T14:22:10Z"
    }
  ],
  "meta": {
    "totalItems": 24,
    "itemCount": 2,
    "itemsPerPage": 10,
    "totalPages": 3,
    "currentPage": 1
  }
}

❌ Error Responses

400 Bad Request

{
  "statusCode": 400,
  "message": "Invalid pagination parameters",
  "errors": [
    {
      "field": "limit",
      "message": "limit cannot exceed 100"
    }
  ]
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Unauthorized access",
  "error": "Unauthorized"
}

403 Forbidden

{
  "statusCode": 403,
  "message": "Insufficient permissions to list presets"
}

✅ Common Use Cases

• 🔍 Preset Discovery: Find presets matching specific criteria
• 📊 Resource Inventory: List all available presets for an organization
• 🧩 Integration Planning: Identify presets for integration with other systems
• 📱 Client Applications: Populate dropdown menus or selection interfaces
• 🔄 Sync Operations: Keep local caches in sync with server-side presets

💡 Best Practices

1. Performance Optimization

   • Use pagination for large collections
   • Apply specific filters to reduce result sets

2. Resource Management

   • Retrieve only the presets you need

3. Search Implementation

   • Use the search parameter for broad matches
   • Use the title parameter for exact matches
   • Combine parameters for more targeted results

📘 Notes

• Results are paginated with a default limit of 10 items per page
• Search is case-insensitive and looks for partial matches in both title and description
• Sorting is by creation date in descending order (newest first)
• Query parameters can be combined for more specific filtering
• Only presets belonging to your organization will be returned