Examples
On this page
- Get an access token
- List records with query parameters
- List records with a filter operation
- Read one record
- Read a record's activities
- Create a record
- Create an Incident with PowerShell
- Run an action on a record
- Check whether an action is available
- Call a global function
- Add an attachment
- Download an attachment
- A failed call
- Related topics
These examples show complete requests and the responses they return. Replace the placeholders in angle brackets with your own values.
<base> is the root of the API's application. The routes in these examples
answer as <base>/, <base>/V1/, or <base>/V2/ followed by the route; the
HTTP examples use V1/; the PowerShell example uses V2/ to preserve HTML
field values. The token endpoint sits at <base>/token, with no version
segment. A Web API call must use HTTPS: a plain-HTTP request is answered with
505 and "HTTP protocol is not supported."
How to obtain and use a token is covered in Authentication. When the instance uses Windows authentication, no token endpoint exists: calls carry the caller's Windows credentials instead of a token.
Get an access token
With a technician's login and password:
POST <base>/token
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=<login>&password=<password>
With an API application's credentials:
POST <base>/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=<application id>&client_secret=<secret>
The token endpoint also accepts a JSON body with the same members.
{
"access_token": "<token>",
"token_type": "bearer",
"expires_in": <seconds>
}
The token is valid for eight hours. The response carries no
refresh_token, and it is not the response envelope that the other routes
return. A wrong login or password is answered with
{"error": "invalid_grant"}, and an unsupported grant_type with
{"error": "unsupported_grant_type"}. When password authentication is not
allowed for the API, the password grant is refused with "Password
authentication is not allowed. Use the authorized authentication method
instead."
Every following request carries the token in the Authorization header.
List records with query parameters
GET <base>/V1/Incidents?Assignee=John%20Doe&par_fields=ID,Ticket&par_sort_asc=Ticket&par_limit=20
Authorization: Bearer <token>
Assignee=John%20Doe is an equality filter: every query parameter other
than the reserved par_ parameters filters on the field of that name.
Percent-encode spaces, &, =, #, +, and % in a value. Field names
in par_fields, in filters, and in sorts are matched against the field's
name exactly, including case, and never against its caption; an unknown
name fails the request with "Field '<name>' is unknown."
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Fields": [
{ "Name": "ID", "DataType": "<data type>", "Caption": "<caption>" },
{ "Name": "Ticket", "DataType": "<data type>", "Caption": "<caption>" }
],
"Data": [
["<GUID>", "<ticket number>"]
]
}
}
Each row of Data lists the values as strings, in the order of Fields.
Parse each column by its DataType. Without par_limit, the list returns
every row the caller may view.
The rows are only those the caller may view. A technician whose roles give
no view right on the class gets a success envelope with an empty Data, the
same answer as for a filter that matches no record.
List records with a filter operation
Only the POST form can filter with an operation other than equality.
POST <base>/V1/Incidents
Authorization: Bearer <token>
Content-Type: application/json
{
"filters": [
{ "name": "Assignee", "value": "John Doe", "operation": "<>" }
],
"offset": 0,
"limit": 20
}
The accepted operations are =, <>, <, >, <=, and >=, spelled
exactly so. Any other operation fails with "An invalid value was specified
for query parameter 'operation'." A sort member takes entries with
property and direction; without it, the list of a ticket class is sorted
by Ticket. Paging with a positive limit needs a sort order: when the
request gives no sort and the class has no default order, the request is
refused. The response has the same Fields and Data shape as above.
Read one record
GET <base>/V1/Object/<object id>
Authorization: Bearer <token>
<object id> is the record's GUID or the class's own identifier, such as
a ticket number. This route, the activity list, and the attachment routes
find the record through the object index: Software Products and Stock Rooms
are not in it and are reached only through their class list with an ID
filter, and a Vendor Product is found by its GUID only. An id that matches
no record fails with "Object not found.", and a record the caller may not
view fails with "You do not have enough permissions to access this item."
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Items": [
{ "name": "Ticket", "caption": "<caption>", "value": "<ticket number>" },
{ "name": "<field name>", "caption": "<caption>", "value": "<value>" }
]
}
}
Read a record's activities
GET <base>/V1/Activities/<object id>?par_fields=Num,Created_by,Created_Date,Activity
Authorization: Bearer <token>
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Fields": [
{ "Name": "Num", "DataType": "<data type>", "Caption": "<caption>" },
{ "Name": "Created_by", "DataType": "<data type>", "Caption": "<caption>" },
{ "Name": "Created_Date", "DataType": "<data type>", "Caption": "<caption>" },
{ "Name": "Activity", "DataType": "<data type>", "Caption": "<caption>" }
],
"Data": [
["<number>", "<created by>", "<date>", "<activity text>"]
]
}
}
Without a sort, activities are ordered by Num. No route creates an
activity; an activity is written as part of an action, as shown in
Run an action on a record.
Create a record
POST <base>/V1/
Authorization: Bearer <token>
Content-Type: application/json
{
"ActionId": "<create action GUID, event id, or name>",
"Fields": {
"<field name or caption>": "<value>"
}
}
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Succeed": true,
"ObjectID": "<new object GUID>",
"ObjectOID": "<new object OID>",
"MessageList": []
}
}
The public routes cannot list a class's actions; where to find a create
action's id is covered in
Create Records and Run Actions. A body without Fields
fails as an invalid body. Fields you leave out are filled from the action
form's defaults; a field that is mandatory on the form, or required by the
table, and is left empty fails the request, naming the field's caption.
ObjectID and ObjectOID are the only way to learn the new record's key.
The response does not return the record itself; read it back to see its new
state. A task action sent to this route fails with "Cannot process the
request. Requested action <event id> is of unexpected type."
Create an Incident with PowerShell
This script signs in with a technician account, runs an Incident create action, checks the API result, and returns the new Incident's identifiers. It uses token authentication with a user name and password. For Windows authentication or single sign-on, see Authentication.
Before you run it:
- Password authentication must be enabled for the API and your account.
- Choose an Incident create action available to your technician account. Find its GUID, event ID, or name in the Settings App, as described in Create Records and Run Actions.
- Supply field names and string values accepted by that action, including all its required fields. For reference fields, use an existing record's identifier or name; for classification fields, use the configured display value. Required fields depend on your workflow.
In a new database created with the Default Workflow, Incident create actions include API Incident Creation. An upgraded or customized database may have different actions; see Incident create actions in a new database.
Save this script as New-AlloyIncident.ps1:
param(
[Parameter(Mandatory)]
[uri]$ApiUrl,
[Parameter(Mandatory)]
[string]$ActionId,
[Parameter(Mandatory)]
[hashtable]$Fields
)
$ErrorActionPreference = 'Stop'
if ($ApiUrl.Scheme -ne 'https') {
throw 'Use the HTTPS address of the Alloy Navigator API.'
}
$baseUrl = $ApiUrl.AbsoluteUri.TrimEnd('/')
$credential = Get-Credential -Message 'Enter your Alloy Navigator technician credentials'
$token = Invoke-RestMethod -Uri "$baseUrl/token" -Method Post `
-ContentType 'application/x-www-form-urlencoded' -Body @{
grant_type = 'password'
username = $credential.UserName
password = $credential.GetNetworkCredential().Password
}
if (-not $token.access_token) {
throw 'The API did not return an access token.'
}
$body = @{
ActionId = $ActionId
Fields = $Fields
} | ConvertTo-Json -Depth 5
$reply = Invoke-RestMethod -Uri "$baseUrl/V2/" -Method Post `
-Headers @{ Authorization = "Bearer $($token.access_token)" } `
-ContentType 'application/json; charset=utf-8' `
-Body ([System.Text.Encoding]::UTF8.GetBytes($body))
if (-not $reply.success -or -not $reply.responseObject.Succeed) {
$messages = @($reply.errorText) + @($reply.responseObject.MessageList)
$details = ($messages | Where-Object { $_ }) -join '; '
if (-not $details) { $details = 'The workflow action did not succeed.' }
throw $details
}
$reply.responseObject | Select-Object ObjectID, ObjectOID
Run it with your API address, Incident create action, and field values. Replace the placeholders and adjust the field map to match the action's form:
$fields = @{
Summary = 'Incident created through the API'
Description = '<p>Please investigate this issue.</p>'
Requester = '<existing Person identifier>'
Urgency = '<configured urgency value>'
Impact = '<configured impact value>'
}
.\New-AlloyIncident.ps1 -ApiUrl 'https://navigator.example.com/api' `
-ActionId '<Incident create action GUID, event ID, or name>' -Fields $fields
The token request goes to /token, without a version segment. The create
request goes to /V2/, where HTML values such as Description are stored
as supplied. The script checks both success and responseObject.Succeed:
an HTTP response alone does not establish that the Incident was created.
For actions with AI Control, see
Actions that use AI Control.
Run an action on a record
POST <base>/V1/Object/<object id>/Action/<action id>
Authorization: Bearer <token>
Content-Type: application/json
{
"<field name or caption>": "<value>",
"Activity.Time_Spent": "<value>"
}
<action id> is the action's GUID, event id, or name. An activity field
carries the Activity. prefix. The response has the same shape as for a
create, with the identifiers of the record the action ran on. A create
action sent to this route fails with the same "unexpected type" message.
This route and its .../Check route look the record up among the records of
the action's class, not in the object index. An id that matches no record there
fails with "Object '<id>' is not found or is not a <workflow
object>."
Check whether an action is available
GET <base>/V1/Object/<object id>/Action/<action id>/Check
Authorization: Bearer <token>
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Result": true
}
}
Nothing is written. A failed check that carries messages comes back as a
failure envelope with the last message in errorText and a null
responseObject; "Result": false appears only for a failed check without
messages.
Call a global function
POST <base>/V1/function/<function id>
Authorization: Bearer <token>
Content-Type: application/json
{
"<parameter name>": "<value>"
}
<function id> is the function's GUID or numeric id. An unknown parameter
name fails the call.
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": {
"Succeed": true,
"MessageList": []
}
}
Add an attachment
PUT <base>/V1/Object/<object id>/Attachments
Authorization: Bearer <token>
Content-Type: application/json
{
"FileName": "notes.txt",
"Data": "<base64 content>",
"Description": "<description>"
}
The body is one attachment or an array of them; FileName is required and
the content is a base64 string. A multipart body is rejected. Adding an
attachment needs the rights to view and to edit the record, and is refused
for a record at its class's inactive status, with a message naming the class
and the status.
{
"success": true,
"errorCode": 0,
"errorText": "",
"responseObject": null
}
GET <base>/V1/SystemSettings returns the attachment size limit in
megabytes as AttachmentMaxSizeMB, or 0 when the limit is switched off.
Download an attachment
GET <base>/V1/Object/<object id>/Attachments/<attachment id>/download
Authorization: Bearer <token>
The response is the raw file, not the envelope, with a
Content-Disposition: attachment header and an attachment-file-name
header holding the URL-escaped file name.
A failed call
On a route that answers with the envelope, a call that reaches the route's
action and fails there still returns HTTP 200, with the failure in the
envelope:
{
"success": false,
"errorCode": 101,
"errorText": "<error message>",
"responseObject": null
}
errorCode is 0 on success and 101 on any failure; the reason is in
errorText. Check success, not the HTTP status code. When a workflow
action aborts with messages, errorText holds the last message and
responseObject.MessageList holds them all. An action that aborts without a
message still answers success: true, with only responseObject.Succeed
set to false, so check Succeed as well.
A request refused before it reaches the route's handler does not get the
envelope: a request filter answers 415, 413, or 505, and a request
refused as unauthorized gets the web framework's own unauthorized answer. A
workflow action refused before it runs is not such a request: it comes back
as a failure envelope with a null responseObject.
Related topics
- Authentication - obtaining and using an access token.
- List and Read Objects
- Create Records and Run Actions
- Global Workflow Functions
- Attachments
- Requests and Responses