Search endpoint

The Search endpoint and fields are described below including details of the supported RESTful CRUD verbs. For details of the conventions of the API see the general conventions.

Endpoint path prefix: 

/n/v1/search/

search was introduced in API version V1

Search has not been marked for deprecation

Description

Search endpoint with support for locating collections of different types.

Search is currently under active development and may be subject to breaking changes.
Search items returned by the search backend may not be visible or may not be available after the search snapshot is materialised so items should be loaded based on the search results. To maintain consistent search responses results are created async and a cache of the items listed. Items may be deleted or access removed after the snapshot. The snapshot of the item does not include any sensitive data and the 'name' field is optionally included.

Verbs / methods

This endpoint supports the following CRUD operations in line with our API conventions. See the conventions section for more details.

CREATE HTTP POST

Request payload

Search reference

{
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "order" : "NAME",
  "includeScopes" : [ "ENTITY" ]
}

Response payload

Search reference
Representation of a search and it's results when available

{
  "urn" : "bdef19c7-7084-4dbe-9cf6-db578d72ed7f",
  "url" : "/n/v1/search/bdef19c7-7084-4dbe-9cf6-db578d72ed7f",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "createdTimestamp" : "2025-09-22T10:15:00",
  "updatedTimestamp" : "2025-09-22T10:15:00",
  "status" : "FULL_RESULT",
  "order" : "NAME",
  "items" : [ {
    "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
    "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
    "sortOrder" : 0,
    "type" : "ENTITY"
  } ],
  "includeScopes" : [ "ENTITY" ]
}

Response codes / scenarios

  • CREATE_SUCCESS

    API code CREATE_SUCCESS HTTP status code 201 : When the representation provided was successfully created return HTTP created (201). Note that when other context like authorisation and permissions are satisfied but the representation is invalid or missing required information typically a error representation with details of the missing information may be returned instead with REPRESENTATION_MISSING_REQUIRED_FIELD api error for example

  • INVALID_REPRESENTATION

    API code INVALID_REPRESENTATION HTTP status code 400 : When creating or updating a representation and the provided representation is invalid. May include an error representation with details of the issue

  • REPRESENTATION_MISSING_REQUIRED_FIELD

    API code REPRESENTATION_MISSING_REQUIRED_FIELD HTTP status code 400 : When creating or updating a representation the provided representation was missing a required filed. Typically has a error response representation with details of the missing required field.

READ HTTP GET

Response example

Search
Representation of a search and it's results when available

{
  "urn" : "bdef19c7-7084-4dbe-9cf6-db578d72ed7f",
  "url" : "/n/v1/search/bdef19c7-7084-4dbe-9cf6-db578d72ed7f",
  "owner" : {
    "urn" : "32a90f18-aaa0-4bdc-a63e-4efd2e16c28c",
    "url" : "/n/v1/company/32a90f18-aaa0-4bdc-a63e-4efd2e16c28c"
  },
  "createdTimestamp" : "2025-09-22T10:15:00",
  "updatedTimestamp" : "2025-09-22T10:15:00",
  "status" : "FULL_RESULT",
  "order" : "NAME",
  "items" : [ {
    "urn" : "4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
    "url" : "/n/v1/entity/4fdf15cf-cfa3-4b43-9e92-57dfbbc0366d",
    "sortOrder" : 0,
    "type" : "ENTITY"
  } ],
  "includeScopes" : [ "ENTITY" ]
}

Response codes / scenarios

  • NOT_FOUND

    API code NOT_FOUND HTTP status code 404 : When the request referenced a representation or a concept that was not found including other request context requirements. Note that if a request is missing other concepts including authorisation, permissions or restrictions on the visibility HTTP not found (404) will typically be returned. Note that when creating a representation if the owner or other references can't be resolved the endpoint may return not found.

  • READ_SUCCESS

    API code READ_SUCCESS HTTP status code 200 : On read when the request is successful. The returned representation is given with the relevant 2XX HTTP code without further detail.