Skip to main content

Search Presets

Presets are server-side configurations that pre-fill parts of a search request — such as result.format, result.properties, or a default filter. Instead of repeating the same options on every request, a client references a preset by name and the gateway fills in the rest.

warning

Presets are defined on the server-side and are not part of our public API. If you want to use presets, please contact us to find out if there are any presets available for your use case or if we can create a custom preset for you.

POST 
/api/v1/entities/search
{
    "filter": {
        "type": "filter-link",
        "content": "/types=schema:Event"
    },
    "presets": ["venus:default"]
}
info

Preset values are defaults — any field the client sends directly will always override the preset. If multiple presets are listed, the first one takes precedence over later ones.

Referencing presets​

Add a presets array to the request body. Each element is either a shorthand string or an explicit object — both forms can be mixed.

Shorthand string​

The shorthand format is "presetName:identifier":

{
    "filter": {
        "type": "filter-link",
        "content": "/types=schema:Event"
    },
    "presets": ["venus:default"]
}

Explicit object​

{
    "filter": {
        "type": "filter-link",
        "content": "/types=schema:Event"
    },
    "presets": [{ "preset": "branchly", "identifier": "mrn" }]
}

Examples​

Let the preset supply the filter​

If the preset defines a query, the client can omit filter entirely:

{
    "presets": ["branchly:odenwald"]
}

The gateway uses the preset's query and result configuration to execute the search.

Override a preset value​

The client always wins. Here the preset sets "format": "ai", but the client overrides it:

{
    "filter": {
        "type": "filter-link",
        "content": "/types=schema:Event"
    },
    "result": {
        "format": "json"
    },
    "presets": ["venus:default"]
}

format will be "json" (from the client); properties will come from the preset since the client did not set them.

Multiple presets​

{
    "filter": {
        "type": "filter-link",
        "content": "/types=schema:Event"
    },
    "presets": [
        { "preset": "branchly", "identifier": "mrn" },
        { "preset": "venus", "identifier": "only-entry" }
    ]
}

For any field defined by both presets, the first entry in the array wins.