# Sage X3 REST API Query URL Builder (Syracuse api1)

> Source: https://netray.co/tools/sage-x3-rest-api-url-builder
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Free Tools

## Short answer

Fill in server, endpoint folder, class, representation and filters to get ready-to-run Sage X3 api1 query and detail URLs with curl and PowerShell examples.

## Category

other-erp

## Erp

Sage X3

## Audience

- Sage X3 developer
- Integration developer

## Tool

**Kind:** template

**Output:** code

**Language:** http

**Fields:**

#### Syracuse server

**Key:** host

**Type:** text

**Default:** x3web01

#### Syracuse port

**Key:** port

**Type:** text

**Default:** 8124

**Help:** 8124 is a common Syracuse default; use the port of your installation.

#### Scheme

**Key:** scheme

**Type:** select

**Options:**

- http
- https

**Default:** http

#### Endpoint (X3 folder endpoint name)

**Key:** endpoint_folder

**Type:** text

**Default:** SEED

#### Class

**Key:** class_name

**Type:** text

**Default:** SORDER

#### Representation

**Key:** representation

**Type:** text

**Default:** SOH

#### Where condition

**Key:** where_clause

**Type:** text

**Default:** BPCORD eq 'C001'

#### Order by

**Key:** order_by

**Type:** text

**Default:** SOHNUM desc

#### Count (page size)

**Key:** count

**Type:** number

**Default:** 20

#### Key for details

**Key:** key

**Type:** text

**Default:** SO-00012

#### User

**Key:** user

**Type:** text

**Default:** apiuser

**Blocks:**

#### List query ($query facet)

**Body:** GET {{scheme}}://{{host}}:{{port}}/api1/x3/erp/{{endpoint_folder}}/{{class_name}}?representation={{representation}}.$query&count={{count}}&where=({{where_clause}})&orderBy={{order_by}}
Accept: application/json
Authorization: Basic <base64 of {{user}}:password>

# Encode spaces and quotes in where and orderBy (%20, %27) when the client does not do it for you.

#### Single record ($details facet)

**Body:** GET {{scheme}}://{{host}}:{{port}}/api1/x3/erp/{{endpoint_folder}}/{{class_name}}('{{key}}')?representation={{representation}}.$details
Accept: application/json
Authorization: Basic <base64 of {{user}}:password>

#### curl

**Body:** curl -s -u "{{user}}:password" -H "Accept: application/json" \
  -G "{{scheme}}://{{host}}:{{port}}/api1/x3/erp/{{endpoint_folder}}/{{class_name}}" \
  --data-urlencode "representation={{representation}}.\$query" \
  --data-urlencode "count={{count}}" \
  --data-urlencode "where=({{where_clause}})" \
  --data-urlencode "orderBy={{order_by}}"

#### PowerShell with paging

**Body:** $pair = '{{user}}:' + $env:X3_PASSWORD
$headers = @{
    Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
    Accept        = 'application/json'
}
$base = '{{scheme}}://{{host}}:{{port}}/api1/x3/erp/{{endpoint_folder}}/{{class_name}}'
$url = $base + '?representation={{representation}}.$query&count={{count}}' +
       '&where=' + [uri]::EscapeDataString("({{where_clause}})") +
       '&orderBy=' + [uri]::EscapeDataString('{{order_by}}')
$all = @()
while ($url) {
    $page = Invoke-RestMethod -Method Get -Uri $url -Headers $headers
    $all += $page.'$resources'
    $url = $null
    if ($page.'$links' -and $page.'$links'.'$next') { $url = $page.'$links'.'$next'.'$url' }
}
$all | ConvertTo-Json -Depth 6 | Out-File .\{{class_name}}.json -Encoding utf8

