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.

• 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.

• - a focused checklist of what changes for an existing v2 integration, with before/after examples.

• - 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 ).

Base URL

All v3 endpoints live under:

https://<your-server>/api/v3/

<your-server> is your Xytech web address. The exact base URL for your environment is shown at the top of the /apidocs page.

The database

In v3 you don't put a database in the URL. Where v2 required a /database/{name}/ segment, v3 uses the server's configured database automatically - so a call is simply:

GET https://<your-server>/api/v3/JmJob/job_no/123

The rare exception: multiple databases

The only time you name a database is the uncommon case where a single server hosts more than one database. Then add a database query parameter to pick one:

GET https://<your-server>/api/v3/JmJob/job_no/123?database=OtherDatabase

On the usual single-database server, leave it off entirely. On a multi-database server, omitting it falls back to the server's default database - which may not be the one you want, so name it explicitly in that case.

The API version is part of the URL path (/api/v3/). There is no api-version header - you select the version by the path you call. v2 and v3 are available simultaneously, so you can migrate endpoint by endpoint.

Every document has an auto-generated OpenAPI (Swagger) specification describing its exact endpoints, fields, and operations. This is the authoritative, always-up-to-date reference for the documents available in your environment.

The /apidocs index

Open the API documentation index in a browser:

https://<your-server>/ApiDocs

To view the index for a specific database:

https://<your-server>/ApiDocs/MyDatabase

The index lists every document grouped by module, with a filter box to find a document quickly. Each document offers a link to its v2 and its v3 specification - use the [v3] link for the current API.

Spec URLs

The v3 specification for a single document is served from:

https://<your-server>/api/v3/spec/{documentCode}

Compare this to the v2 spec URL, which includes the database in the path:

https://<your-server>/api/v2/database/{database}/spec/{documentCode}

The database segment is absent from the v3 spec URL - consistent with v3 not using a database URL parameter (see ).

The generated spec documents, per document:

• Available operations (GET / POST / PUT / PATCH) and their routes.

• Field names and types for request and response bodies.

• The supported filter operators for querying (mirrors the ).

Because the reference is generated from your environment, it always reflects the documents and fields actually configured for your database - start here whenever you need the exact field names for a specific document.

List documents (e.g. JmJoblist) return multiple records. You filter, sort, page, and select fields using query-string parameters.

GET https://<your-server>/api/v3/JmJobList?fields={"L":["job_no","job_desc"]}&query={"job_no":{"$range":[10,100]}}&sort=job_no&pagesize=50&page=1

Parameters

Every v3 GET must include a fields parameter - omit it and the call fails with 400 XY_MISSING_FIELD ("The 'fields' parameter is mandatory for API v3."). This is a change from v2 and applies to single-record, setup, and list GETs alike.

fields is a JSON object - a comma-separated list is rejected with 400 XY_BAD_REQUEST. The shape is {"table": ["field1", "field2", {"dropdown": ["key1", "key2"]}]}.

The table name depends on the document type:

• List and report documents use the list-table alias "L" (and the response is keyed by "L" too):

• Single-record and setup documents use the document's primary table name (e.g. jm_job, sch_resource, jm_phase):

Use the to find the exact table and field names for a document. A nested object (e.g. { "division_no": [...] }) projects selected keys of a dropdown/lookup field.

Encoding note: if your HTTP client is strict about {, }, ", URL-encode the value of the fields and query parameters. For large or deeply nested filters, prefer .

query takes a JSON object where each key is a field and each value is either a literal (exact match) or an operator object. Operators are prefixed with $.

See the for the complete operator list.

Every list response is paged. If you don't set pagesize, the system default (200) is applied; larger requests are clamped to the cap. Read the total row count from the Pagination-Count response header and iterate with page. See .

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 - documents, primary/sub-tables, and how they map to REST endpoints.

2. Methods and response codes - the HTTP verbs the API uses and what each returns.

3. - obtain and send a bearer token.

4. - where calls go and how the database is chosen.

5. - the /keyName/keyValue path syntax, and keyEncoding=base16 for keys with special characters.

6. - the key sub-section in payloads, and date/time conventions.

7. - filter, sort, and select fields from the URL.

8. - send complex queries as a JSON body.

9. - the full set of operators.

10. - the default page size and pagination headers.

11. - filtering reference/lookup lists the same way as list documents.

12. - POST, PUT, and PATCH.

13. - the saveArgument header for triggering app-server functions (load template, void, approve, etc.).

14. - naming and using fields added through document customisation.

