MENU navbar-image

Introduction

API for TV applications (Apple TV, Android TV) to display artworks.

Welcome to the 1Kosmos Factory TV API documentation.

This API is designed for TV applications to display artworks with QR codes for mobile scanning.

## Authentication
All requests require an `X-API-Key` header. Contact the administrator to get your API key.

## Rate Limiting
Default rate limit is 1000 requests per hour per API key.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).</aside>

Authenticating requests

To authenticate requests, include a X-API-Key header with the value "{YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

Contact the administrator to get your API key for TV applications.

TV Artworks

APIs for TV applications to display artworks with QR codes.

List Artworks

requires authentication

Get a paginated list of artworks for TV display. Each artwork includes images and a QR code that links to the artwork detail page in the mobile/web application.

Example request:
curl --request GET \
    --get "https://stage.1kosmosfactory.com/api/v1/tv/artworks?per_page=20&category_id=1&featured=1&sort=new" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://stage.1kosmosfactory.com/api/v1/tv/artworks"
);

const params = {
    "per_page": "20",
    "category_id": "1",
    "featured": "1",
    "sort": "new",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "X-API-Key": "{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, Success):


{
    "data": [
        {
            "id": 1,
            "title": "Sunset Canvas",
            "description": "A beautiful sunset painting",
            "artist_name": "John Doe",
            "images": [
                {
                    "thumbnail": "https://example.com/thumb.jpg",
                    "medium": "https://example.com/medium.jpg",
                    "large": "https://example.com/large.jpg",
                    "original": "https://example.com/original.jpg"
                }
            ],
            "category": "Paintings",
            "price": {
                "amount": 1500,
                "currency": "USD",
                "formatted": "$1,500.00"
            },
            "dimensions": {
                "width": 24,
                "height": 36,
                "depth": 2,
                "unit": "inches"
            },
            "qr_code": {
                "url": "https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1",
                "base64": "data:image/png;base64,iVBORw0KGgo..."
            }
        }
    ],
    "meta": {
        "current_page": 1,
        "last_page": 5,
        "per_page": 20,
        "total": 100
    }
}

Request      

GET api/v1/tv/artworks

Headers

X-API-Key        

Example: {YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

Query Parameters

per_page   integer  optional    

Number of items per page. Min: 1, Max: 50. Example: 20

category_id   integer  optional    

Filter by category ID. Example: 1

featured   boolean  optional    

Show only featured artworks. Example: true

sort   string  optional    

Sort order: new, popular, price_asc, price_desc. Example: new

Get Artwork

requires authentication

Get a single artwork by ID for TV display. Includes full details, images, artist info, and a QR code that links to the artwork detail page.

Example request:
curl --request GET \
    --get "https://stage.1kosmosfactory.com/api/v1/tv/artworks/1" \
    --header "X-API-Key: {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
const url = new URL(
    "https://stage.1kosmosfactory.com/api/v1/tv/artworks/1"
);

const headers = {
    "X-API-Key": "{YOUR_API_KEY}",
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200, Success):


{
    "data": {
        "id": 1,
        "title": "Sunset Canvas",
        "description": "A beautiful sunset painting with vibrant colors",
        "artist_name": "John Doe",
        "artist": {
            "id": 5,
            "name": "John Doe",
            "bio": "Contemporary artist based in New York",
            "profile_image": "https://example.com/artist.jpg"
        },
        "images": [
            {
                "thumbnail": "https://example.com/thumb.jpg",
                "medium": "https://example.com/medium.jpg",
                "large": "https://example.com/large.jpg",
                "original": "https://example.com/original.jpg"
            }
        ],
        "category": "Paintings",
        "price": {
            "amount": 1500,
            "currency": "USD",
            "formatted": "$1,500.00"
        },
        "dimensions": {
            "width": 24,
            "height": 36,
            "depth": 2,
            "unit": "inches"
        },
        "qr_code": {
            "url": "https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1",
            "base64": "data:image/png;base64,iVBORw0KGgo..."
        }
    }
}

Example response (404, Not Found):


{
    "message": "No query results for model [App\\Models\\Artwork] 999"
}

Request      

GET api/v1/tv/artworks/{id}

Headers

X-API-Key        

Example: {YOUR_API_KEY}

Content-Type        

Example: application/json

Accept        

Example: application/json

URL Parameters

id   integer     

The artwork ID. Example: 1