HTTP GET Request
squid supports HTTP GET requests and returns JSON.
URL
The URL is https://yourinstance/api/x_a46gh_squidx/v1/data/{configName}
where {configName}
is the name of the
configuration you are requesting.
See Predefined Configurations for an overview of all predefined configurations
provided by squid.
(The demo server is proxied and rate limited. In order to keep the URL shorter and more human readable, we have removed
the x_a46gh_squidx/v1/data/
part of the URL in all links to demo.squid46.io. If you're getting HTTP 429s, slow down.)
Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=10
Query Parameter
The configuration on its own is only of limited use. Query parameter allow the caller to request a specific entity, filter results, add relations to the request and further influence the behavior of squid.
Relations
Resolving references and relations is the added value of squid. References are resolved by default. Relations must be explicitly requested.
squid supports three different types of relations:
- 1:n: These would be e.g., parent-child relations where the child has a reference to the parent.
- m:n Tables: Basically any table that connects two other tables by referencing records in both tables in one row.
While ServiceNow defines Many-to-Many tables (
sys_m2m
) and these may be used for m:n relations, but squid will happily resolve relations defined in any m:n table. - CI Relationships (
cmdb_rel_ci
): These are the relations you know from ServiceNow based on the M-to-N tablecmdb_rel_ci
. Technically speaking, CI Relations are the specific m:n tablecmdb_rel_ci
See Predefined Relations for an overview of all predefined relations provided by squid.
relations
Relations are requested as query parameter relations
. squid accepts this parameter in various formats:
relations=rel1,rel2,rel3
relations=rel1&relations=rel2&relations=rel3
relations=rel1,rel2&relations=rel3
Use whatever fits your calling application best.
Relations may be rendered in various ways. Please see Relations for details.
Inline
{
...,
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc",
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z",
"user_groups": [
{
"active": true,
"name": "Infrastructure",
"sys_created_by": "admin",
"sys_created_on": "2021-03-30T18:56:30Z",
"sys_id": "6577e5908f972410960c53ac37bdee66",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2021-03-30T18:56:30Z"
},
{
"active": true,
"description": "CAB approvers",
"name": "CAB Approval",
"sys_created_by": "admin",
"sys_created_on": "2011-09-30T16:30:34Z",
"sys_id": "b85d44954a3623120004689b2d5dd60a",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2011-09-30T16:30:34Z",
"type": [
"itil"
]
}
]
}
],
...
}
Relation Reference
{
...,
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc",
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07", <= sys_id of requested server
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z"
}
],
"relations": {
"5f9b83bfc0a8010e005a2b3212c9dc07": { <= sys_id of requested server
"user_groups": [
{
"sys_id": "6577e5908f972410960c53ac37bdee66", <= sys_id of user group
"sys_class_name": "sys_user_group"
},
{
"sys_id": "b85d44954a3623120004689b2d5dd60a", <= sys_id of user group
"sys_class_name": "sys_user_group"
}
]
}
},
"referenced": {
"6577e5908f972410960c53ac37bdee66": { <= sys_id of user group
"active": true,
"name": "Infrastructure",
"sys_created_by": "admin",
"sys_created_on": "2021-03-30T18:56:30Z",
"sys_id": "6577e5908f972410960c53ac37bdee66",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2021-03-30T18:56:30Z"
},
"b85d44954a3623120004689b2d5dd60a": { <= sys_id of user group
"active": true,
"description": "CAB approvers",
"name": "CAB Approval",
"sys_created_by": "admin",
"sys_created_on": "2011-09-30T16:30:34Z",
"sys_id": "b85d44954a3623120004689b2d5dd60a",
"sys_mod_count": 0,
"sys_updated_by": "admin",
"sys_updated_on": "2011-09-30T16:30:34Z",
"type": [
"itil"
]
}
}
}
{configName}.relations
When rendering inline content you might want to request relations for referenced entities. You can do this by adding a query parameter with the following structure:
configName.relations=rel5,rel6
This tells squid to add the given relations whenever an entity is rendered with a configuration configName
.
As with relations
squid accepts this parameter in various formats:
configName.relations=rel5,rel6,rel7
configName.relations=rel5&relations=rel6&relations=rel7
configName.relations=rel5,rel6&relations=rel7
Use whatever fits your calling application best.
Try it: TODO generate demo entity and create link.
Filters
Most use cases require a specific subset of data. You will seldom want all entities in cmdb_ci_server
. squid allows
you to define query parameter that restrict what data is returned, e.g. only 'all server with modelIf xxx' or all pc
clients updated in the last 14 days.
squid supports the following filters:
encodedQuery
ServiceNow has the concept of 'encodedQueries'.
See ServiceNow: 'Encoded query strings'
for details on how to structure a query.
See ServiceNow: 'Operators available for filters and queries'
for details on available operators for encodedQueries.
Usage in the context of squid
Using encodedQueries in squid is as simple as defining a query parameter encodedQuery
with the encodedQuery as value.
Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_name=dbaix901nyc
{
"metadata": {
"powered_by": "arc46.io",
"git": "squid-0.10.8+24-4af2b54",
"build": "2025-09-12T09:39:40.935Z",
"license_max_entities": "Unlimited",
"license_valid_till": "2050-12-31T23:59:59.000Z",
"requested_by": "arc46_rest_demo",
"request_received": "2025-09-14T15:39:25.730Z",
"config": "cmdb_ci_server_minimal",
"row_count": 1,
"provided_filter": "base_name=dbaix901nyc", <= encodedQuery as provided by caller
"combined_filter": "base_name=dbaix901nyc" <= resulting encodedQuery used to retrieve data
},
"data": [
{
"asset_tag": "P1000182",
"last_discovered": "2024-07-12T11:21:50Z",
"name": "dbaix901nyc", <= property that matches encodedQuery
"sys_class_name": "cmdb_ci_unix_server",
"sys_id": "5f9b83bfc0a8010e005a2b3212c9dc07",
"sys_mod_count": 12,
"sys_updated_on": "2024-07-17T10:54:43Z"
}
],
...
}
Correctly defining an encodedQuery
squid uses ServiceNow database views to
a) define what data is retrieved and
b) aggregate data of multiple tables in a single JSON.
Every table that is incorporated into a ServiceNow database view must have a
so-called 'Variable prefix'.
By convention all squid database views use 'base'
as the 'Variable prefix' for the base table. (If you want to
use existing database views that do not follow this naming convention, the prefix can be changed in any specific
configuration.)
The prefixes for any additional joined tables are documented in the view. Predefined configurations document the used prefixes in the documentation of the configuration e.g., cmdb_ci_server. Look for 'encodedQuery prefix'.
Field Names
squid removes the database view specific 'Variable prefixes' to present the returned JSON in a more expected format.
Instead of base_sys_id
we return sys_id
.
For ServiceNow to understand a given encodedQuery we have to use the field names defined on the database view that we
are querying, i.e. we have to set conditions on base_sys_id
instead of sys_id
.
A future release will take care of this for you, but we're not quite there yet.
Supported encodedQuery Operators
^
/^OR
(AND/OR)=
,!=
STARTSWITH
ISEMPTY
/ISNOTEMPTY
EMPTYSTRING
IN
/NOT IN
<
/<=
/>=
/>
/BETWEEN
/MORETHAN
/LESSTHAN
SAMEAS
/NSAMEAS
GT_FIELD
/GT_OR_EQUALS_FIELD
/LT_FIELD
/LT_OR_EQAULS_FIELD
RELATIVEGT
/RELATIVELT
VALCHANGES
/CHANGESFROM
/CHANGESTO
DYNAMIC
RLQUERY
/ENDRLQUERY
/SUBQUERY
/ENDSUBQUERY
/JOIN
.
(dot walking)
As always with database queries handle with care. The above operators will cause full table scans if the queried fields are not indexed. squid has no plausible way of checking for the existence of an index. (This is technically possible, but the performance impact on each and every request does not justify that approach.)
Restricted encodedQuery Operators
squid is built to deliver large amounts of data in the most performant way possible without impacting your ServiceNow instance. We therefore prevent encodedQueries from executing operations that have the potential of having a noticeable impact on your instance. Anything that would cause a full table scan with text search, order by operations etc. are by default rejected.
As the performance of database queries always depends on the exact query and the presence of indexes our categorizing of operators into critical (restricted) and non-critical (unrestricted) can only be a best effort.
For you to better understand why we are restricting at all we have included the following anecdotal query durations:
Querying cmdb_ci
with 1.1 million entries. (These are just anecdotal values to give an impression of what we're
talking about. This is NOT a full-fledged performance evaluation. Measurement after 5 warmup queries.)
Field | STARTSWITH | LIKE | ENDSWITH | ORDERBY |
---|---|---|---|---|
name - indexed | 2ms | 1900ms | 1900ms | 48ms |
environment - not indexed | 3500ms | 3500ms | 3500ms | 4700ms |
Restricting encoded queries in this way might sound heavy-handed, but in most use cases the caller of squid is coming from a peripheral system that has little to nothing to do with ServiceNow other than that it needs data. The caller will probably neither know nor notice any negative impact he or she is causing.
We however recognize that there may be valid use cases when these operators are necessary and useful. Configurations
therefore have a property Restrict Encoded Query
that is set to true on all predefined configurations. If this
property is set to true
the following operators are NOT allowed. If you wish to allow these operators, create a
new configuration and set the Restrict Encoded Query
to false
.
%
/ENDSWITH
*
/LIKE
/CONTAINS
!*
/NOT LIKE
javascript
(Anything that requiresjavascript
is restricted)ORDERBY
123TEXTQUERY321
/123TEXTINDEXGROUP321
Unless the requested configuration explicitly allows the use of restricted operators, including any of the restricted operators in an encodedQuery is considered an error condition and the request is rejected.
Try it: https://demo.squid46.io/cmdb_ci_server_minimal?encodedQuery=base_nameLIKEdbaix901nyc
squid reserves the right to expand the above-mentioned list of restricted encoded query operators at any point in time.
ServiceNow may implement new encoded query operators or undocumented operators may come to our attention. If
considered
potentially performance critical, these will be added to the above list at our discretion. Please check the release
notes
for any changes.
Forbidden for security reasons
^NQ
- squid allows configurations to be restricted by the role of the caller and configurations to define view filter that limit the returned data. Both together are a security feature (TODO add link to corresponding documentation).
^NQ
would add a top levelOR
clause to any query allowing a caller to circumvent any set restrictions.
Including a forbidden operator in an encodedQuery is considered an error condition and the request is rejected.
Use restricted encodedQuery operators in view_filter
Configurations have a property called view_filter
. This allows a squid administrator to add an encodedQuery to
the configuration. This encodedQuery is NOT restricted in any way as it is defined by a squid administrator.
Time/Date values
Time/Date values are a difficult topic in a ServiceNow context. ServiceNow will accept nonsense Time/Date values without throwing any kind of error and just make a best effort. This will give you the impression of your query being correct until you notice that your results do not match what you were expecting.
The following is based on trial and error:
encodedQuery=base_sys_updated_on>2024-04-22 23:00:00
will be read as '2024-04-22 23:00:00 UTC' as will
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01Z
encodedQuery=base_sys_updated_on>2024-04-22T23:00:01nonsense
(!)
encodedQuery=base_sys_updated_on>2024-04-22x23:00:01
will be accepted as valid encodedQuery, but ServiceNow will only
interpret the first part, i.e. '2024-04-22' resulting in a query value of '2024-04-22 00:00:00 UTC'.
Please be sure to check any encodedQueries that use Time/Date values.
encodedQuery (HTTP) query parameter format
squid will accept encoded queries as
encodedQuery=yourEncodedQuery
Multiple values are considered an error condition.
sys_id
sys_id
allows retrieval of one or more entities by way of their sysId.
squid accepts this parameter in various formats:
sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951,1072335fc611227500c0267a21be5dc5
sys_id=5f9b83bfc0a8010e005a2b3212c9dc07&sys_id=106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5
sys_id=5f9b83bfc0a8010e005a2b3212c9dc07,106c5c13c61122750194a1e96cfde951&sys_id=1072335fc611227500c0267a21be5dc5
Use whatever fits your calling application best.
updatedBefore / updatedSince / lastDiscoveredBefore / lastDiscoveredSince
updatedBefore
, updatedSince
and lastDiscoveredBefore
, lastDiscoveredSince
are utility query parameters intended
to make querying both values easier.
The expected DateTime format is ISO8601
- "YYYY-MM-DD'T'hh:mm(:ss)?'Z'" or
- "YYYYMMDD'T'hhmm(ss)?'Z'"
The given values are used as to build a filter of
base_sys_updated_on<givenDateTimeValue
forupdatedBefore
base_sys_updated_on>=givenDateTimeValue
forupdatedSince
base_sys_last_discovered<givenDateTimeValue
forlastDiscoveredBefore
base_sys_last_discovered>=givenDateTimeValue
forlastDiscoveredSince
Please notice that these values are inclusive for *since
and exclusive for *before
. (Feel free to give us feedback
on this at support.arc46.io)
The 'Variable prefix' (base_
) will automatically be adjusted for whatever value is defined in the requested
configuration.
squid only accepts and returns ISO8601 Date/Time values (except when encoded in encodedQueries).
Multiple values are considered an error condition.
Try it:
- https://demo.squid46.io/cmdb_ci_server_minimal?updatedBefore=20240501T135655Z
- https://demo.squid46.io/cmdb_ci_server_minimal?updatedSince=20240501T135655Z
- https://demo.squid46.io/cmdb_ci_server_minimal?lastDiscoveredBefore=20240501T135655Z
- https://demo.squid46.io/cmdb_ci_server_minimal?lastDiscoveredSince=20240501T135655Z
filterOnTags (cmdb_key_value
)
Public cloud provider have adopted tags as way of adding metadata to entities (AWS, Azure, GCP) making tags a common and established way of qualifying and accessing configuration items, especially in a dev-ops environment.
ServiceNow supports this concept by way of cmdb_key_value
. This table is populated
by Cloud Discovery,
but may also be populated directly.
ServiceNow uses the term Tags for a slightly different concept. See the link for details on the ServiceNow usage.
squid users are mainly peripheral systems or devOps integrations. These users generally understand 'tag' as described by the major public cloud providers. We try to make life easy for our users.
filterOnTags
allows restricting the returned data to only configuration items (cmdb_key_value
only allows
references to cmdb_ci
) that are referenced by at least one key-value entry in cmdb_key_value
that matches the given
criteria.
Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific key-value entry, is NOT supported.
filterOnTags
does NOT change the returned data, i.e., it does not implicitly add tags to the returned configuration
items. filterOnTags
only filters (nomen-est-omen) data.
See showTags/showTagsInline below for details on how to render tags for configuration items.
filterOnTags
query parameter have the following structure:
filterOnTags=tagClause1^ORtagClause2^ANDtagClause3
Following ServiceNow GlideRecord conventions (but
contrary to what you might be used to from SQL) ^OR
has
precedence over ^AND
! The above filterOnTags
query parameter would result in
(tagClause1 OR tagClause2) AND tagClause3
tagClauses
have the following structure:
tagName
/tagName=*
- filters on having a tag withkey=tagName
ignoringvalue
tagName*
/tagName*=*
- filters on having a tag withkeySTARTSWITHtagName
ignoringvalue
tagName=
- filters on having a tag withkey=tagName
andvalue=null
tagName*=
- filters on having a tag withkeySTARTSWITHtagName
andvalue=null
tagName=value1(,value2,...)
- filters on having a tag withkey=tagName
and avalue
ofvalue1
ORvalue2
tagName*=value1(,value2,...)
- filters on having a tag withkeySTARTSWITHtagName
and avalue
ofvalue1
ORvalue2
Value wildcards (value*
) are NOT supported.
Multiple filterOnTags
query parameter are AND combined.
filterOnTags=tagName1=value1&filterOnTags=tagName2=value2
is equivalent to
filterOnTags=tagName1=value1^ANDtagName2=value2
filterOnTeams (cmdb_rel_team
)
filterOnTeams
allows restricting the returned data to only configuration items (cmdb_rel_team
only allows
references to cmdb_ci
) that are referenced by at least one entry in cmdb_rel_team
that matches the given criteria.
Negative filtering, i.e., returning only configurations items that are NOT referenced by a specific team relation, is NOT supported.
filterOnTeams
does NOT change the returned data, i.e., it does not implicitly add team relations to the returned
configuration items. filterOnTeams
only filters (nomen-est-omen) data.
In order to include Teams relation, request one of the predefined Teams relations.
filterOnTeams
query parameter have the following structure:
filterOnTeams=group_type=group1,group2,group3
group_type
is e.g. managed_by
, approval
group1,group2,group3
are either sysIds of a sys_user_group
or the name of a sys_user_group
.
If a name is given squid will attempt to resolve the name to a sysId. Multiple values are combined as OR condition.
Multiple filterOnTeams
query parameter are AND combined.
filterOnTeams=managed_by=group1,group2
will restrict the query to CIs that are
managed_by
group1
OR group2
.
filterOnTeams=managed_by=group11&filterOnTeams=managed_by=group2
will restrict the query to CIs that are
managed_by
group1
AND group2
.
limit
limit
allows you to limit the amount of entities returned. This is of limited use in a production environment, but
during development you might want to test your queries with just 10 returned entities instead of 10.000.
As the order of the result set is intentionally undefined, which entities are returned may vary from call to call.
Try it: https://demo.squid46.io/cmdb_ci_server_minimal?limit=5
Flags
showBlank
By default, squid will suppress any properties with a null
value.
Some client libraries might rely on a stable JSON structure and not play nice with missing JSON properties.
The query parameter showBlank
will cause squid to render null
JSON properties.
Try it:
- https://demo.squid46.io/cmdb_ci_server_full?limit=1&showBlank
- https://demo.squid46.io/cmdb_ci_server_full?limit=1
showTags
Just as relations, resolving tags requires at least one additional database query. For this reason, tags are only rendered when explicitly requested.
The query parameter showTags
tells squid to retrieve and render tags belonging to a configuration item.
squid can render tags in two forms:
As Object
As object
. This is a standard JSON object with tagName (key) as property name and value as value.
{
...,
"tags": {
// sys_id of the entity
"995390bccd34f010f8778495fd9bf7f7": {
// key : value
"Owner": "SD DC Ops",
"Location": "San Diego",
"Environment": "Production"
},
"6e5314bccd34f010f8778495fd9bf72b": {
"Owner": "SD DC Ops",
"Environment": "Production",
"Location": "San Diego"
},
"9c5314bccd34f010f8778495fd9bf710": {
"Service": "San Diego Wiki",
"Owner": "SD DC Ops",
"Location": "San Diego",
"Environment": "Production"
},
"821b6357c0a8018b244b9609d7010267": {
"Owner": null
}
},
...
}
While object
is easy to read intuitively it is not without problems.
ServiceNow does NOT prevent multiple tags with the same name for a single configuration item. In our example above,
nothing prevents a configuration item from having two or
more
tags with the name Service
. As object
may only have one property with a given name, it is undefined which of the
multiple values is returned.
The structure of the returned object
is unknown beforehand, this may lead to problems when deserializing with some
JSON frameworks.
For these reasons squid additionally offers
As Array
as array
The exact same data as above (with the addition of the extra 'Service' tag for demonstration purposes) renders as shown below.
{
...,
"tags": {
"995390bccd34f010f8778495fd9bf7f7": [
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Location",
"value": "San Diego"
},
{
"name": "Environment",
"value": "Production"
}
],
"6e5314bccd34f010f8778495fd9bf72b": [
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Environment",
"value": "Production"
},
{
"name": "Location",
"value": "San Diego"
}
],
"9c5314bccd34f010f8778495fd9bf710": [
{
// Conflicting name 'Service'
"name": "Service",
"value": "Redundant Tag!"
},
{
// Conflicting name 'Service'
"name": "Service",
"value": "San Diego Wiki"
},
{
"name": "Owner",
"value": "SD DC Ops"
},
{
"name": "Location",
"value": "San Diego"
},
{
"name": "Environment",
"value": "Production"
}
],
"821b6357c0a8018b244b9609d7010267": [
{
"name": "Owner",
"value": null
}
]
},
...
}
This is a much harder read and more verbose, but it is able to render 'conflicting' tagNames and has a predefined structure.
Allowed showTags
query parameter are:
showTags
defaults toshowTags=object
showTags=object
showTags=array
showTagsInline
Tags may also be rendered inline
.
preservePrefix
squid uses ServiceNow database views to aggregate data. These views prefix all properties with
so-called Variable Prefixes, e.g. base_
, lin_
, etc.
Most of the time you do NOT want to see these prefixes. There are however use cases where preserving the prefix is
essential, e.g. when aggregating tables with name collisions. In the case of two joined tables, one with the prefix
base
and the other with the prefix other
with both having the property name
would give us a raw result set with
base_name
and other_name
, with base_name
having priority and other_name
being ignored. The returned json would only contain
one
property name
with the value of base_name
This will usually be part of the configuration (
See Configurations - Preserve Prefix), but is also
available as a query parameter. preservePrefix
has precedence over configuration settings.
Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&preservePrefix
{config}.preservePrefix
TODO
showConfig
The config used to render entities is normally not part of the returned json and of no value to the recipient. During development, it may however help to know which configuration was used to render a specific entity.
Referenced entities may be retrieved based on multiple configs depending on the path by which they are referenced. The returned json will be a merge of all data returned by all relevant configs.
The query parameter showConfig
will add a property squid_config
to each and every returned entity as a string array
of all configs used to render the entity.
{
...,
"data": [
{
...,
"squid_config": [
"cmdb_ci_server"
],
...
}
],
"relations": {},
"referenced": {
"067018092b2692103c92f65ac891bf66": {
...
"squid_config": [
"core_company"
],
...
}
}
}
Try it: https://demo.squid46.io/cmdb_ci_server?limit=1&showConfig
lenient
We strongly suggest you use this query parameter ONLY during development.
Use in production can lead to unnoticed missing data!
squid may encounter two different types of errors while processing a request.
- configuration errors: these are errors when configurations reference non-existent target configs etc. (We might do a deep dive on why we don't validate when a configuration is created, but for now please take our word for it that this is the only realistically workable approach.)
- query errors: these are errors when the query itself has errors, e.g., requesting a non-existent relation.
squid now has two options:
- crash hard and early. This is usually the safest option, but developers trying to get their queries right won't have much fun with this approach - or
- be 'nice' and include warnings in the metadata of the returned JSON pointing developers to what went wrong.
Being nice has the risk of missing data without noticing. Who reads the metadata of a JSON in a technical API? Therefore, squid will, by default, return an error whenever it encounters any type of problem.
Developers tweaking their queries have the option of adding a query parameter lenient
. This tells squid to play 'nice'
and only add warnings to the metadata.
Some types of errors are not recoverable. Requesting a non-existent configuration will result in a 404 error, regardless
of whether lenient
is set or not.