15. - worked cURL examples for the calls above.

16. - status codes and error-code catalogue.

17. - using the API efficiently.

18. - the generated per-document reference.

Every example below uses https://<your-server> for your Xytech web address - substitute your own. v3 calls don't include a database (see ).

v3 runs side by side with v2 - nothing you have today stops working. You migrate by pointing calls at the v3 path and adjusting for the changes below. You can migrate one endpoint at a time.

Each section states the change, shows a v2 ? v3 before/after, and flags anything that could break a naive port.

1. Change the base path and drop the database

- GET https://<your-server>/api/v2/database/MyDatabase/JmJob/...
+ GET https://<your-server>/api/v3/JmJob/...

v3 no longer takes a database in the URL - the server uses its configured database automatically, so drop the /database/{name}/ segment entirely.

Watch out: the only exception is a server that hosts more than one database. There, add ?database=Name to target one; otherwise the server falls back to its default. See .

Because the value is now a path segment, = no longer appears in your URLs.

A /where/ route captures the rest of the path, slashes included:

This is the change most likely to break an existing integration. Every v3 GET must include a fields parameter, and it must be JSON (a comma-separated list is rejected):

Omit it and you get 400 XY_MISSING_FIELD; send a comma list and you get 400 XY_BAD_REQUEST. The shape is {"table": ["field", {"dropdown": ["key1","key2"]}]}. Applies to single-record, setup, and list GETs. See .

v3 always applies the system default page size (200 unless your administrator changed MAX_LIST_ROWS_REST_API); larger requests are clamped.

Watch out: if your v2 code assumed one response held all rows, it must now page. Read the total from the Pagination-Count response header and loop with ?page=. See .

GET with query still works for simple cases. See .

Setup documents (e.g. TcActivity, JmPhase, MoTask) can now be filtered with the same query and fields parameters as list documents, instead of returning every record. See .

v3 standardises PATCH bodies on the conventional mapping, which is the opposite of v2:

Watch out: swap your PATCH Content-Type headers. See .

v3 returns the correct status and a JSON body { status, code, error }:

Watch out: branch on the HTTP status and the body code (not the free-text error, and not a blanket 400). See .

• Point calls at /api/v3/... and drop the /database/{name}/ segment (add ?database= only on multi-database servers).

• Convert keyName=keyValue addressing to /keyName/keyValue.

v3 addresses a specific record using path segments for the key, instead of the key=value query syntax used by v1/v2.

The standard form: /document/keyName/keyValue

GET https://<your-server>/api/v3/JmJob/job_no/123

• JmJob - the document code.

• job_no - the key field name.

• 123 - the key value.

Every v3 GET also requires a JSON fields parameter (omitted from the addressing examples here for clarity) - see Querying list documents.

Because the value is a path segment rather than a query parameter, the = character no longer appears in your URLs, so most simple lookups need no manual URL-encoding.

Some documents let users define their own codes, and those codes can contain characters that are not valid in a URL path segment - most commonly a /, for example a resource code of AVL/007. A raw or percent-encoded / in a path segment isn't reliable: IIS request filtering, reverse proxies (ARR), and load balancers commonly decode, normalize, or reject %2F before your request reaches the API.

v3 solves this by letting the client Base16 (hex) encode the key value and signal it with the keyEncoding=base16 query parameter. The server decodes the value before doing the lookup, so the special character never travels through the URL as itself.

Here 41564c2f303037 is the Base16 encoding of AVL/007 - every byte of the UTF-8 value written as two hex digits (A?41, V?56, L?4c, /?2f, ...). The hex alphabet (0-9a-f, case-insensitive) contains only URL-unreserved characters, so it passes through every layer of infrastructure unchanged.

Rules:

• keyEncoding is explicit, never auto-detected - without it, key values are used verbatim. This is deliberate: a plain value can itself look like valid hex (e.g. face), so guessing would silently corrupt ordinary keys.

• The only supported value today is keyEncoding=base16.

Use keyEncoding=base16 whenever a key value may contain special characters. Documents with user-definable codes where this commonly applies include:

• SchResource (resource codes)

• SchGroup (group codes)

• JmBillingCode (billing codes)

...and any other document whose code is user-definable.

Rule of thumb: if the value is a clean, simple identifier, address it directly - /{keyName}/{keyValue}. If it can contain a / or other special character, Base16-encode the value and add ?keyEncoding=base16.

