> 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/api-v3-user-guide.md).

# API v3 user guide

This guide walks through everything you need to build an integration on API v3, in the order you'll typically need it:

1. [Fundamentals and data model](/xytech/rest-api-v3/api-v3-user-guide/fundamentals-and-data-model.md) - documents, primary/sub-tables, and how they map to REST endpoints.
2. [Methods and response codes](/xytech/rest-api-v3/api-v3-user-guide/methods-and-response-codes.md) - the HTTP verbs the API uses and what each returns.
3. [Authentication](/xytech/rest-api-v3/api-v3-user-guide/authentication.md) - obtain and send a bearer token.
4. [Base URL and databases](/xytech/rest-api-v3/api-v3-user-guide/base-url-and-databases.md) - where calls go and how the database is chosen.
5. [Addressing a document](/xytech/rest-api-v3/api-v3-user-guide/addressing-a-document.md) - the `/keyName/keyValue` path syntax, and `keyEncoding=base16` for keys with special characters.
6. [Key fields and time formats](/xytech/rest-api-v3/api-v3-user-guide/key-fields-and-time-formats.md) - the key sub-section in payloads, and date/time conventions.
7. [Querying list documents (GET)](/xytech/rest-api-v3/api-v3-user-guide/querying-list-documents-get.md) - filter, sort, and select fields from the URL.
8. [Querying with POST](/xytech/rest-api-v3/api-v3-user-guide/querying-with-post.md) - send complex queries as a JSON body.
9. [Filtering reference](/xytech/rest-api-v3/api-v3-user-guide/filtering-reference.md) - the full set of operators.
10. [Paging and sorting](/xytech/rest-api-v3/api-v3-user-guide/paging-and-sorting.md) - the default page size and pagination headers.
11. [Querying setup documents](/xytech/rest-api-v3/api-v3-user-guide/querying-setup-documents.md) - filtering reference/lookup lists the same way as list documents.
12. [Creating and updating documents](/xytech/rest-api-v3/api-v3-user-guide/creating-and-updating-documents.md) - POST, PUT, and PATCH.
13. [Save arguments](/xytech/rest-api-v3/api-v3-user-guide/save-arguments.md) - the `saveArgument` header for triggering app-server functions (load template, void, approve, etc.).
14. [Custom field handling](/xytech/rest-api-v3/api-v3-user-guide/custom-field-handling.md) - naming and using fields added through document customisation.
15. [Examples](/xytech/rest-api-v3/api-v3-user-guide/examples.md) - worked cURL examples for the calls above.
16. [Error responses](/xytech/rest-api-v3/api-v3-user-guide/error-responses.md) - status codes and error-code catalogue.
17. [Performance recommendations](/xytech/rest-api-v3/api-v3-user-guide/performance-recommendations.md) - using the API efficiently.
18. [API reference (Swagger)](/xytech/rest-api-v3/api-v3-user-guide/api-reference-swagger.md) - the generated per-document reference.

## Quick start

```http
# 1. Get a token (served by v2 - see Authentication; or use a provider bearer token / Basic auth)
POST https://<your-server>/api/v2/database/<your-database>/orchestration/auth/login
Content-Type: application/json

{ "username": "myuser", "password": "mypassword" }
```

```http
# 2. Read a single job (fields is required on every GET)
GET https://<your-server>/api/v3/JmJob/job_no/123?fields={"jm_job":["job_no","customer_name"]}
Authorization: Bearer <access_token>
```

```http
# 3. Query a list, filtered and paged (list fields use the "L" alias)
GET https://<your-server>/api/v3/JmJobList?fields={"L":["job_no","job_desc"]}&query={"job_no":{"$range":[10,100]}}&pagesize=50&page=1
Authorization: Bearer <access_token>
```

Every example below uses `https://<your-server>` for your Xytech web address - substitute your own. v3 calls don't include a database (see [Base URL and databases](/xytech/rest-api-v3/api-v3-user-guide/base-url-and-databases.md)).