API Reference

Search objects

POST/api/gotham/v1/objects/types/{objectType}/search

Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Search for objects of the given object type. The request body is used to filter objects based on the specified query. The supported queries are:

Query type	Description
`empty`	Apply no filter (i.e., list all objects of type objectType).
`eq`	Filter objects that have the exact value for the provided property
`and`	Filter objects that match all the provided queries
`or`	Filter objects that match at least one of the provided queries
`keyword`	The objects' contents match the specified keyword query
`lt`	Filter objects where the provided property is less than the provided value
`gt`	Filter objects where the provided property is greater than the provided value
`lte`	Filter objects where the provided property is less than or equal to the provided value
`gte`	Filter objects where the provided property is greater than or equal to the provided value
`not`	Filter objects that do not match the provided query
`geoPointWithin`	Filter objects whose intrinsic coordinates are within the provided polygon

For more details about available queries, see search query types.

Path parameters

objectType

string

The type of the requested objects to search for.

Query parameters

preview

boolean

optional

Represents a boolean value that restricts an endpoint to preview mode when set to true.

Request body

SearchObjectsRequest

object

Search request to issue against the RevDB Object Index for finding and returning objects. query is required, and represents the query to execute when searching for objects.

pageSize and pageToken are optional and are used for pagination of large result sets; see the Paging instructions for more information.

If not specified, pageSize defaults to a page size of 100 results; 100 is also the maximum allowed page size.

Specifying an invalid page size results in an InvalidPageSize general error.

Hide children

query

union

Show children

not

object

optional

Returns objects where the query is not satisfied.

Show children

value

union

Show children

not

object

optional

Returns objects where the query is not satisfied.

Show children

value

union

object

optional

Returns objects where at least 1 query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

and

object

optional

Returns objects where every query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

geoPointWithin

object

optional

Returns objects where a point on the object is within the provided polygon coordinates. By default searches for the "intrinsic" geometry on the object if it is a point.

Show children

polygon

list<GeoPoint>

optional

Polygon coordinates representing the geospatial area a geospatial point on the object must be within.

Show children

GeoPoint

object

Show children

longitude

number

latitude

number

elevation

number

optional

object

optional

Returns objects where the specified field is less than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

gte

object

optional

Returns objects where the specified field is greater than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

lte

object

optional

Returns objects where the specified field is less than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

object

optional

Returns objects where the specified field is equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

keyword

object

optional

Returns objects where object contents match the specified keyword query. This query type supports advanced syntax.

The keyword query string is parsed into parts based on operators (AND, OR, etc), and used to analyse content matches.

If no operators are specified between words, a default operator of AND is used for matching contents.

Show children

field

string

optional

The name of the property in the API - also called the Property Type URI.

query

string

Contents match specified keyword query.

object

optional

Returns objects where the specified field is greater than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

empty

object

optional

Returns objects without checking fields (i.e., searches on object type only)

Show children

placeholder

boolean

optional

object

optional

Returns objects where at least 1 query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

Show children

not

object

optional

Returns objects where the query is not satisfied.

Show children

value

union

object

optional

Returns objects where at least 1 query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

and

object

optional

Returns objects where every query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

geoPointWithin

object

optional

Returns objects where a point on the object is within the provided polygon coordinates. By default searches for the "intrinsic" geometry on the object if it is a point.

Show children

polygon

list<GeoPoint>

optional

Polygon coordinates representing the geospatial area a geospatial point on the object must be within.

Show children

GeoPoint

object

Show children

longitude

number

latitude

number

elevation

number

optional

object

optional

Returns objects where the specified field is less than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

gte

object

optional

Returns objects where the specified field is greater than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

lte

object

optional

Returns objects where the specified field is less than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

object

optional

Returns objects where the specified field is equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

keyword

object

optional

Returns objects where object contents match the specified keyword query. This query type supports advanced syntax.

The keyword query string is parsed into parts based on operators (AND, OR, etc), and used to analyse content matches.

If no operators are specified between words, a default operator of AND is used for matching contents.

Show children

field

string

optional

The name of the property in the API - also called the Property Type URI.

query

string

Contents match specified keyword query.

object

optional

Returns objects where the specified field is greater than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

empty

object

optional

Returns objects without checking fields (i.e., searches on object type only)

Show children

placeholder

boolean

optional

and

object

optional

Returns objects where every query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

Show children

not

object

optional

Returns objects where the query is not satisfied.

Show children

value

union

object

optional

Returns objects where at least 1 query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

and

object

optional

Returns objects where every query is satisfied.

Show children

value

list<SearchJsonQuery>

optional

Show children

SearchJsonQuery

union

geoPointWithin

object

optional