v2 compatibility note: v2's /where/{key} route (which captured the rest of the path, slashes included) still exists, but only under v2 URLs - /api/v2/database/{database}/{document}/where/{key}. It is not available under v3 URLs: calling /api/v3/.../where/... does not invoke it - where is parsed as an ordinary key name and the call fails with a "key not valid" error. Use keyEncoding=base16 for all v3 calls.

Setup documents hold reference/lookup data - for example:

• TcActivity - TimeCard activities

• JmPhase - phases

In v2 most failures came back as 400. v3 returns the correct HTTP status code and a JSON body identifying the error.

Response shape

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "status": 404,
  "code": "XY_NOT_FOUND",
  "error": "Alternate key not found: table=sch_resource, column=resource_code, value=FRED01"
}

The body has three fields:

• status - the numeric HTTP status (matches the status line).

• code - a stable, machine-readable error code (the XY_* values below). Branch on this.

• error - a human-readable message. Log it; don't branch on the text.

v3 uses standard HTTP status codes; where several client errors map to 400, the code field distinguishes them.

1. Check the HTTP status class: 2xx success, 4xx client error, 5xx server error.

2. For 4xx, branch on the body code (e.g. re-authenticate on XY_UNAUTHORIZED, surface the missing field on XY_MISSING_FIELD

Custom fields

Any custom fields you define through document customization are automatically included in the REST API definition. They follow a specific naming convention: the Customization Code you created during document customisation, concatenated with the internal field name by an underscore:

{customization code}_{field name}

These custom fields appear in GET responses and can be set in POST/PATCH/PUT payloads just like standard fields, using that concatenated name.

Custom drop-down fields with additional attributes

You can enable a document-customisation flag, "Additional API details", on a custom drop-down field. When enabled, a REST API call returns the additional attributes stored with the dropdown record (such as external_key) rather than just the value.

• Not enabled - the custom drop-down field returns its value only.

• Enabled - the field returns an object including the additional attributes (e.g. external_key).

Screenshots of the document-customisation screens (Customization Code, internal field names, and the "Additional API details" checkbox) are available in the existing REST API documentation and apply unchanged to v3.

All write bodies are document-shaped JSON: an object keyed by the primary table name whose value is an array of records (the same shape a GET returns, minus the read-only key sub-sections). Times follow ISO-8601 - see Key fields and time formats.

Create - POST

POST to the document endpoint with Content-Type: application/json and a document payload.

POST https://<your-server>/api/v3/SchResource
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "sch_resource": [
    { "resource_code": "FRED01", "resource_desc": "Fred", "external_key": "Ext001" }
  ]
}

Success is 201 Created, and the body reports the identifiers of the created record(s):

{
  "message": null,
  "tables": ["sch_resource"],
  "sch_resource": {
    "record_identifiers": ["resource_code"],
    "records": [ { "resource_code": "FRED01" } ]
  }
}

To generate a primary key, set it to -1 (see Key fields and time formats).

Update - PATCH (two body formats)

PATCH updates an existing record. The body format is selected by Content-Type:

• op - the operation, e.g. replace, add, remove.

• path - the field name (no leading slash).

The primary key must appear both in the URL and in the body.

Sending an operation array with application/json, or a document payload with application/json-patch+json, is rejected - match the body to the Content-Type.

PUT creates a record, or updates it if one already exists (matched on external_key). Use the keyed URL with Content-Type: application/json and a document payload.

Success is 204 No Content. Use DELETE sparingly - changing a record's status is often preferable to removing it.

List endpoints accept PATCH to update every record matching a query - the API equivalent of the UI's Grid Update. Send the operation array with application/json-patch+json; see .

Field names and requirements vary per document - the generated is the authoritative source for each document's schema.

To keep responses fast and protect the platform, v3 always applies a page size to list results:

• If you don't send a page size, the system default is used.

• If you request a page size larger than the cap, it is clamped to the cap.

The default/cap is 200 rows unless your administrator has changed the MAX_LIST_ROWS_REST_API

Issues currently known to affect API v3. Each entry describes the behaviour you will see, and the recommended approach until it is addressed.

Filter groups: nesting an or group inside another or group is rejected

An "or" group cannot contain another "or" group - the request is rejected with an error naming the field rather than the filter being silently altered. This holds up to two levels of alternation; see Querying with POST for the shapes this allows and disallows.

The same limitation applies to the $or filter in API v2.

Basic v3 calls. Replace <your-server> with your Xytech web address and <access_token> with your bearer token (see Authentication). Every GET must include a JSON fields parameter.

GET a single record

