API Overview
On this page
The Alloy Navigator API is a web interface that any HTTP client can call.
The routes that read data, run workflow actions and functions, and handle
attachments must be called over HTTPS. Responses use JSON unless the
request's Accept header asks for XML; attachment downloads return the file
content. Reading data runs queries over
database views, and objects are created and changed only by running workflow
actions.
The base URL
Every route of the API hangs off one base URL: the root of the API's IIS
application. An API published in a virtual directory named api on the
default HTTPS binding has the base URL https://<host>/api/. The routes that
read data, run workflow actions and functions, and handle attachments are each
reached as <base>/<route>, <base>/V1/<route>, or <base>/V2/<route>; see
Versions.
When the instance does not use Windows authentication, the two token
endpoints, token and externalToken, sit directly at the base URL and take
no version segment. When the instance uses Windows authentication, neither
token endpoint exists, and a call carries the caller's Windows credentials
instead of a bearer token. See Authentication.
Find the base URL in the Web Configuration tool
- In the Web Configuration window, select the API instance in the tree. Each IIS site that has an HTTP or HTTPS binding is a top-level node, and each application under it is a child node named after its virtual directory.
- On the instance's information page, headed Alloy Navigator API, read the URL: line in the Web category.
The URL: value is a link: selecting it opens the address in the default browser.
Find the base URL in the Admin Center
In the Admin Center, the same URL appears in the URL field on the API instance's General tab.
The default page
The base URL itself, requested without credentials, returns a default page. The page shows the product name and version and the authentication type the instance is configured to use, and it links to the online API user guide. You can use this page to check which version an instance runs without signing in.
HTTPS
Every call to a route that reads data, runs a workflow action or function, or
handles attachments must use HTTPS. A call made over plain HTTP is refused
with status 505 HTTP Version Not Supported and the message "HTTP protocol
is not supported." For the other checks a request must pass, see
Requests and Responses.
Versions
The API has two versions, v1 and v2. A URL that names no version uses
v2. v2 has every route of v1 plus one route of its own,
GET <base>/V2/GetAppConfig?par_app_name=<application name>, which returns
the configuration stored for that application. For how the server selects a
configuration, see
Mobile App Configuration.
Because the
route that lists objects of a class puts the class name in the first path
segment, v1 and v2 are reserved there and never address an object class.
The version changes exactly three behaviors, all of them about HTML field pairs:
- Naming a field in a read. On
v2, a field you list, filter on, or sort by that is the plain-text half of an HTML field pair is redirected to the HTML half. - Reading one object. On
v1, the value of an HTML field is converted to plain text. - Writing an HTML field. A plain-text field name that belongs to an HTML
pair is written to the HTML field. On
v1, the submitted value is HTML-encoded; onv2, it is stored as supplied, sov2accepts HTML.
No direct CRUD
The API has no direct create, update, or delete of an object. Reading data uses queries over database views. An object is created or changed only by running a workflow action:
POST <base>/runs a create action.POST <base>/Object/{objectId}/Action/{actionId}runs a task action against an existing object.
The route decides which kind of action is expected. A task action sent to
POST <base>/, or a create action sent to the action route, fails with
"Cannot process the request. Requested action <event id> is of
unexpected type."
GET <base>/Object/{objectId}/Action/{actionId}/Check evaluates whether an
action is available without running it, and
POST <base>/function/{functionId} runs a global workflow function, with no
object context.
No route deletes an object. Attachments have their own routes on an object: they add attachments, change an attachment's description, and remove an attachment.
Testing tools
No client library, SDK, machine-readable API description, sample scripts, or test tool ships with the API. Any HTTP client can call it.
For worked requests and a PowerShell Incident-creation script, see Examples.
Besides the default page, these routes answer without credentials:
| Route | Returns |
|---|---|
GET <base>/lifecycle/health |
A {version, startTime} object: the product version and a UTC time. The time is recorded when the lifecycle service is first used, not when the process starts. The route also accepts cross-origin requests. |
POST <base>/Ver/GetApiVersion |
The version number as major.minor.build. |
GET <base>/V1/ProductVersion |
The version number as major.minor.build. |
Related topics
- Requests and Responses - headers, response format, errors, and the date and time format.
- Authentication - authenticate a user or an application and get a token.