Returns objects where a point on the object is within the provided polygon coordinates. By default searches for the "intrinsic" geometry on the object if it is a point.

Show children

polygon

list<GeoPoint>

optional

Polygon coordinates representing the geospatial area a geospatial point on the object must be within.

Show children

GeoPoint

object

Show children

longitude

number

latitude

number

elevation

number

optional

object

optional

Returns objects where the specified field is less than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

gte

object

optional

Returns objects where the specified field is greater than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

lte

object

optional

Returns objects where the specified field is less than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

object

optional

Returns objects where the specified field is equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

keyword

object

optional

Returns objects where object contents match the specified keyword query. This query type supports advanced syntax.

The keyword query string is parsed into parts based on operators (AND, OR, etc), and used to analyse content matches.

If no operators are specified between words, a default operator of AND is used for matching contents.

Show children

field

string

optional

The name of the property in the API - also called the Property Type URI.

query

string

Contents match specified keyword query.

object

optional

Returns objects where the specified field is greater than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

empty

object

optional

Returns objects without checking fields (i.e., searches on object type only)

Show children

placeholder

boolean

optional

geoPointWithin

object

optional

Returns objects where a point on the object is within the provided polygon coordinates. By default searches for the "intrinsic" geometry on the object if it is a point.

Show children

polygon

list<GeoPoint>

optional

Polygon coordinates representing the geospatial area a geospatial point on the object must be within.

Show children

GeoPoint

object

Show children

longitude

number

latitude

number

elevation

number

optional

object

optional

Returns objects where the specified field is less than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

gte

object

optional

Returns objects where the specified field is greater than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

lte

object

optional

Returns objects where the specified field is less than or equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

object

optional

Returns objects where the specified field is equal to a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

keyword

object

optional

Returns objects where object contents match the specified keyword query. This query type supports advanced syntax.

The keyword query string is parsed into parts based on operators (AND, OR, etc), and used to analyse content matches.

If no operators are specified between words, a default operator of AND is used for matching contents.

Show children

field

string

optional

The name of the property in the API - also called the Property Type URI.

query

string

Contents match specified keyword query.

object

optional

Returns objects where the specified field is greater than a value.

Show children

field

string

The name of the property in the API - also called the Property Type URI.

value

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

empty

object

optional

Returns objects without checking fields (i.e., searches on object type only)

Show children

placeholder

boolean

optional

pageSize

integer

optional

The page size to use for the endpoint.

pageToken

string

optional

The page token indicates where to start paging. This should be omitted from the first page's request. To fetch the next page, clients should take the value from the nextPageToken field of the previous response and populate the next request's pageToken field with it.

Response body

SearchObjectsResponse

object

Search Result Payload

Hide children

data

list<GothamOntologyObject>

optional

Show children

GothamOntologyObject

object

Represents an object in the Object Store.

Show children

primaryKey

string

The primary key/unique identifier of an object, useful for interacting with Gotham APIs to load and mutate objects.

title

string

optional

The title of an object, which represents a display-friendly String of what the object represents.

objectType

string

The name of the object in the API - also called the Object Type URI.

properties

map<PropertyApiName, array>

optional

A map of the property values of the object.

Show children

PropertyApiName

string

The name of the property in the API - also called the Property Type URI.

array

list<PropertyValue>

Show children

PropertyValue

any

Represents the value of a property. The following table provides expected representations of scalar data types:

Type	JSON encoding	Example
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Integer	number	`238940`
Long	string	`"58319870951433"`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

intrinsicCoordinates

object

optional

Show children

longitude

number

latitude

number

elevation

number

optional

timeInterval

object

optional

Represents a time interval by its start and end datetime. TimeInterval is generally used when an Object has a meaningful start and/or end datetime, such as an event. For example, a Meeting might have start and end datetimes corresponding to when the meeting began and ended.

Show children

timeStart

string

optional

timeEnd

string

optional

nextPageToken

string

optional

Examples

Request

Copied!

curl -X POST \
	-H "Content-type: application/json" \
	-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/gotham/v1/objects/types/com.palantir.object.person/search?preview=true" \
	-d '{"query":{"type":"and","value":[{"type":"eq","field":"com.palantir.property.name:FIRST_NAME","value":"John"},{"type":"gte","field":"com.palantir.property.age","value":24}]}}'

Response

Copied!

{
  "data": [
    {
      "primaryKey": "ri.gotham.111111-0.object-internal.111111",
      "objectType": "com.palantir.object.person",
      "properties": {
        "com.palantir.property.name": [
          {
            "FIRST_NAME": "John",
            "LAST_NAME": "Smith"
          }
        ],
        "com.palantir.property.age": [
          37
        ]
      }
    }
  ]
}