curl --location --globoff \
  'https://<your-server>/api/v3/SchResource/resource_code/FRED01?fields={"sch_resource":["resource_code","resource_desc","external_key"]}&nullvaluehandling=ignore' \
  --header 'Authorization: Bearer <access_token>'

Response - note the key sub-section (resource_code) plus root fields:

{
  "sch_resource": [
    {
      "resource_code": { "resource_code": "FRED01" },
      "resource_desc": "Fred",
      "external_key": "Ext001"
    }
  ]
}

GET a filtered list

List documents project fields under the list-table alias "L" (see Querying list documents):

curl --location --globoff \
  'https://<your-server>/api/v3/JmJobList?fields={"L":["job_no","job_desc"]}&query={"job_no":{"$range":[10,100]}}&pagesize=50&page=1' \
  --header 'Authorization: Bearer <access_token>'

GET a record whose key contains a slash

Base16 (hex) encode the key value and add keyEncoding=base16. AVL/007 encodes to 41564c2f303037 - see Addressing a document for the full rule set.

Response (201 Created):

An array of {op, path, value} operations; path is the bare field name.

Response: 204 No Content.

Update every record matching a query - the API equivalent of the UI's Grid Update. Send the operation array with application/json-patch+json:

For a text "contains" match use $likeAnd, e.g. query={"job_desc":{"$likeAnd":"Sport"}}. See the Filtering reference.

Create, or update if a record with the same external_key exists. Keyed URL, application/json, document payload.

Response: 204 No Content.

A ready-to-run collection of these v3 examples is published publicly on Postman:

Open it in the Postman web app or Run in Postman to import it into your own workspace, then set the collection variables (baseUrl, username, password) and send the requests. The collection groups the calls into Authentication, Read, Query & filter, Create & update, and Save arguments, and mirrors the rules on these pages - fields is required on every GET, list documents use the "L" alias, and v3 data calls take no database in the URL.

Complex queries used to force everything into a long, heavily encoded URL. v3 adds a POST /query route on list and report endpoints that accepts a structured JSON body, so filtering, paging, sorting, and field selection all travel in the request body.

The same route is available for report documents:

filtering and fields are required; paging and sorting are optional.

Xytech is, at a fundamental level, a system that creates, updates, and uses a particular type of data object called a document.

• Each Xytech document represents a database table (or a collection of tables) and has a REST API endpoint.

  • Each endpoint has a primary table and may have one or more sub-tables.

  • All sub-tables are children of the primary table, and a sub-table can itself have child sub-tables.

• Each endpoint represents one of the following document types:

  • Setup - generally describes a single item and usually contains only a primary table. Setup documents manage simple items used to build lists of options in other documents (status labels, predefined code sets, etc.). In v3 these can be filtered - see .

  • Maintenance - describes master data (used in transactional data) or transactional data. Maintenance documents often contain one or more sub-tables.

The REST API is JSON-based. Every endpoint has an OpenAPI 3.0 specification available in your environment - see to browse it.

A document's payload is a JSON object keyed by the primary table name, whose value is an array of records. Sub-tables appear as nested arrays within a record. For example, a Work Order (jm_work_order) can carry transaction sub-tables inside each record.

Where a ~/ prefix appears before an endpoint in the API reference, that indicates a sub-table endpoint of the primary endpoint.

This page covers the shared concepts. For how records are addressed and keyed, see and .

Some operations require a saveArgument header to tell the app server to perform a function as part of an API call. For example, to load a Work Order Template when creating a Work Order, you supply the saveArgument header and include the wo_template_no in the payload.

Examples below use v3 conventions: the /api/v3/ base, path-segment keys, and a bearer token. Where a Save Argument is used with a PATCH field-operation body ([{op, path, value}]), it is sent with Content-Type: application/json-patch+json; a POST with a document payload uses Content-Type: application/json (see ).

Applicable endpoints: JmWorkOrder, MoMediaOrder, XmTransmissionOrder

Loads a Work Order Template to an order. This is the improved method (from release 26.1) that can append or replace existing transactions.

Options: 1 = append template transactions to existing order transactions; 0 = replace existing order transactions with the template's. Applies to POST, PATCH, and PUT, and requires wo_template_no in the payload.

The prior method is still supported: saveArgument: {"LoadTemplate":"15"} where the number is the template to load; add "LoadChildTemplates":"Y" (from release 11.3) to load child templates. The template number must be in both the header and the payload.

For transmission orders, load a Service Template and populate service_template_no:

