Sage X3 REST API Query URL Builder (Syracuse api1)
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.
Fill in
8124 is a common Syracuse default; use the port of your installation.
List query ($query facet)
GET http://x3web01:8124/api1/x3/erp/SEED/SORDER?representation=SOH.$query&count=20&where=(BPCORD eq 'C001')&orderBy=SOHNUM desc Accept: application/json Authorization: Basic <base64 of apiuser:password> # Encode spaces and quotes in where and orderBy (%20, %27) when the client does not do it for you.
Single record ($details facet)
GET http://x3web01:8124/api1/x3/erp/SEED/SORDER('SO-00012')?representation=SOH.$details
Accept: application/json
Authorization: Basic <base64 of apiuser:password>curl
curl -s -u "apiuser:password" -H "Accept: application/json" \ -G "http://x3web01:8124/api1/x3/erp/SEED/SORDER" \ --data-urlencode "representation=SOH.\$query" \ --data-urlencode "count=20" \ --data-urlencode "where=(BPCORD eq 'C001')" \ --data-urlencode "orderBy=SOHNUM desc"
PowerShell with paging
$pair = 'apiuser:' + $env:X3_PASSWORD
$headers = @{
Authorization = 'Basic ' + [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($pair))
Accept = 'application/json'
}
$base = 'http://x3web01:8124/api1/x3/erp/SEED/SORDER'
$url = $base + '?representation=SOH.$query&count=20' +
'&where=' + [uri]::EscapeDataString("(BPCORD eq 'C001')") +
'&orderBy=' + [uri]::EscapeDataString('SOHNUM desc')
$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 .\SORDER.json -Encoding utf8URL 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.
Get your Sage X3 integration checked
Send us the classes, representations and filters you plan to use and we will check them against your Sage X3 version and endpoint setup.
Optional. The tool and every export work without this. No spam.
How to use it
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.
- 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
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
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
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.
Frequently Asked Questions
Does Sage X3 have a REST API?
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?
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?
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?
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.
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.
Related Tools
Sage X3 SOAP Web Service Request Generator (CAdxWebServiceXmlCC)
Generate ready-to-post SOAP envelopes for the Sage X3 generic web service (CAdxWebServiceXmlCC): run a subprogram, read an object by key, or save an object.
Other ERPsSage X3 Database Tables Reference
Key Sage X3 tables by module with what they store, typical key columns and naming conventions for SQL and reporting.
Other ERPsSage X3 Supervisor and Dictionary Tables Reference (ATABLE, ATABZON, ATABDIV, AUTILIS)
The Sage X3 V11/V12 technical tables behind the dictionary, parameters, local menus, texts, users, batch server and payments, with keys, maintaining function and a SQL tip each.
Other ERPsSYSPRO e.net REST URL Builder (Logon, Query, Transaction Post)
Fill in host, port, operator, company and business objects to get the full SYSPRO e.net REST call sequence (Logon, Query, Post, Logoff) as URLs and a PowerShell script.
More Other ERPs tools
See all- Sage X3 Import Template Worksheet
- Sage X3 Maintenance Checklist and Schedule
- Sage X3 Private AI Layer Blueprint Generator
- Sage X3 AI Assistant Sizing and Value Calculator
- Sage X3 4GL (L4G) Syntax and Functions Reference
- Sage X3 Patch, Syracuse and Version Upgrade Checklist (V11, V12 and Later Releases)
- Sage X3 On-Premises License and Maintenance Cost Calculator
- Infor VISUAL Work Order Status and Structure Reference
- Infor VISUAL Manufacturing Scheduling Checklist
Keep exploring
Free tools
- Sage X3 Maintenance Checklist and ScheduleA tick-box routine maintenance plan for Sage X3: database, batch server, Syracuse, backups, patches, security and testing.
- Sage X3 Private AI Layer Blueprint GeneratorGenerate an architecture plan for adding a private AI assistant to on-prem Sage X3: SQL replica views, Syracuse SData and web services, retrieval, local GPU model, permissions and audit.
- Sage X3 Import Template WorksheetAn editable import tracker for Sage X3: which object, which import template, source file, records loaded, errors and owner, with error rates calculated.
ERP fixes and how-tos
- Sage X3 REST API: Reading Sales Orders Through SyracuseHow to call the Sage X3 REST API through Syracuse: URL pattern, endpoint and representation, authentication, filtering with where, paging, and common 401 and 404 causes.
- Sage X3 AI Integration On-Prem: A Private ArchitectureHow to add a private AI assistant to on-prem Sage X3: SQL read replica, Syracuse SData and web services, retrieval index, local GPU model and audit trail.
- Sage X3 API Documentation: REST (Syracuse), SOAP Web Services and Where to Find DocsSage X3 API options explained: Syracuse REST (SData), SOAP web services and where official documentation lives, plus guidance on choosing and securing access.
AI on your ERP
- AI for Sage X3 in Food and Beverage: Lot Genealogy and Shelf-Life Answers From Your Own DataPrivate AI on Sage X3 for food and beverage: lot genealogy, shelf-life, allergen and batch yield questions answered from live data, on-prem or private cloud.
- AI for Sage X3, Grounded in Your Own Ledgers and Stock DataAdd AI to Sage X3 finance and stock data without exporting it to a public model. On-prem and private-cloud LLMs for Sage X3 in the UK and France.
Integrations
- How to build an MCP server for Sage X3How to build a Model Context Protocol server for Sage X3: read-only tools over SData, auth to Syracuse, stdio versus HTTP, permission scoping and audit logging.
- How to add AI agents to Sage X3How to add AI agents to Sage X3: a tool layer over SData and web services, read-first design, human approval on writes, and on-prem models for MRP and POs.