Skill Query API | Skills Base Help Center

The Skill Query API allows programmatic access to execute Skill Query queries. The endpoint is read-only.

Endpoint

/2.0/skillquery

Objects used by this API

Skill Query Request object

Defines the JSON object that must be provided in the HTTP request body when calling the Skill Query API. The object can have these properties:

Name	Data type	Description
query	string	The Skill Query statement to execute

Skill Query Result object

Defines the JSON object that the API will return in the HTTP response body. The object can have these properties:

Name	Data type	Description
status	string	Returns "success" if the query was successful.
data	ResultSet object	A Skill Query Result Set. See below.

ResultSet object

A ResultSet object is returned as the value of the "data" property of the API response.

Name	Data type	Description
columns	array of Column objects	Contains metadata about each of the result table columns.
rows	array of Row objects	Contains each result table row.
totalRows	integer	The number of rows that the query produced. May be less than the number of rows that are returned in the ResultSet, due to pagination.
offset	integer	The pagination offset that applied to this query.
limit	integer	The pagination limit that applied to this query, or null if no limit.
accessRestrictions	boolean	If "true", indicates that some rows or values may have been suppressed due to security restrictions.

Column object

The Column object is a property of the Skill Query "data" object

Name	Data type	Description
path	array	Identifies the property that was requested from the Skill Query data model, relative to the query's root collection. For example, in the query "FIND person skills SHOW person.team, skillLevel", the path for the first column would be ["person", "team"]. This refers to the "team" property of the "person" property of the "person skills" collection.
title	string	The display name for the column.
type	enum	The main data type for values in this column. One of: boolean date decimal integer percentage rating reference richtext shorttext text timestamp tuple
processingFunction	enum	(optional) Indicates whether any special processing applied to the values in this column. One of: none : No special processing delta : Numbers represents the difference between a current value and an earlier value percent-change : Numbers represents the percentage difference between a current value and an earlier value
groupingValue	string	(optional) If there are multiple columns with the same property path, contains the value that disambiguates this column from the others. For example, the query "FIND person skills SHOW person, skillLevel BY skill" would return multiple "skillLevel" columns, one for each skill. The groupingValue will contain the name of the skill.

Row object

The Row object is a property of the Skill Query "data" object

Name	Data type	Description
values	array of Value objects	The values for this result table row

Value object

The "values" property of the Row object contains an array of Value objects. The properties of a Value object depend on the data returned. Therefore it is not guaranteed that all of the following properties will be available.

Name	Data type	Description
type	enum	Data type. One of: boolean date decimal integer percentage rating reference richtext shorttext text timestamp tuple
data	string\|integer\|float\|boolean\|null	The raw value
collectionName	string	The display name of the Skill Query collection that this value came from (for example "person skills")
url	string	The URL of the related entity (if applicable) For example, if this value represents a person's name, the "url" property will contain the URL for viewing that person's dashboard in Skills Base.
id	string\|integer	The unique identifier of the related entity (if applicable) For example, if this value represents a person's name, the "id" property will contain the ID of the person record.
colorHex	string	The color associated with this value (if applicable). For example, if this value is a skill rating, the "colorHex" property will contain the color used when visualizing that rating in Skills Base dashboards.
disposition	enum	Communicates additional semantics for the value (if applicable). One of: delta-value : When the value represents the difference from some starting value (so should be rendered with a +/- prefix). no-value : When no value exists. "data" will be null. redacted-value : When a value exists, but cannot be shown due to restrictions. "data" may be null, or may contain placeholder text such as "Hidden Person" no-answer : When the requested property is unavailable due to restrictions. A value may or may not exist in the underlying storage. "data" will be null.
html	string	A HTML representation of the related entity (if applicable). For example, if the value represents a person's name, the "html" property may contain markup for displaying that person's user avatar.
childValues	array of Value objects	If the value represents a multi-value property, this contains an array of the set of sub-values that make up this value. For example, in the query "FIND skills SHOW name, parentCategories", the second column will contain a list of the skill's category ancestry. In this scenario, "data" will contain a (possibly truncated) display string such as "Category A > Category B", while "childValues" will contain a full Value object describing each category in the set.
suggestedSeparator	string	If the value represents a multi-value property, this contains the recommended string for concatenating the items in the list, when rendering a UI. For example: For the property "person.roles", a comma is a suitable separator: Role A, Role B For the property "team.ancestry", a greater-than symbol is more suitable since it denotes a path-like hierarchy: Root Team > Sub-team

Methods

POST /skillquery

Executes a Skill Query query.

The HTTP request body must be a Skill Query Request object (see above).