REST APIs
Overview
The system provides a Representational State Transfer (REST) API to work with key records.
REST provides a consistent URI for access and manipulation of a specific data record. Under REST, a single URI represents a data record, and the HTTP verb controls the manipulation according to the following table:
GET
Returns a collection of items based on a filter
GET /api/json/item?...
POST
Creates a new item
POST /api/json/item
GET
Returns a single item
GET /api/json/item/id/1
PUT
Updates a single item
PUT /api/json/item/id/1
Collections
The Crisisworks REST API returns either returns a single object or a collection of objects, based on its invocation.
Collections contain the following JSON structure:
{
"models": {
"1": { ... }
"2": { ... }
"3": { ... }
"4": { ... }
"5": { ... }
},
"count": 5,
"total": "22608"
}In the collection structure:
modelscontains an array of individual model structures,countcontains the number of returned objects, andtotalcontains the total set (this will be different if you call the API with alimitand/oroffsetparameter to paginate the set).
Records
Use the GET method and supply an id parameter to fetch a single record.
Example:
If the record does not exist or is not accessible, the following is returned.
Working with REST collections
Fetching a collection of records
Fetching a collection of RESTful objects is achieved by calling its base URL without an identifier. e.g.
The {{filter}} is a standard GET parameter list with the following parameters.
Specifying the register
For item collections you must specify the type of register:
Filtering
Filters can be provided using CQL.
Like all GET requests, the values must be URL encoded.
For example, to filter the CQL query
Your filter will look like:
Ordering
Collections can be ordered by a limited number of columns, with the most common being id, dateCreated and dateModified.
Pagination
Optional pagination is controlled via limit and offset.
Each result will return the count in the result, and the total records:
Example: get results 50-55 of recoveryInfrastructure
Searching and filtering records
You can use CQL to search and filter your records.
See our user guide for details
A data dictionary exists for each register, and you will find the link in the UI under the search box.
A full example in CQL for Crisisworks might be this — the following returns active records in event 22 updated in the last 30 days:
To run CQL in the REST API, you must url encode it and use a parameter called cql.
Working with REST Records
Submitting new records
New records can be submitted using POST.
JSON Input follows the same structure as that returned from the GET API.
The JSON response reflects the final values of the record after being saved.
Possible error codes include 40x and 50x status codes. All have a human-readable message, and use http codes so you can follow that spec to know whether it's a temporary or permanent error.
The API will respond with the saved data.
The fields and values are defined in the module guide.
Updating existing records
To update an existing record, use PUT or PATCH.
PUT and PATCH work similarly, where:
PUT expecting a full record, while
PATCH expects a change-set.
Tip: When using PUT, missing data will be treated as if the value is set to null, and this will overwrite existing values at the server.
Possible error codes include 40x and 50x codes, as usual.
The API will respond with the saved data.
Deleting records
Records in Crisisworks cannot be deleted. Instead, set the status to an inactive status.
Consult the relevant module reference guide for more information.
REST Commands
Asset
The asset REST command searches and returns assets in Crisisworks.
To search:
To return a specific record by its ID:
GET Parameters
limit
Number
When paginating, how many records to return
offset
Number
When paginating, which record to start from
id
Integer
Returns a record of a specific ID
fulltext
String
Returns records containing the supplied text, as analysed by the full-text search parser.
soundex
String
Returns records where the title sounds like the supplied string Aliases: name
active
Boolean
Returns only active (or inactive) records based on supplied value
type
String
Returns records matching the given asset type. For a list of asset types, see the asset-type API command.
code
String
Returns records matching the given asset code
isImpacted
Boolean
Returns records that have an active register item record in Crisisworks
latitude
longitude range
Number
Returns assets near the provided geospatial location.
Example
Return 1 matching asset.
Result:
Event
This command fetches available events, and allows updating.
Fetch Individual Event
Example
Search Events
Example
Parameters
limit
Number
When paginating, how many records to return
offset
Number
When paginating, which record to start from
id
Number
Search by ID
fulltext
String
Set fulltext_operator to the desired operator if changing from the default
status
String
Search item
active
Boolean
All active statuses
startDateAfter
Date Time String
startDateBefore
Date Time String
tag
String
Search for events containing this tag
isTemplate
Boolean
isGlobal
Boolean
Example: Fetch the most recent event
Request:
Result:
Update Event
This method is deprecated and will not be supported in 2026
Example: Close an event and update its description
Register Item
A RESTful command to access and manage register items, which are the primary business object within the system.
GET Parameters
limit
Number
When paginating, how many records to return
offset
Number
When paginating, which record to start from
registerId
String
Aliases: type ; Set to the register ID for filtering.
cql
String
Aliases query; Use this for all field-level and full-text querying using the CQL query language.
eventId
String
since
String
Set since_operator to the desired operator if changing from the default
until
String
Set until_operator to the desired operator if changing from the default
isTemplate
String
Filter to include or exclude template items
Example: fetch all active FPN records
Example output of all active FPN items. Note, the first item has an attached asset and shows how the extra fields are returned.
Response
POST|PUT
Creating (POST) and updating (PUT) items uses a similar structure to the GET response, but only sends one item.
To create an item
To update an item:
For example:
Matching assets
When linking an asset to an item, you have three approaches:
set
assetIdto the Crisisworks internal ID for the asset,set
asset_friendlyto a name, and have Crisisworks look up the asset using a its search algorithm, orset
asset_lookupto look up a foreign key for the asset, that will match one of the stored foreign keys in the asset'sextraproperty. For example, you can look up bypropnumorcrefno, if those foreign keys are in your asset dataset. To determine which code to look up, you can specifyasset_codefield.
Example: creating an item with an asset looked up based on a property containing propnum.
Example: creating an item with an asset looked up based on a property by a name search.
Audit Log
This fetches a collection of audit logs, either for a given object (with itemId specified), a given event (with eventId specified) or across the system.
GET Parameters
limit
Number
When paginating, how many records to return
offset
Number
When paginating, which record to start from
id
String
Load a specific audit log ID
eventId
String
Load all audit logs for an event. Warning, this is a large payload and will need pagination.
itemId
String
Load all audit logs for a given register item
Example
Fetch the audit log for item 14968
Result
Media
Media (photos, videos) are uploaded to Crisisworks and then attached to items.
Creating media
To upload a file, use the /api/binary/file endpoint and POST a multipart/form-data payload with name (the friendly filename) and file (the raw binary payload).
The following is a raw HTTP example:
Fortunately common HTTP libraries handle this for us.
Here's the above example in BASH:
And here is the same example in Windows PowerShell:
The result contains a unique file ID:
You can use this id in future item POST and PUT commands to attach the item:
Downloading media
To download a file, use its file ID.
The output will be streamed in binary.
Use your libraries to make this easier. For example, in curl -o allows the destination filename to be specified:
Last updated
Was this helpful?