API Reference

List Objects

GET/api/v1/ontologies/{ontologyRid}/objects/{objectType}

Lists the objects for the given Ontology and object type.

This endpoint supports filtering objects. See the Filtering Objects documentation for details.

Note that this endpoint does not guarantee consistency. Changes to the data could result in missing or repeated objects in the response pages.

For Object Storage V1 backed objects, this endpoint returns a maximum of 10,000 objects. After 10,000 objects have been returned and if more objects are available, attempting to load another page will result in an ObjectsExceededLimit error being returned. There is no limit on Object Storage V2 backed objects.

Each page may be smaller or larger than the requested page size. However, it is guaranteed that if there are more results available, at least one result will be present in the response.

Note that null value properties will not be returned.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:ontologies-read.

Path parameters

ontologyRid

string

The unique Resource Identifier (RID) of the Ontology that contains the objects. To look up your Ontology RID, please use the List ontologies endpoint or check the Ontology Manager.

objectType

string

The API name of the object type. To find the API name, use the List object types endpoint or check the Ontology Manager.

Query parameters

pageSize

integer

optional

The desired size of the page to be returned. Defaults to 1,000. See page sizes for details.

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 use it to populate the pageToken field of the next request.

properties

list<SelectedPropertyApiName>

optional

The properties of the object type that should be included in the response. Omit this parameter to get all the properties.

Show child attributes

SelectedPropertyApiName

string

By default, anytime an object is requested, every property belonging to that object is returned. The response can be filtered to only include certain properties using the properties query parameter.

Properties to include can be specified in one of two ways.

A comma delimited list as the value for the properties query parameter properties={property1ApiName},{property2ApiName}
Multiple properties query parameters. properties={property1ApiName}&properties={property2ApiName}

The primary key of the object will always be returned even if it wasn't specified in the properties values.

Unknown properties specified in the properties list will result in a PropertiesNotFound error.

To find the API name for your property, use the Get object type endpoint or check the Ontology Manager.

orderBy

string

optional

A command representing the list of properties to order by. Properties should be delimited by commas and prefixed by p or properties. The format expected format is orderBy=properties.{property}:{sortDirection},properties.{property}:{sortDirection}...

By default, the ordering for a property is ascending, and this can be explicitly specified by appending :asc (for ascending) or :desc (for descending).

Example: use orderBy=properties.lastName:asc to order by a single property, orderBy=properties.lastName,properties.firstName,properties.age:desc to order by multiple properties. You may also use the shorthand p instead of properties such as orderBy=p.lastName:asc.

Response body

ListObjectsResponse

object

Success response.

Hide child attributes

nextPageToken

string

optional

data

list<OntologyObject>

optional

The list of objects in the current page.

Show child attributes

OntologyObject

object

Represents an object in the Ontology.

Show child attributes

properties

map<PropertyApiName, PropertyValue>

optional

A map of the property values of the object.

Show child attributes

PropertyApiName

string

The name of the property in the API. To find the API name for your property, use the Get object type endpoint or check the Ontology Manager.

PropertyValue

any

Represents the value of a property in the following format.

Type	JSON encoding	Example
Array	array	`["alpha", "bravo", "charlie"]`
Attachment	JSON encoded `AttachmentProperty` object	`{"rid":"ri.blobster.main.attachment.2f944bae-5851-4204-8615-920c969a9f2e"}`
Boolean	boolean	`true`
Byte	number	`31`
Date	ISO 8601 extended local date string	`"2021-05-01"`
Decimal	string	`"2.718281828"`
Double	number	`3.14159265`
Float	number	`3.14159265`
GeoPoint	geojson	`{"type":"Point","coordinates":[102.0,0.5]}`
GeoShape	geojson	`{"type":"LineString","coordinates":[[102.0,0.0],[103.0,1.0],[104.0,0.0],[105.0,1.0]]}`
Integer	number	`238940`
Long	string	`"58319870951433"`
Short	number	`8739`
String	string	`"Call me Ishmael"`
Timestamp	ISO 8601 extended offset date-time string in UTC zone	`"2021-01-04T05:00:00Z"`

Note that for backwards compatibility, the Boolean, Byte, Double, Float, Integer, and Short types can also be encoded as JSON strings.

rid

string

The unique resource identifier of an object, useful for interacting with other Foundry APIs.

totalCount

string

The total number of items across all pages.

Examples

Request

Copied!

curl \
	-H "Authorization: Bearer $TOKEN" \
	"https://$HOSTNAME/api/v1/ontologies/ri.ontology.main.ontology.c61d9ab5-2919-4127-a0a1-ac64c0ce6367/objects/employee"

Response

Copied!

{
  "nextPageToken": "v1.QnVpbGQgdGhlIEZ1dHVyZTogaHR0cHM6Ly93d3cucGFsYW50aXIuY29tL2NhcmVlcnMvP2xldmVyLXNvdXJjZSU1YiU1ZD1BUElEb2NzI29wZW4tcG9zaXRpb25z",
  "data": [
    {
      "rid": "ri.phonograph2-objects.main.object.88a6fccb-f333-46d6-a07e-7725c5f18b61",
      "properties": {
        "id": 50030,
        "firstName": "John",
        "lastName": "Doe"
      }
    },
    {
      "rid": "ri.phonograph2-objects.main.object.dcd887d1-c757-4d7a-8619-71e6ec2c25ab",
      "properties": {
        "id": 20090,
        "firstName": "John",
        "lastName": "Haymore"
      }
    }
  ]
}