**Notes:** URL structure (api1, representation=REP.$facet, where, orderBy, count) follows the Sage X3 V12 help page 'Api requests'; the help writes the application and contract segment generically, and on standard installs it is x3/erp. Verify on your system: the endpoint name in Syracuse Administration > Endpoints, that the class and representation exist and are enabled (Development > Classes and Representations), the authentication method your Syracuse server accepts (basic or OAuth2 connected apps), and the paging links returned in your JSON response.

## Content

**Intro:** This builder writes Sage X3 V11/V12 REST URLs for the Syracuse api1 interface: a list query with where, orderBy and count, and a single-record details call, with curl and a PowerShell script that follows paging. It targets on-premises Sage X3 with your own Syracuse server.

**Sections:**

#### How to use it

**Body:** Enter the Syracuse host and port, the endpoint name of your folder, the class and representation, and a filter. Paste the list URL into a browser where you are logged into Sage X3 to check it returns JSON before scripting it. Then move to curl or PowerShell with a dedicated API user. Keep the page size modest (20 to 100) and follow the paging links rather than asking for everything in one call.

**Bullets:**

- The $query facet returns a list and $details one record.
- String values in where go in single quotes.
- Store the password in an environment variable, not in the script.

#### Where this lives in Sage X3

**Body:** The URL is made of the Syracuse server and port, api1, the application and contract (x3/erp for Sage X3 classes), the endpoint (the folder as named in Administration > Endpoints), and the class. Classes and representations are defined under Development > Classes and Representations; the defaults here use class SORDER with representation SOH, so replace them with a class and representation that exist in your folder. The representation decides which properties come back and the facet decides the shape. The user must have access to the endpoint and to the function behind the class.

#### Worked example

**Body:** For endpoint SEED on x3web01:8124, the list of orders for customer C001, newest first, 20 per page, is GET http://x3web01:8124/api1/x3/erp/SEED/SORDER?representation=SOH.$query&count=20&where=(BPCORD eq 'C001')&orderBy=SOHNUM desc. The JSON carries the records in $resources. To fetch order SO-00012 with its lines, call SORDER('SO-00012') with representation=SOH.$details. If a property name in where is wrong, the server returns an error naming it, so check the representation's property names.

#### Version differences and gotchas

**Body:** Older V7-era examples often use the sdata path in place of api1; sdata is the path the interactive web client uses, so build integrations on api1 or SOAP web services. Property names in a representation can differ from database column names. A 401 means authentication, a 404 usually a wrong endpoint or class name, and an empty list often a where clause on a property that is not in the representation. Test with the same user the integration will use.

**Cta:** If you want people to ask Sage X3 questions in plain English through these same APIs, on your own infrastructure, we can set that up.

**Faq:**

#### Does Sage X3 have a REST API?

**Answer:** Yes. Sage X3 V7 and later expose classes through Syracuse at /api1/x3/erp/{endpoint}/{class} with a representation and facet, for example representation=SOH.$query for a list and SOH.$details for one record. Parameters such as where, orderBy and count shape the result. SOAP web services remain available for publications.

#### How do I filter a Sage X3 REST query?

**Answer:** Add where=(condition) using the api1 syntax, for example where=(BPCORD eq 'C001'). Combine conditions with and/or, quote strings with single quotes and URL-encode spaces. Use orderBy=FIELD desc for sorting and count to set the page size.

#### What port does the Sage X3 REST API use?

**Answer:** The API is served by the Syracuse web server, so it uses the Syracuse port. 8124 is a common default, but installations differ and many run behind HTTPS on another port or a reverse proxy. Use the same host and port you use to open Sage X3 in a browser.

#### Should I use the Sage X3 REST API or SOAP web services?

**Answer:** Use REST api1 to read classes and representations already defined in the folder, especially for lists with filters. Use SOAP web services when you need to run a published subprogram or work with a classic object publication. Both run with an authenticated user, so give integrations their own user and rights.

## Search terms

sage x3 rest api, sage x3 rest api query, sage x3 api rest, sage x3 api documentation, sage x3 api, sage x3 api integration, sage x3 api1, syracuse rest api

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json