> For the complete documentation index, see [llms.txt](https://knowledgebase.fabricdata.com/xytech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://knowledgebase.fabricdata.com/xytech/rest-api-v3/introduction.md). # Introduction API v3 is the latest version of the Xytech Platform REST API. It builds on v2 with one goal in mind: make the API **easier to use and harder to get wrong**, while keeping it fast under load. v3 is generally available from **release 26.5**. It is enabled by default - there is no longer a feature flag to turn on - and it runs alongside v2, so existing v2 integrations keep working unchanged. ### Why v3? The API v3 initiative was guided by three objectives: * **Embrace standards.** Align Xytech's API with widely understood REST conventions for URLs, request bodies, and HTTP status codes, so that developers familiar with other modern APIs feel at home. * **Apply better defaults.** Ship sensible, safe defaults - especially around result size - so that a naive call stays performant and doesn't put the system under unnecessary load. * **Improve functionality.** Add capabilities that integrators have asked for, such as querying setup documents and sending complex queries in a request body. ### What's new at a glance | Area | v2 | v3 | | -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Addressing a record** | `?keyName=keyValue` in the query string | `/keyName/keyValue` as clean path segments | | **Records with `/` in the code** | Fails (e.g. `AVL/007`) | Supported via a dedicated `/where/` route | | **The database** | Required in the URL path | Dropped - the server's database is used automatically (name one via `?database=` only on multi-database servers) | | **List queries** | GET only, filters in the URL | GET **or** POST, with a structured JSON body for complex queries | | **Setup documents** | Return every record | Can be filtered like list documents | | **Field selection** | Optional | **Required** on every GET (JSON `fields` parameter) | | **Result size** | Unbounded unless you asked for a page | A safe **default page size** is always applied | | **PATCH `Content-Type`** | ops = `application/json`, doc = `application/json-patch+json` | **Reversed/standardised**: ops = `application/json-patch+json`, doc = `application/json` | | **Errors** | Almost everything was `400` | Correct status + machine-readable `code` in the body | | **Discovery** | - | Every document's v3 Swagger doc is linked from the `/apidocs` index | ### Key benefits * **Cleaner URLs.** Record keys are path segments (`/job_no/123`) rather than `?job_no=123`, so simple lookups read cleanly and need no encoding. (The JSON `fields` and `query` parameters still need URL-encoding in strict clients.) * **Predictable performance.** A required `fields` projection and a system default page size protect both your integration and the platform from accidental "select everything" calls. * **Standard, actionable errors.** A `404` means not found, a `401` means unauthenticated, and the response body carries a stable `code` you can branch on. * **More reach.** Setup documents - previously all-or-nothing - can now be filtered, and complex queries that used to produce unwieldy URLs can be sent as a JSON body. ### How to read this guide * [**Migrating from API v2 to API v3**](/xytech/rest-api-v3/migrating-from-api-v2-to-api-v3.md) - a focused checklist of what changes for an existing v2 integration, with before/after examples. * [**API v3 user guide**](/xytech/rest-api-v3/api-v3-user-guide.md) - a task-oriented reference for building a new integration on v3: authentication, addressing records, querying, paging, updating, and error handling. > **Conventions used in this guide.** Examples use `https://` as a placeholder for your Xytech web address - replace it with your own. The exact base URL for your environment is shown on the `/apidocs` page (see [API reference](/xytech/rest-api-v3/api-v3-user-guide/api-reference-swagger.md)). --- # 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://knowledgebase.fabricdata.com/xytech/rest-api-v3/introduction.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.