Load multiple by comma-separating the values; in that case you may leave service_template_no null in the body:

Applicable endpoints: JmWorkOrder, MoMediaOrder, XmTransmissionOrder

When a call changes an order's wo_begin_dt and/or wo_end_dt, the app normally asks the user how existing order transactions should react. There's no one to ask over the API, so by default the transactions are left unchanged. Use one of these save arguments to choose a behavior instead:

Only the key's presence is checked, so any value works. TrxTimeOptionMove only applies when wo_begin_dt changes without a wo_end_dt change in the same call; use TrxTimeOptionAdjust otherwise.

Applicable endpoints: JmWorkOrder, MoMediaOrder, XmTransmissionOrder

The value is the Work Order number-sequence. Example with PATCH:

Applicable endpoints: JmWorkOrder, MoMediaOrder, XmTransmissionOrder

Applicable endpoint: JmActual (v11.1)

Actualises selected or all transactions, updating the transaction and order phase (effectively posting the actuals).

Intended to be used with a POST of actual actions; the save argument then performs the actualisation.

Applicable endpoint: TcBatch (v11.1)

Replicates the UI action to 'Post' the batch.

Applicable endpoint: SchResource

Sets the default Group of a resource. The Group must already be assigned to the resource.

Applicable endpoint: BidVersion

Changes the approval state of a Bid, using a number for the approval type.

Where applicable, combine multiple save arguments in one object:

To avoid impacting the user experience or other integrations, use the API efficiently:

1. Keep your field projection tight - fields (GET) is required anyway, so list only the columns you actually use; on POST /query use resultColumns. See .

The REST API uses standard HTTP methods to distinguish the type of operation.

Key field sub-sections

Each payload contains a nested sub-section of key fields, used to look records up by their key. This sub-section is identified by the primary key field name, and always contains the primary key field plus the external_key field.

The key sub-section is not used for writing values to the database - values you want to store must live in the root of the payload. As a general rule, if you are creating or updating field values, put those fields in the root of the payload.

There are also sub-sections for related tables with their key fields. Look-ups (via GET query parameters) can only filter sub-tables using the sub-table primary key, not their alternate keys, unless the sub-table field also exists in the root of the payload.

Creating records with key fields

Using POST you have two ways to set the key values of sub-tables. This example creates a JmJob, generating the primary key (with -1) and assigning the Division, Customer, and Job Type sub-table IDs - mirroring the structure a GET returns:

Alternatively, flatten the structure so the field name matches the sub-section name:

When creating records with POST, values for alternate key fields such as external_key must be in the root of the payload, not in the key sub-section (where they are ignored). The same applies to a document-payload PATCH (Content-Type: application/json).

The external_key field exists on all documents and is designed to hold the external system's unique identifier for a record. You can then use it in later look-ups instead of having to know the Xytech primary key value.

Some documents have additional key fields, all held in the same key sub-section - for example Media Assets (lib_master) expose master_no, barcode, external_key, and umid. Any of these can retrieve the record with a GET. Using the barcode alternate key:

Ensure alternate-key uniqueness if you want to retrieve individual records this way. If a key value can contain a / or other special character, use the /where/ route - see .

When creating records with POST, set the primary key value to -1 to generate it. When creating multiple sub-table records in one call that each need a generated value, decrement for each: -1, -2, -3, . . Reusing -1 refers to the same generated value again, which is useful when the same new ID must be populated elsewhere in the payload.

Prior to v11.3 there is one exception: JmWorkOrder, whose primary key is wo_no + wo_seq; to generate wo_no_seq use a "+1" value:

Some fields are mandatory (defined in the OpenAPI specification). The ID of the created record is returned in the response payload.

Date-time values follow ISO-8601: YYYY-MM-DDThh:mm:ss.sTZD.

Times are stored in the Xytech database as UTC (the exception is the legacy option where the Master Time Zone is not UTC). The recommendation is to work in UTC, or in local times using the time-zone header.

POST / PUT / PATCH - supply times as UTC:

or with a time-zone offset:

or supply local times and name the zone with a header - any DST offset is calculated automatically when the UTC value is stored (this overrides any offset in the value):

GET / responses - times are returned with an offset attribute, e.g. 2025-02-20T10:00:00+00:00 (the offset is determined by the app-server time zone, normally UTC; time plus offset equals the UTC time).

Operator names are spelled differently in the two verbs, and the spellings are not interchangeable. In a POST /query body, a condition's op takes an unprefixed name - gte, in, contains. The GET query parameter requires the $-prefixed form - $gte, $in. Sending an unprefixed operator on GET, or an unrecognised operator on either verb, is rejected with a 400 listing the valid names.

