Examples

On this page

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.