> 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://<your-server>` 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)).