Zoomed Image
USA
800 691 9120
UK
01225 704844

How to Use the REST API

xAssets Configuration Guide
How To

How to Use the REST API

This page explains how to get started with the xAssets REST API, from creating an API key to making your first data query and save operation.

Prerequisites

  • An xAssets instance accessible over the network from the calling application.
  • Administrator access to xAssets to create API keys.
  • A tool for making HTTP requests (e.g., Postman, curl, or a programming language with HTTP support).

Step 1: Create an API Key

API keys control who can access the API and what data they can see.

  1. Navigate to Admin > Settings.
  2. Open the API Keys section.
  3. Click New to create a new API key.
  4. Enter a description (e.g., "Integration with HR System").
  5. Set the User Group to control what data this key can access. The key inherits the same permissions as users in that group.
  6. Save the record -- the system generates a Key and Secret.
  7. Copy both values immediately -- the Secret is only shown once.

Warning: Treat the API Secret like a password. Do not store it in source code or share it in emails. Use environment variables or a secrets manager.

Step 2: Authenticate and Get a Bearer Token

Send a POST request to obtain a bearer token:

POST https://your-server/a.aspx
Content-Type: application/x-www-form-urlencoded

apikey=YOUR_API_KEY&apisecret=YOUR_API_SECRET&command=logon

The response includes a bearer token in the Authorization field. Store this token for use in subsequent requests.

Step 3: Query Data

Use the bearer token to retrieve data. For example, to get the XML representation of an asset:

POST https://your-server/a.aspx
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

command=commandprocessor&commandname=AssetXML&id=1001

To run a saved query and get JSON results:

command=commandprocessor&commandname=RunQuery&queryname=All Assets&json=true

JSON responses use a standard structure with columns, rows, and rowCount fields.

Step 4: Save Data

After modifying the XML representation, save it back:

POST https://your-server/a.aspx
Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

command=save&savexml=YOUR_MODIFIED_XML

The response confirms success or returns an error message.

Step 5: Use Special Operations

For business operations beyond simple data saving (disposals, transfers, running transformations), use the SaveSpecial interface:

command=savespecial&commandname=SpecialDBTransformRun&transformname=My Transform

Common API Operations

Task Interface API Method
Get asset data as XML CommandProcessor AssetXML
Run a saved query CommandProcessor RunQuery
Save asset changes Save WebSaveXML
Run a transformation SaveSpecial SpecialDBTransformRun
Get a setting value CommandProcessor GetSpecialOption

Error Handling

API errors return an HTTP 200 status with an error message in the response body. Always check the response for error indicators. Common errors:

Error Solution
Invalid API Key Verify the key and secret. Check the key is not disabled.
Session Expired Call the logon endpoint again for a new token.
Insufficient Permissions Change the user group assigned to the API key or grant the required permissions.
Invalid XML Validate the XML structure and check field names against the data model.

Tips

  • During development, use a broad-permission user group to avoid permission errors, then restrict to minimum-necessary permissions before production.
  • Use Postman for exploring and testing the API before writing production code.
  • Add &json=true to any request to receive JSON output instead of XML.
  • Consider using AMSX transformations instead of direct API calls when the operation can run on a schedule, trigger, or menu item.