{ "variable": [ { "id": "baseUrl", "key": "baseUrl", "type": "string", "name": "string", "value": "https:\/\/stage.1kosmosfactory.com" } ], "info": { "name": "1Kosmos Factory TV API Documentation", "_postman_id": "005cee1d-db20-4f3e-b1ba-161c170eb326", "description": "API for TV applications (Apple TV, Android TV) to display artworks.", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "TV Artists", "description": "\nAPIs for TV applications to display artist profiles.\nAll endpoints require the `X-API-Key` header and a valid TV access token\nobtained from the TV pairing flow (`Authorization: Bearer `).", "item": [ { "name": "List Artists", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artists", "query": [ { "key": "page", "value": "1", "description": "Page number for pagination. Default: 1.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Number of items per page. Min: 1, Max: 50. Default: 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/tv\/artists?page=1&per_page=20" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get a paginated list of artists for TV display. Returns basic profile info\nsuitable for artist listing screens." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 5,\n \"name\": \"John Doe\",\n \"profile_image\": \"https:\/\/example.com\/artists\/5\/photo.jpg\",\n \"specialty\": \"Oil Painting\",\n \"permanent_location\": \"Rajkot, Gujarat, India\"\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 3,\n \"per_page\": 20,\n \"total\": 55\n }\n}", "name": "Success" } ] }, { "name": "Get Artist", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artists\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/artists\/:id", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "The artist user ID." } ] }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get a single artist by ID for TV display. Includes full profile details,\nbio, permanent location, social links, and career sections (education,\nexhibitions, galleries, residencies, institutions)." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 5,\n \"name\": \"John Doe\",\n \"profile_image\": \"https:\/\/example.com\/artists\/5\/photo.jpg\",\n \"bio\": \"Contemporary artist based in Rajkot.\",\n \"specialty\": \"Oil Painting\",\n \"years_of_experience\": 10,\n \"permanent_location\": \"Rajkot, Gujarat, India\",\n \"social_links\": {\n \"instagram\": \"https:\/\/instagram.com\/johndoe\",\n \"facebook\": null,\n \"website\": \"https:\/\/johndoe.art\",\n \"twitter\": null\n },\n \"education\": [\n { \"name\": \"Fine Arts Academy\", \"date\": \"2010\", \"location\": \"Mumbai, India\" }\n ],\n \"exhibitions\": [\n { \"name\": \"Modern Art Expo\", \"date\": \"2022\", \"location\": \"Delhi, India\" }\n ],\n \"galleries\": [\n { \"name\": \"City Gallery\", \"date\": \"2021\", \"location\": \"Ahmedabad, India\" }\n ],\n \"residencies\": [\n { \"name\": \"Artist Residency Program\", \"date\": \"2019\", \"location\": \"Jaipur, India\" }\n ],\n \"institutions\": [\n { \"name\": \"National Institute of Art\", \"date\": \"2018\", \"location\": \"Baroda, India\" }\n ]\n }\n}", "name": "Success" }, { "header": [], "code": 404, "body": "{\n \"message\": \"No query results for model [App\\\\Models\\\\User] 999\"\n}", "name": "Not Found" } ] }, { "name": "Subscribe to an artist", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artists\/:id\/subscribe", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/artists\/:id\/subscribe", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "The artist user ID." } ] }, "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Subscribe the authenticated TV user to an artist. Allows the user to filter\nartworks by subscribed artists." }, "response": [ { "header": [], "code": 201, "body": "{\n \"message\": \"Subscribed successfully\",\n \"artist_id\": 5,\n \"is_subscribed\": true\n}", "name": "Success" }, { "header": [], "code": 422, "body": "{\n \"message\": \"Already subscribed to this artist\"\n}", "name": "Already Subscribed" } ] }, { "name": "Unsubscribe from an artist", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artists\/:id\/subscribe", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/artists\/:id\/subscribe", "variable": [ { "id": "id", "key": "id", "value": "5", "description": "The artist user ID." } ] }, "method": "DELETE", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Unsubscribe the authenticated TV user from an artist." }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"Unsubscribed successfully\",\n \"artist_id\": 5,\n \"is_subscribed\": false\n}", "name": "Success" }, { "header": [], "code": 422, "body": "{\n \"message\": \"Not subscribed to this artist\"\n}", "name": "Not Subscribed" } ] }, { "name": "Get user's subscribed artists", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/me\/artist-subscriptions", "query": [ { "key": "page", "value": "1", "description": "Page number for pagination. Default: 1.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Number of items per page. Min: 1, Max: 50. Default: 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/tv\/me\/artist-subscriptions?page=1&per_page=20" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get a paginated list of artists the authenticated TV user is subscribed to." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 5,\n \"name\": \"John Doe\",\n \"profile_image\": \"https:\/\/example.com\/artists\/5\/photo.jpg\",\n \"specialty\": \"Oil Painting\",\n \"permanent_location\": \"Rajkot, Gujarat, India\",\n \"is_subscribed\": true\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 20,\n \"total\": 3\n }\n}", "name": "Success" } ] }, { "name": "Get user's category preferences", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/me\/category-preferences", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/me\/category-preferences" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get the authenticated TV user's selected category preferences. Returns the list\nof categories the user has selected for filtering artworks." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"categories\": [\n {\n \"id\": 1,\n \"name\": \"Painting\",\n \"slug\": \"painting\",\n \"description\": \"Oil and acrylic paintings\"\n },\n {\n \"id\": 2,\n \"name\": \"Photography\",\n \"slug\": \"photography\",\n \"description\": \"Digital and film photography\"\n }\n ],\n \"category_ids\": [1, 2]\n }\n}", "name": "Success" } ] }, { "name": "Update user's category preferences", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/me\/category-preferences", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/me\/category-preferences" }, "method": "PUT", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"category_ids\":[1,2,3]}" }, "description": "Update the authenticated TV user's category preferences. The user can select\nwhich categories they want to see artworks from. At least one category must be selected." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"categories\": [\n {\n \"id\": 1,\n \"name\": \"Painting\",\n \"slug\": \"painting\",\n \"description\": \"Oil and acrylic paintings\"\n }\n ],\n \"category_ids\": [1]\n },\n \"message\": \"Preferences updated successfully\"\n}", "name": "Success" }, { "header": [], "code": 422, "body": "{\n \"message\": \"The given data was invalid.\",\n \"errors\": {\n \"category_ids\": [\"The category_ids field is required.\"]\n }\n}", "name": "Validation Error" } ] } ] }, { "name": "TV Artworks", "description": "\nAPIs for TV applications to display artworks with QR codes.\nAll endpoints require the `X-API-Key` header and a valid TV access token\nobtained from the TV pairing flow (`Authorization: Bearer `).", "item": [ { "name": "List Artworks", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artworks", "query": [ { "key": "page", "value": "1", "description": "Page number for pagination. Default: 1.", "disabled": false }, { "key": "per_page", "value": "20", "description": "Number of items per page. Min: 1, Max: 50. Default: 20.", "disabled": false }, { "key": "category_id", "value": "1", "description": "Filter by category ID.", "disabled": false }, { "key": "featured", "value": "1", "description": "Show only featured artworks.", "disabled": false }, { "key": "sort", "value": "new", "description": "Sort order: new, popular, price_asc, price_desc. Default: new.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/tv\/artworks?page=1&per_page=20&category_id=1&featured=1&sort=new" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get a paginated list of artworks for TV display. Each artwork includes images and a QR code\nthat links to the artwork detail page in the mobile\/web application." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 1,\n \"title\": \"Sunset Canvas\",\n \"description\": \"A beautiful sunset painting\",\n \"artist_name\": \"John Doe\",\n \"images\": [\n {\n \"image_url\": \"https:\/\/example.com\/artworks\/1\/image.jpg\"\n }\n ],\n \"qr_code\": {\n \"url\": \"https:\/\/stage.1kosmosfactory.com\/web\/artist\/artwork-detail?id=1\",\n \"base64\": \"data:image\/svg+xml;base64,PHN2ZyB...\"\n }\n }\n ],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 5,\n \"per_page\": 20,\n \"total\": 100\n }\n}", "name": "Success" } ] }, { "name": "Get Artwork", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/artworks\/:id", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/artworks\/:id", "variable": [ { "id": "id", "key": "id", "value": "1", "description": "The artwork ID." } ] }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Get a single artwork by ID for TV display. Includes full details, images, artist info,\ncategory, and a QR code that links to the artwork detail page." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"id\": 1,\n \"title\": \"Sunset Canvas\",\n \"description\": \"A beautiful sunset painting with vibrant colors\",\n \"artist_name\": \"John Doe\",\n \"views_count\": 15,\n \"images\": [\n {\n \"id\": 456,\n \"image_url\": \"https:\/\/example.com\/artworks\/1\/image.jpg\"\n }\n ],\n \"artist\": {\n \"id\": 5,\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"full_name\": \"John Doe\",\n \"profile_image\": \"https:\/\/example.com\/artist.jpg\",\n \"bio\": \"Contemporary artist specializing in abstract paintings\"\n },\n \"category\": {\n \"id\": 3,\n \"name\": \"Painting\",\n \"slug\": \"painting\",\n \"description\": \"Oil and acrylic paintings\"\n },\n \"owner\": {\n \"id\": 6,\n \"first_name\": \"Jane\",\n \"last_name\": \"Smith\",\n \"full_name\": \"Jane Smith\",\n \"profile_image\": \"https:\/\/example.com\/collector.jpg\"\n },\n \"qr_code\": {\n \"url\": \"https:\/\/stage.1kosmosfactory.com\/web\/artist\/artwork-detail?id=1\",\n \"base64\": \"data:image\/png;base64,iVBORw0KGgo...\"\n }\n }\n}", "name": "Success" }, { "header": [], "code": 404, "body": "{\n \"message\": \"No query results for model [App\\\\Models\\\\Artwork] 999\"\n}", "name": "Not Found" } ] } ] }, { "name": "TV Authentication", "description": "\nEndpoints for pairing a TV device with a mobile user account.\nQR and poll endpoints require only the `X-API-Key` header. The pair endpoint\nrequires an authenticated user bearer token from the mobile\/Flutter app.", "item": [ { "name": "Pair TV From Mobile App", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/pair", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/pair" }, "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {mobile_user_bearer_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"session_code\":\"ABCDEF12\"}" }, "description": "Called by the authenticated mobile\/Flutter app after scanning the TV QR code.\nLinks the pairing session to the authenticated user.\n\nNote: This endpoint requires the mobile user's bearer token (regular Sanctum auth),\nNOT the TV access token, and does NOT require an X-API-Key.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"TV paired successfully.\",\n \"session_code\": \"ABCDEF12\"\n}", "name": "Success" }, { "header": [], "code": 404, "body": "{\n \"message\": \"Invalid or expired session code.\"\n}", "name": "Invalid or Expired" } ] }, { "name": "Generate QR Session", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/auth\/qr", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/auth\/qr" }, "method": "GET", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Creates a new TV pairing session and returns a QR code URL.\nThe TV application should display the QR code and begin polling\n`POST \/api\/v1\/tv\/auth\/poll` until the user scans and pairs.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"session_code\": \"ABCDEF12\",\n \"qr_url\": \"onekosmosfactory:\/\/tv-pair?code=ABCDEF12\",\n \"expires_at\": \"2026-06-26T21:00:00+00:00\"\n}", "name": "Success" } ] }, { "name": "Poll Pairing Status", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/auth\/poll", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/auth\/poll" }, "method": "POST", "header": [ { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"session_code\":\"ABCDEF12\"}" }, "description": "Polls the status of a TV pairing session. Returns 202 while waiting,\n200 once paired with the TV access token, 404 if the session is not found,\nand 410 if the session expired.", "auth": { "type": "noauth" } }, "response": [ { "header": [], "code": 200, "body": "{\n \"access_token\": \"1|tv_access_token...\",\n \"user\": {\n \"id\": 5,\n \"full_name\": \"John Doe\",\n \"email\": \"john@example.com\"\n },\n \"subscription\": {\n \"has_tv_access\": true,\n \"plan_name\": \"Basic\",\n \"billing_interval\": \"yearly\",\n \"ends_at\": \"2027-06-26T21:00:00+00:00\",\n \"artwork_limit\": 25\n }\n}", "name": "Paired" }, { "header": [], "code": 202, "body": "{\n \"message\": \"Waiting for pairing.\"\n}", "name": "Waiting" }, { "header": [], "code": 404, "body": "{\n \"message\": \"Session not found.\"\n}", "name": "Not Found" }, { "header": [], "code": 410, "body": "{\n \"message\": \"Session expired.\"\n}", "name": "Expired" } ] } ] }, { "name": "TV Me", "description": "\nEndpoints for the authenticated TV device to retrieve information about the\ncurrently paired user. Requires a valid TV access token returned by the pairing flow.", "item": [ { "name": "Get TV Subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/me\/subscription", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/me\/subscription" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns the paired user's subscription status for TV access checks.\nDoes not require an active TV subscription plan, but the paired session must be valid." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"has_tv_access\": true,\n \"plan_name\": \"Basic\",\n \"billing_interval\": \"yearly\",\n \"ends_at\": \"2027-06-26T21:00:00+00:00\",\n \"artwork_limit\": 25\n }\n}", "name": "Success" }, { "header": [], "code": 401, "body": "{\n \"message\": \"Unauthenticated.\"\n}", "name": "Unauthenticated" } ] } ] }, { "name": "TV Subscriptions", "description": "\nEndpoints for the authenticated TV device to browse membership plans and\nsubscribe via native in-app purchase platforms. All endpoints require a valid\nTV access token returned by the pairing flow.", "item": [ { "name": "List available subscription plans", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/plans", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/plans" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns active plans with web prices and platform-specific product IDs\n(Apple\/Google\/Amazon) that the TV app must use when calling the native\nin-app purchase SDK." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [\n {\n \"id\": 1,\n \"slug\": \"basic\",\n \"name\": \"Basic\",\n \"monthly_price\": {\"currency\": \"USD\", \"price\": \"9.99\"},\n \"yearly_price\": {\"currency\": \"USD\", \"price\": \"99.99\"},\n \"all_prices\": {\"USD\": {\"monthly\": \"9.99\", \"yearly\": \"99.99\"}},\n \"platform_products\": [\n {\"id\": 1, \"platform\": \"apple\", \"billing_interval\": \"monthly\", \"product_id\": \"com.1kosmosfactory.basic.monthly\", \"is_active\": true}\n ],\n \"is_current\": false\n }\n ],\n \"currency\": \"USD\"\n}", "name": "Success" } ] }, { "name": "Verify an Apple In-App Purchase subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/subscriptions\/verify-apple", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/subscriptions\/verify-apple" }, "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": { "mode": "raw", "raw": "{\"signedTransactionInfo\":\"eyJhbGciOiJFUzI1NiIs...\"}" }, "description": "The TV app sends the signed transaction info (JWS) after a successful StoreKit 2 purchase.\nThe backend decodes and verifies the JWS, looks up the matching plan from the configured\nplatform products, and activates the subscription." }, "response": [ { "header": [], "code": 200, "body": "{\n \"message\": \"Subscription verified and activated.\",\n \"data\": {\n \"has_tv_access\": true,\n \"plan_name\": \"Basic\",\n \"billing_interval\": \"monthly\",\n \"ends_at\": \"2026-08-15T12:00:00+00:00\",\n \"artwork_limit\": 0\n }\n}", "name": "Success" } ] }, { "name": "Get the current TV subscription", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/subscriptions\/current", "query": [], "raw": "{{baseUrl}}\/api\/v1\/tv\/subscriptions\/current" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "" }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": {\n \"has_tv_access\": true,\n \"plan_name\": \"Basic\",\n \"billing_interval\": \"monthly\",\n \"ends_at\": \"2026-08-15T12:00:00+00:00\",\n \"artwork_limit\": 0\n }\n}", "name": "Success" } ] }, { "name": "List TV subscription history", "request": { "url": { "host": "{{baseUrl}}", "path": "api\/v1\/tv\/subscriptions\/history", "query": [ { "key": "per_page", "value": "20", "description": "optional Number of records per page (1-50). Default: 20.", "disabled": false } ], "raw": "{{baseUrl}}\/api\/v1\/tv\/subscriptions\/history?per_page=20" }, "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {tv_access_token}" }, { "key": "Content-Type", "value": "application\/json" }, { "key": "Accept", "value": "application\/json" } ], "body": null, "description": "Returns paginated subscription history for the authenticated TV user." }, "response": [ { "header": [], "code": 200, "body": "{\n \"data\": [...],\n \"meta\": {\n \"current_page\": 1,\n \"last_page\": 1,\n \"per_page\": 20,\n \"total\": 1\n }\n}", "name": "Success" } ] } ] } ], "auth": { "type": "apikey", "apikey": [ { "key": "in", "value": "header", "type": "string" }, { "key": "key", "value": "X-API-Key", "type": "string" } ] } }