> For the complete documentation index, see [llms.txt](https://docs.xibosignage.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xibosignage.com/developer/integrate/openapi.md). # OpenAPI This section deals with general information related to making requests. ## Enveloping All requests can be enveloped by adding `envelope=1` as a query parameter. ## Errors API errors are reported via the 4xx and 5xx HTTP response codes, the most common of which are: * 404 Not Found (the resource could not be found) * 409 Conflict (the request conflicts with an existing entity) * 422 Unprocessable Entity (the entity provided is invalid) Extra information is available in the response body and is JSON formatted. A human readable error message is presented, the HTTP status code and a data block indicating further information. An example 422 response: ```json { "error": { "message": "Layout Name must be between 1 and 50 characters", "code": 422, "data": { "property": "name" } } } ``` 5xx errors indicate an issue with the CMS environment and extra information will be available in the CMS logs. ## Grid Data — lists of records Lists of records, henceforth referred to as grids, are paged by default, with a default page size of 10 records. They also have a default sort order applied to them, which is appropriate for that record type. ### Paging Paging is controlled by 2 parameters, `start` and `length`. The `start` parameter denotes at which record in the set the results should start from, and `length` denotes the number of records to return. The default `length` is 10 records which means to get page 2, `start=20` would be provided. The headers of the response contain extra information related to paging, these are: * `X-Total-Count`: The total count of records (all pages) * `Link`: Links pointing to the first, prev, next and last pages (as appropriate) The Link header is RFC formatted: and consists of a url and `;` and a `rel=` (relationship) attribute. For example, the headers returned with page 1 are: ``` Link: ; rel="next", ; rel="first" X-Total-Count: 26 ``` ### Sorting Sorting happens in two steps using a columns array and an order array. The columns array describes the fields that should be ordered, and the order array describes how they should be ordered and in what order. Taking the layout grid as an example, if you want to order by the `duration` of the layout, descending, specify a columns array: ``` columns[1][data]:duration ``` And an order array: ``` order[1][column]:1 order[1][dir]:desc ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xibosignage.com/developer/integrate/openapi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.