{
  "openapi": "3.1.0",
  "info": {
    "title": "Luna Screens API",
    "version": "v1",
    "description": "> **Note:** This API is in beta and contracts may change.\n\nThe Luna Screens API lets you manage your digital signage programmatically.\nCreate and remove screens, upload the adverts (images, videos and\nwebpages) that play on them, and manage who can access what with\npermission groups.\n\nThe API is organised around REST. Requests and responses are JSON, and\nstandard HTTP status codes indicate success or failure.\n\nExpect more features and endpoints coming soon.\n\nThe full OpenAPI definition is available at\n[`/api/openapi.json`](/api/openapi.json) and\n[`/api/openapi.yaml`](/api/openapi.yaml). AI agents can start from\n[`/api/llms.txt`](/api/llms.txt).\n\n## Authentication\n\nAuthenticate requests by sending an API key as a bearer token in the\n`Authorization` header.\n\n```\nAuthorization: Bearer lsk_YOUR_API_KEY\n```\n\nTo create an API key, sign in to the\n[Luna Screens dashboard](https://app.lunascreens.com) and go to\n**Account → API keys**. Give the key a name and choose a permission group;\nthe key can do whatever that permission group allows in your account.\n\nThe key is only shown once, when it's created, so copy it somewhere safe.\nIf you lose it, create a new key and revoke the old one.\n\nYou can change a key's permission group, disable it or revoke it from the\nsame page at any time. Changes take effect on the key's next request. A\ndisabled key stops working until it's enabled again, while revoking a key\ndeletes it permanently. To rotate a key, create a new one, switch your\nintegration over to it, then disable the old one. Once you're sure nothing\nstill uses it, revoke it.\n\nKeep your API keys secret. Don't put them in client-side code or commit\nthem to source control.\n\n## Errors\n\nErrors return a non-2xx status code and a JSON body with a human-readable\n`message`.\n\n```json\n{ \"message\": \"name is required.\" }\n```\n\n| Status | Meaning |\n| :--- | :--- |\n| `200` | Success. |\n| `400` | The request was invalid, for example a required field is missing, the body isn't valid JSON, or the `Authorization` header is missing. |\n| `403` | The API key is invalid, disabled or revoked, or the key's permission group doesn't allow this action. |\n| `404` | The resource doesn't exist in your account. A resource in another account returns `404` too, as if it doesn't exist. |\n| `500` | Something went wrong on our side. |\n"
  },
  "servers": [
    {
      "url": "https://api.lunascreens.com/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Screens",
      "description": "A screen represents a display in your account, such as a TV in a\nreception area. Content is scheduled onto screens, and a physical device\nis paired to a screen to play it.\n"
    },
    {
      "name": "Adverts",
      "description": "An advert is a piece of content in your library: an image, a video or a\nwebpage. Adverts are scheduled onto screens to be displayed.\n\nMedia must be hosted at a publicly accessible HTTPS URL. Pass the URL as\n`content` along with its MIME `type` and pixel dimensions.\n"
    },
    {
      "name": "Permission groups",
      "description": "A permission group controls what its members can see and change in\nyour account. Every user and API key belongs to one permission group.\n\nEach group sets a level for every feature: `noAccess`, `canView` or\n`canModify`. Screens and content can also be `granular`, to give access\nto only some screens or only the group's own adverts.\n\nEvery account has an Owner group with full access. Only the account\nowner is in it, and it can't be changed with the API.\n"
    }
  ],
  "paths": {
    "/screens": {
      "post": {
        "tags": [
          "Screens"
        ],
        "operationId": "createScreen",
        "summary": "Create a screen",
        "description": "Creates a new screen in your account.\n\nA new screen isn't connected to a device yet. Pair a device to it with\n`POST /screens/{id}/pair` or from the dashboard so it can start playing content.\n\nRequires permission to modify screens.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "timeZone"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name of the screen.",
                    "example": "Reception TV"
                  },
                  "description": {
                    "type": "string",
                    "description": "Optional description of the screen.",
                    "example": "Wall-mounted TV by the front desk"
                  },
                  "timeZone": {
                    "type": "string",
                    "description": "IANA time zone the screen's schedule runs in, for example `Europe/London` or `America/New_York`.",
                    "example": "Europe/London"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created screen.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "screen": {
                      "$ref": "#/components/schemas/Screen"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X POST https://api.lunascreens.com/v1/screens \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Reception TV\",\n    \"description\": \"Wall-mounted TV by the front desk\",\n    \"timeZone\": \"Europe/London\"\n  }'\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch('https://api.lunascreens.com/v1/screens', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'Reception TV',\n    description: 'Wall-mounted TV by the front desk',\n    timeZone: 'Europe/London',\n  }),\n})\nconst { screen } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.post(\n    \"https://api.lunascreens.com/v1/screens\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\n        \"name\": \"Reception TV\",\n        \"description\": \"Wall-mounted TV by the front desk\",\n        \"timeZone\": \"Europe/London\",\n    },\n)\nscreen = response.json()[\"screen\"]\n"
          }
        ]
      }
    },
    "/screens/{id}": {
      "delete": {
        "tags": [
          "Screens"
        ],
        "operationId": "deleteScreen",
        "summary": "Delete a screen",
        "description": "Permanently deletes a screen from your account. This can't be undone.\n\nRequires permission to modify this screen.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID of the screen to delete.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The screen was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X DELETE https://api.lunascreens.com/v1/screens/3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47 \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\"\n"
          },
          {
            "lang": "Node.js",
            "source": "await fetch(`https://api.lunascreens.com/v1/screens/${screenId}`, {\n  method: 'DELETE',\n  headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}` },\n})\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nrequests.delete(\n    f\"https://api.lunascreens.com/v1/screens/{screen_id}\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n)\n"
          }
        ]
      }
    },
    "/screens/{id}/pair": {
      "post": {
        "tags": [
          "Screens"
        ],
        "operationId": "pairScreen",
        "summary": "Pair a device to a screen",
        "description": "Pairs a physical device to a screen so it starts playing the screen's\ncontent.\n\nWhen a device isn't paired yet, it shows a pairing code on its display.\nSend that code as `pairingCode`. Spaces and letter case don't matter, so\n`ab12 cd34 ef56` is the same as `AB12CD34EF56`. Codes change regularly, so\nuse one that's currently on the display.\n\nA successful pair sends a `device.paired` webhook event.\n\nRequires permission to modify this screen.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID of the screen to pair the device to.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "pairingCode"
                ],
                "properties": {
                  "pairingCode": {
                    "type": "string",
                    "description": "The pairing code shown on the device's display.",
                    "example": "AB12CD34EF56"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The device was paired to the screen.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid, for example `pairingCode` is missing, or the pairing code doesn't match a device or has expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Invalid pairing code."
                }
              }
            }
          },
          "403": {
            "description": "The API key is invalid, disabled or revoked, or the key's permission group isn't allowed to modify this screen.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "You can't pair a device to this screen because your permission group doesn't allow you to modify it. Ask an account owner to give you permission to modify this screen.",
                  "code": "CANNOT_MODIFY_SCREEN"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X POST https://api.lunascreens.com/v1/screens/3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47/pair \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"pairingCode\": \"AB12CD34EF56\" }'\n"
          },
          {
            "lang": "Node.js",
            "source": "await fetch(`https://api.lunascreens.com/v1/screens/${screenId}/pair`, {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ pairingCode: 'AB12CD34EF56' }),\n})\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nrequests.post(\n    f\"https://api.lunascreens.com/v1/screens/{screen_id}/pair\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\"pairingCode\": \"AB12CD34EF56\"},\n)\n"
          }
        ]
      }
    },
    "/adverts": {
      "post": {
        "tags": [
          "Adverts"
        ],
        "operationId": "createAdvert",
        "summary": "Create an advert",
        "description": "Adds an image, video or webpage to your library so it can be scheduled\nonto screens.\n\nThe response includes the advert's `id`. Store it, as it's needed to\nupdate or delete the advert.\n\nImages and videos are given by the URL of the file, there's no upload\nendpoint. The advert is created straight away and the file is processed\nin the background: copied into Luna Screens' storage (up to 300MB), its\ndetails read and, for videos, optimised for screens. Follow its progress\nwith `processingState`, by fetching the advert.\n\nRequires permission to modify content.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "advert"
                ],
                "properties": {
                  "advert": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/AdvertInput"
                      },
                      {
                        "type": "object",
                        "required": [
                          "content",
                          "customType"
                        ]
                      }
                    ]
                  }
                }
              },
              "examples": {
                "image": {
                  "summary": "Image",
                  "value": {
                    "advert": {
                      "name": "Summer sale banner",
                      "customType": "image",
                      "content": "https://example.com/media/summer-sale.jpg"
                    }
                  }
                },
                "video": {
                  "summary": "Video",
                  "value": {
                    "advert": {
                      "name": "Product launch",
                      "customType": "video",
                      "content": "https://example.com/media/product-launch.mp4",
                      "soundEnabled": false
                    }
                  }
                },
                "webpage": {
                  "summary": "Webpage",
                  "value": {
                    "advert": {
                      "name": "Company dashboard",
                      "customType": "webpage",
                      "content": "https://example.com/dashboard"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created advert.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "advert": {
                      "$ref": "#/components/schemas/Advert"
                    }
                  }
                },
                "example": {
                  "advert": {
                    "id": "8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58",
                    "listingKey": "8207654540321-8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58",
                    "createdAt": 1792345459678,
                    "updatedAt": 1792345459678,
                    "name": "Summer sale banner",
                    "customType": "image",
                    "content": "https://example.com/media/summer-sale.jpg",
                    "thumbnailUrl": "https://files.lunascreens.com/thumbnails/failed-to-generate-webpage.png",
                    "processingState": "uploading",
                    "processingProgress": 0,
                    "processingError": null
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X POST https://api.lunascreens.com/v1/adverts \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"advert\": {\n      \"name\": \"Summer sale banner\",\n      \"customType\": \"image\",\n      \"content\": \"https://example.com/media/summer-sale.jpg\"\n    }\n  }'\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch('https://api.lunascreens.com/v1/adverts', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    advert: {\n      name: 'Summer sale banner',\n      customType: 'image',\n      content: 'https://example.com/media/summer-sale.jpg',\n    },\n  }),\n})\nconst { advert } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.post(\n    \"https://api.lunascreens.com/v1/adverts\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\n        \"advert\": {\n            \"name\": \"Summer sale banner\",\n            \"customType\": \"image\",\n            \"content\": \"https://example.com/media/summer-sale.jpg\",\n        },\n    },\n)\nadvert = response.json()[\"advert\"]\n"
          }
        ]
      }
    },
    "/adverts/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "ID of the advert.",
          "schema": {
            "type": "string",
            "format": "uuid",
            "example": "8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58"
          }
        }
      ],
      "put": {
        "tags": [
          "Adverts"
        ],
        "operationId": "updateAdvert",
        "summary": "Update an advert",
        "description": "Updates an advert in your library.\n\nSend only the fields you want to change. Fields you leave out keep their\ncurrent values.\n\nIf you change the `content` of an image or video advert, the new file is\nprocessed the same way as when it's created, see `processingState`.\n\nRequires permission to modify content.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "advert"
                ],
                "properties": {
                  "advert": {
                    "$ref": "#/components/schemas/AdvertUpdateInput"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated advert.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "advert": {
                      "$ref": "#/components/schemas/Advert"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X PUT https://api.lunascreens.com/v1/adverts/8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58 \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"advert\": {\n      \"name\": \"Summer sale banner (final)\"\n    }\n  }'\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch(`https://api.lunascreens.com/v1/adverts/${advert.id}`, {\n  method: 'PUT',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    advert: { name: 'Summer sale banner (final)' },\n  }),\n})\nconst { advert: updated } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.put(\n    f\"https://api.lunascreens.com/v1/adverts/{advert['id']}\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\n        \"advert\": {\"name\": \"Summer sale banner (final)\"},\n    },\n)\nupdated = response.json()[\"advert\"]\n"
          }
        ]
      },
      "delete": {
        "tags": [
          "Adverts"
        ],
        "operationId": "deleteAdvert",
        "summary": "Delete an advert",
        "description": "Removes an advert from your library. This can't be undone.\n\nRequires permission to modify content.\n",
        "responses": {
          "200": {
            "description": "The advert was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X DELETE https://api.lunascreens.com/v1/adverts/8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58 \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\"\n"
          },
          {
            "lang": "Node.js",
            "source": "await fetch(`https://api.lunascreens.com/v1/adverts/${advert.id}`, {\n  method: 'DELETE',\n  headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}` },\n})\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nrequests.delete(\n    f\"https://api.lunascreens.com/v1/adverts/{advert['id']}\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n)\n"
          }
        ]
      }
    },
    "/account/permission-groups": {
      "get": {
        "tags": [
          "Permission groups"
        ],
        "operationId": "listPermissionGroups",
        "summary": "List permission groups",
        "description": "Lists every permission group in your account, including the Owner group.\n\nRequires permission to view permission groups or users.\n",
        "responses": {
          "200": {
            "description": "The account's permission groups.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "permissionGroups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PermissionGroup"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl https://api.lunascreens.com/v1/account/permission-groups \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\"\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch('https://api.lunascreens.com/v1/account/permission-groups', {\n  headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}` },\n})\nconst { permissionGroups } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.get(\n    \"https://api.lunascreens.com/v1/account/permission-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n)\npermission_groups = response.json()[\"permissionGroups\"]\n"
          }
        ]
      },
      "post": {
        "tags": [
          "Permission groups"
        ],
        "operationId": "createPermissionGroup",
        "summary": "Create a permission group",
        "description": "Creates a permission group. Users and API keys can then be assigned to it.\n\nOnly `name` is required, but we recommend sending every permission so the\ngroup gets exactly the access you expect. Any you leave out default to:\n\n- `canModify` for `screens`, `contentItems`, `contentItemsLocal`,\n  `billing`, `permissions` and `users`.\n- `noAccess` for `accountSetup`, `apiKeys` and `webhooks`.\n\nDefaults are lowered to your own access where they're more than you have.\nPermissions you set yourself aren't lowered: if any are more than your own\naccess, the request fails with a `403`.\n\nRequires permission to modify permission groups.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/PermissionGroupInput"
                  },
                  {
                    "required": [
                      "name"
                    ]
                  }
                ]
              },
              "example": {
                "name": "Store managers",
                "screens": "granular",
                "screensPermissions": {
                  "3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47": "canModify"
                },
                "contentItems": "canModify",
                "contentItemsLocal": "canModify",
                "billing": "noAccess",
                "permissions": "noAccess",
                "users": "noAccess",
                "accountSetup": "noAccess",
                "apiKeys": "noAccess",
                "webhooks": "noAccess"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The created permission group, including its `id`.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "permissionGroup": {
                      "$ref": "#/components/schemas/PermissionGroup"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X POST https://api.lunascreens.com/v1/account/permission-groups \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Store managers\",\n    \"screens\": \"granular\",\n    \"screensPermissions\": {\n      \"3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47\": \"canModify\"\n    },\n    \"contentItems\": \"canModify\",\n    \"contentItemsLocal\": \"canModify\",\n    \"billing\": \"noAccess\",\n    \"permissions\": \"noAccess\",\n    \"users\": \"noAccess\",\n    \"accountSetup\": \"noAccess\",\n    \"apiKeys\": \"noAccess\",\n    \"webhooks\": \"noAccess\"\n  }'\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch('https://api.lunascreens.com/v1/account/permission-groups', {\n  method: 'POST',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'Store managers',\n    screens: 'granular',\n    screensPermissions: { [screenId]: 'canModify' },\n    contentItems: 'canModify',\n    contentItemsLocal: 'canModify',\n    billing: 'noAccess',\n    permissions: 'noAccess',\n    users: 'noAccess',\n    accountSetup: 'noAccess',\n    apiKeys: 'noAccess',\n    webhooks: 'noAccess',\n  }),\n})\nconst { permissionGroup } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.post(\n    \"https://api.lunascreens.com/v1/account/permission-groups\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\n        \"name\": \"Store managers\",\n        \"screens\": \"granular\",\n        \"screensPermissions\": {screen_id: \"canModify\"},\n        \"contentItems\": \"canModify\",\n        \"contentItemsLocal\": \"canModify\",\n        \"billing\": \"noAccess\",\n        \"permissions\": \"noAccess\",\n        \"users\": \"noAccess\",\n        \"accountSetup\": \"noAccess\",\n        \"apiKeys\": \"noAccess\",\n        \"webhooks\": \"noAccess\",\n    },\n)\npermission_group = response.json()[\"permissionGroup\"]\n"
          }
        ]
      }
    },
    "/account/permission-groups/{id}": {
      "put": {
        "tags": [
          "Permission groups"
        ],
        "operationId": "updatePermissionGroup",
        "summary": "Update a permission group",
        "description": "Changes a permission group. Send only the fields to change; the rest keep\ntheir current values. Changes apply to everyone in the group, including\nAPI keys, from their next request.\n\nYou can't give a group more access than your own, or change a group that\nalready has more access than you, including the Owner group.\n\nRequires permission to modify permission groups.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID of the permission group to update.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "6b8e1f2a-4c3d-4e5f-9a0b-1c2d3e4f5a6b"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PermissionGroupInput"
              },
              "example": {
                "name": "Regional managers",
                "users": "canView"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated permission group.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "permissionGroup": {
                      "$ref": "#/components/schemas/PermissionGroup"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "The permission group doesn't exist in your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Permission group not found."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X PUT https://api.lunascreens.com/v1/account/permission-groups/6b8e1f2a-4c3d-4e5f-9a0b-1c2d3e4f5a6b \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"name\": \"Regional managers\", \"users\": \"canView\" }'\n"
          },
          {
            "lang": "Node.js",
            "source": "const response = await fetch(`https://api.lunascreens.com/v1/account/permission-groups/${permissionGroupId}`, {\n  method: 'PUT',\n  headers: {\n    Authorization: `Bearer ${process.env.LUNA_API_KEY}`,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({ name: 'Regional managers', users: 'canView' }),\n})\nconst { permissionGroup } = await response.json()\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nresponse = requests.put(\n    f\"https://api.lunascreens.com/v1/account/permission-groups/{permission_group_id}\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n    json={\"name\": \"Regional managers\", \"users\": \"canView\"},\n)\npermission_group = response.json()[\"permissionGroup\"]\n"
          }
        ]
      },
      "delete": {
        "tags": [
          "Permission groups"
        ],
        "operationId": "deletePermissionGroup",
        "summary": "Delete a permission group",
        "description": "Permanently deletes a permission group. This can't be undone.\n\nA group that still has users in it can't be deleted; move them to another\ngroup first. You also can't delete a group that has more access than your\nown, including the Owner group.\n\nRequires permission to modify permission groups.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "ID of the permission group to delete.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "example": "6b8e1f2a-4c3d-4e5f-9a0b-1c2d3e4f5a6b"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The permission group was deleted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Success"
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid, for example the group still has users in it.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Cannot delete permission group because there are users attached to it."
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "The permission group doesn't exist in your account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "message": "Permission group not found."
                }
              }
            }
          }
        },
        "x-codeSamples": [
          {
            "lang": "cURL",
            "source": "curl -X DELETE https://api.lunascreens.com/v1/account/permission-groups/6b8e1f2a-4c3d-4e5f-9a0b-1c2d3e4f5a6b \\\n  -H \"Authorization: Bearer $LUNA_API_KEY\"\n"
          },
          {
            "lang": "Node.js",
            "source": "await fetch(`https://api.lunascreens.com/v1/account/permission-groups/${permissionGroupId}`, {\n  method: 'DELETE',\n  headers: { Authorization: `Bearer ${process.env.LUNA_API_KEY}` },\n})\n"
          },
          {
            "lang": "Python",
            "source": "import os, requests\n\nrequests.delete(\n    f\"https://api.lunascreens.com/v1/account/permission-groups/{permission_group_id}\",\n    headers={\"Authorization\": f\"Bearer {os.environ['LUNA_API_KEY']}\"},\n)\n"
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "An API key created in the Luna Screens dashboard under\n**Account → API keys**. Keys start with `lsk_`.\n"
      }
    },
    "schemas": {
      "Screen": {
        "type": "object",
        "description": "A screen in your account.",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier for the screen.",
            "example": "3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47"
          },
          "name": {
            "type": "string",
            "description": "Display name of the screen.",
            "example": "Reception TV"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional description of the screen. `null` if not set.",
            "example": "Wall-mounted TV by the front desk"
          },
          "timeZone": {
            "type": "string",
            "description": "IANA time zone the screen's schedule runs in.",
            "example": "Europe/London"
          }
        }
      },
      "Advert": {
        "description": "An advert in your library.",
        "allOf": [
          {
            "$ref": "#/components/schemas/AdvertInput"
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for the advert.",
                "example": "8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58"
              },
              "listingKey": {
                "type": "string",
                "description": "Used internally. Likely will be removed in the future.",
                "example": "8207654540321-8d0f5b7e-2c4a-4f1e-b3d9-6a7c1e0f2b58"
              },
              "createdAt": {
                "type": "integer",
                "description": "When the advert was created, in milliseconds since the Unix epoch.",
                "example": 1792345459678
              },
              "updatedAt": {
                "type": "integer",
                "description": "When the advert was last changed, in milliseconds since the Unix epoch.",
                "example": 1792345459678
              },
              "processingState": {
                "type": "string",
                "readOnly": true,
                "enum": [
                  "uploading",
                  "extracting",
                  "optimising",
                  "ready",
                  "errored"
                ],
                "description": "Where an image or video is in being processed after it's created or\nits `content` changes. Always `ready` for webpages.\n\n- `uploading`: the file is being copied from its URL into Luna\n  Screens' storage. Skipped if it's already stored with us.\n- `extracting`: its `type`, `width`, `height` and, for videos,\n  `duration` are being read.\n- `optimising`: a video is being optimised for screens.\n- `ready`: finished.\n- `errored`: it couldn't be processed, see `processingError`. Screens\n  skip the advert. Update `content` to try again.\n\nScreens show a placeholder while it's being processed.\n",
                "example": "ready"
              },
              "processingProgress": {
                "type": [
                  "number",
                  "null"
                ],
                "readOnly": true,
                "description": "How much of the file has been copied, from 0 to 100, while `uploading`, or how far a video's optimisation has got, from 0 to 99, while `optimising`. Otherwise null.",
                "example": null
              },
              "processingError": {
                "type": [
                  "string",
                  "null"
                ],
                "readOnly": true,
                "description": "Why the file couldn't be processed when `processingState` is `errored`. Otherwise null.",
                "example": null
              }
            }
          }
        ]
      },
      "AdvertInput": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AdvertUpdateInput"
          },
          {
            "type": "object",
            "properties": {
              "customType": {
                "type": "string",
                "enum": [
                  "image",
                  "video",
                  "webpage"
                ],
                "description": "The kind of advert. Determines how it's displayed and edited in the\ndashboard, and which other fields are required.\n",
                "example": "image"
              }
            }
          }
        ]
      },
      "AdvertUpdateInput": {
        "type": "object",
        "description": "The fields of an advert that can be changed after it's created.",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name shown in your library.",
            "example": "Summer sale banner"
          },
          "content": {
            "type": "string",
            "format": "uri",
            "description": "Publicly accessible HTTPS URL of the media. For a `webpage` advert, the\nURL of the page to display.\n\nFor images and videos, we download the file (up to 300MB) into Luna\nScreens' storage, read its details and optimise videos for screens. This\nhappens in the background after the advert is created or its `content`\nchanges, see `processingState`. Once copied, `content` is the URL of our\ncopy. Sending the original URL again isn't treated as a change.\n",
            "example": "https://example.com/media/summer-sale.jpg"
          },
          "type": {
            "type": "string",
            "readOnly": true,
            "description": "MIME type of the content. For images and videos it's read from the file\nonce it's processed, any value you send is ignored. Always `text/html`\nfor webpages.\n",
            "example": "image/jpeg"
          },
          "width": {
            "type": "integer",
            "readOnly": true,
            "description": "Width of the content in pixels. For images and videos it's read from the file once it's processed, any value you send is ignored.",
            "example": 1920
          },
          "height": {
            "type": "integer",
            "readOnly": true,
            "description": "Height of the content in pixels. For images and videos it's read from the file once it's processed, any value you send is ignored.",
            "example": 1080
          },
          "duration": {
            "type": "number",
            "readOnly": true,
            "description": "Length of a video in seconds, read from the file once it's processed. Any value you send is ignored.",
            "example": 37.3
          },
          "soundEnabled": {
            "type": "boolean",
            "description": "Whether a video plays with sound.",
            "example": false
          },
          "thumbnailUrl": {
            "type": "string",
            "format": "uri",
            "readOnly": true,
            "description": "URL of a thumbnail image shown in your library, made by us. Any value\nyou send is ignored. For images and videos it's made from the file once\nit's stored with us, for webpages a screenshot is taken in the\nbackground after the advert is created or its `content` changes. A\nplaceholder is shown until it's ready.\n",
            "example": "https://files-2.lunascreens.com/thumb/uploads/41fde444-8c6a-40ca-8b01-ebcc1d33d775/298876b8-559b-47df-8268-1d58f1fbc6c5/summer-sale.jpg"
          }
        }
      },
      "PermissionGroup": {
        "description": "A permission group in your account. Every user and API key belongs to one.",
        "allOf": [
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Unique identifier for the permission group.",
                "example": "6b8e1f2a-4c3d-4e5f-9a0b-1c2d3e4f5a6b"
              }
            }
          },
          {
            "$ref": "#/components/schemas/PermissionGroupInput"
          },
          {
            "type": "object",
            "properties": {
              "isOwnerPermissionGroup": {
                "type": "boolean",
                "description": "`true` for the account's Owner group, which always has full access\nwhatever its other fields say. Only the account owner is in it, and\nit can't be changed or deleted with the API. Not set on other groups.\n",
                "example": false
              },
              "createdAt": {
                "type": "integer",
                "description": "When the permission group was created, in milliseconds since the Unix epoch.",
                "example": 1792345459678
              },
              "updatedAt": {
                "type": "integer",
                "description": "When the permission group was last changed, in milliseconds since the Unix epoch. Not set if it's never been changed.",
                "example": 1792345459678
              }
            }
          }
        ]
      },
      "PermissionGroupInput": {
        "type": "object",
        "description": "The settings of a permission group. Each permission is one of these levels:\n\n- `noAccess`: can't see or use the feature.\n- `canView`: can see the feature but not change anything.\n- `canModify`: can see and change everything in the feature.\n\nScreens and content can also be `granular`, see each field.\n\nFields not listed here are rejected with a `400`, so a typo doesn't get\nsilently ignored.\n",
        "properties": {
          "name": {
            "type": "string",
            "description": "Display name of the permission group.",
            "example": "Store managers"
          },
          "screens": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify",
              "granular"
            ],
            "description": "Access to screens. `granular` sets access screen by screen with\n`screensPermissions`, with no access to any screen not listed there.\n",
            "example": "granular"
          },
          "screensPermissions": {
            "type": "object",
            "description": "Only used when `screens` is `granular`. Maps screen IDs to that screen's\npermission level. Only screens in your account get access. It's cleared\nwhen `screens` is anything else, and replaces the whole object when\nupdating.\n",
            "additionalProperties": {
              "type": "string",
              "enum": [
                "noAccess",
                "canView",
                "canModify"
              ]
            },
            "example": {
              "3f1c2a9e-7b4d-4e8a-9c61-2d5f8b0a1e47": "canModify",
              "9a2e4c6b-1d3f-4a5e-8b7c-0f1e2d3c4b5a": "canView"
            }
          },
          "contentItems": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify",
              "granular"
            ],
            "description": "Access to adverts in the library. `granular` gives access only to\nadverts added by members of this permission group.\n",
            "example": "canModify"
          },
          "contentItemsLocal": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Only used when `contentItems` is `granular`. Access to the adverts added\nby members of this permission group.\n",
            "example": "canModify"
          },
          "billing": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to billing, plans and invoices.",
            "example": "noAccess"
          },
          "permissions": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to permission groups, including these endpoints.",
            "example": "noAccess"
          },
          "users": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to the account's users and invites.",
            "example": "canView"
          },
          "accountSetup": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to account setup, such as a custom domain and email.",
            "example": "noAccess"
          },
          "apiKeys": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to API keys.",
            "example": "noAccess"
          },
          "webhooks": {
            "type": "string",
            "enum": [
              "noAccess",
              "canView",
              "canModify"
            ],
            "description": "Access to webhook endpoints.",
            "example": "noAccess"
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "Human-readable description of the error.",
            "example": "name is required."
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code, when available."
          }
        }
      },
      "Success": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request was invalid, for example a required field is missing.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "message": "name is required."
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key is invalid, disabled or revoked, or the key's permission group doesn't allow this action.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "message": "Unauthorised."
            }
          }
        }
      },
      "NotFound": {
        "description": "The resource doesn't exist in your account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "message": "Screen not found."
            }
          }
        }
      }
    }
  }
}