The same condition, in each verb:

contains has no GET operator of its own - put the wildcards in the value instead. { "field": "contact", "op": "contains", "value": "Lee" } on POST is equivalent to { "contact": "%Lee%" } on GET.

$likeAnd and $or are GET-only; they have no POST equivalent. In a POST body, OR logic is expressed with combiningOperator on a group - see .

Every column type can be filtered, including decimal and currency columns. The restriction is on how the value is written in JSON, not on what the column holds.

A quoted decimal is still compared numerically, not as text.

Two consequences worth knowing:

• The type check is not applied uniformly. in, notin and range validate only that a value is present, not its type. An unquoted 10.5 is refused by eq but passed through by in, and what happens next depends on the column - fine on a decimal column, a database conversion error on an integer one. Quoting sidesteps the difference.

Comparison operators work on text columns too, comparing alphabetically - contact gte "M" is valid.

• Multiple keys in one object are combined with AND:

• Use $or for alternatives:

• In a POST body, use nested filter groups with combiningOperator (and

Conditions naming the same field are combined. Combinations that cannot be represented are rejected rather than approximated:

The same field may appear in different OR branches without restriction. These rules apply within a single AND scope.

Two rules that regularly surprise callers:

1. Only gte, lte, range and isnull work on a date column. eq, in and contains are rejected with "Date parameters must use range syntax".

A document defines two column sets: the columns it can return and the columns it can be filtered by. They overlap heavily but are not the same, and the filterable set is the smaller one.

A column that exists in the table - and even appears in resultColumns - may still be refused as a filter. unit_increment on the Billing Code list can be returned but not filtered; the amount columns on jm_job are not filterable from the job list.

So when a filter is rejected as an undefined parameter, the question is not whether the column exists, but whether that document exposes it as a filter column. There is no API call that lists the filterable set - it comes from the document definition.

A filter is either applied exactly as written, or the request is rejected with a message naming the field. These all return 400:

• an unknown or misspelled operator, including an unprefixed operator on GET

• a condition with no field

• contains given a list instead of a single value

Field selection is required on every v3 GET (see ):

• GET: the fields parameter as a JSON object - fields={"jm_job":["job_no","customer_name"]}.

• POST: the fields array, e.g. [{ "table": "jm_job", "columns": ["job_no", "customer_name"] }]. resultColumns is still accepted as a deprecated alias.

Projecting only the fields you need makes responses smaller and faster.

Every v3 request must carry an Authorization header with a bearer token. There are two ways to obtain that token - the same two methods used across the Xytech REST API:

• Auth-provider OAuth (recommended) - obtain a bearer token from your configured identity provider (Azure AD, Okta, or Auth0) and use it to call the API. This is the standard method for both system-to-system and interactive integrations.

• Xytech token endpoint - exchange a Xytech username and password for a Xytech-issued token via the API's own auth endpoints.

The methods your server accepts are controlled by its REST_AUTH_METHODS configuration.

Your auth provider and the Xytech app server must already be configured (Azure and Okta/Auth0). Two provider flows are supported:

• Client Credentials (system-to-system): you need the Access token URL, Client ID, Client Secret, and Scope.

• SPA / browser sign-in (interactive user sign-in): you need the Authorisation URL, Access token URL, Client ID, Client Secret, and Scope.

The flow is the same in both cases:

1. Obtain a token from your auth provider.

2. Send it as a bearer token on every REST API call until it expires, then obtain a new one.

See the existing Connecting and Authenticating page for provider-specific setup - the v3 API accepts these tokens unchanged.

The API can also issue its own tokens. Exchange a username and password for an access token, a refresh token, and an ID token:

Interim note. The orchestration/auth endpoints have not yet been migrated to v3, so they are served by API v2 and still require the /database/{name}/ segment - unlike v3 data calls, which take no database. This is a short-term arrangement; a future release will bring these endpoints in line with the v3 standard. The token they return works against v3 data endpoints. (If you authenticate with an auth-provider bearer token or Basic auth - Method 1 - you don't need this endpoint at all.)

Response

Send the accessToken as a bearer token on subsequent requests:

When the access token expires, exchange it for a new one. The refresh request requires both the current accessToken and the refreshToken:

The response is the same shape as login (accessToken, refreshToken, idToken).

All are under ./api/v2/database/<your-database>/orchestration/auth:

See for the full catalogue.