Endpoints

Endpoints expose a model through a URL path and HTTP method.

What is an Endpoint?

An endpoint binds a model to a specific path and HTTP verb, making your data accessible to consumers. Each endpoint belongs to an API version, so you can evolve your API without breaking existing integrations. After creating an endpoint, assign API keys to it to control who can call it.

Prerequisites

• An API. See Create an API.
• A model. See Models.

Create an endpoint

1. In the sidebar, click APIs.
2. Click Endpoint List.
3. Click Add New Endpoint. A modal form appears.
4. Fill in the fields:
   • Model — select the model this endpoint will expose. Once a model is selected, the path may be auto-filled if the model already has an associated endpoint path. A model already used by another endpoint group in this API version is shown disabled, since each model can only back one endpoint group per version.
   • Path — the URL path segment for this endpoint (see rules below).
   • Method — one or more HTTP methods: GET, POST, PUT, DELETE, PATCH. A separate endpoint is created for each selected method. Selecting GET creates both a list endpoint and its detail endpoint (/{id}) together.
   Add endpoint modal
5. Click Save to create the endpoint(s) and close the modal, or Save and Continue to add another endpoint without closing.

Endpoint list

Endpoints are grouped by path on the API's endpoint list page. Each group header shows an Edit button, which opens a single endpoint editor covering every HTTP method in that group, and a Mappings button showing the group's Elasticsearch mapping JSON.

Expanding an endpoint accordion row shows its model's field table — Name, Type, Required, and Searchable. A lock icon next to the method and path shows whether any API key is assigned to that specific endpoint; use the key icon at the end of the row to open the Set API Keys modal (see API keys below).

A version selector at the top right lets you switch between draft and published versions of the API to compare their endpoints.

Endpoint list

Edit an endpoint

Click a group's Edit (pencil) button on the endpoint list to open its editor. One editor page covers every HTTP method in the group, so the following fields apply to the whole group at once:

• Path — read-only; the path cannot be changed after creation
• Description — optional text shown in Swagger documentation
• Model — the model this endpoint exposes; can be changed on a draft version. A model already used by another endpoint group in this API version is shown disabled.
• Page Size — number of records returned per page; visible only when the group has a GET list endpoint

Endpoint editor

Endpoint methods

The Endpoint Methods panel lists every possible HTTP method as a checkbox, reflecting which ones currently exist for this group. To add or remove methods:

1. Check or uncheck methods. At least one method must always stay checked.
2. Click Save Methods.

Checking GET creates both the list endpoint and its detail endpoint (/{id}) together; unchecking it removes both. Unlike the rest of the editor, this panel stays editable even after the API version is published.

Aggregation

Aggregation is available exclusively on GET endpoints. When enabled, the API response includes an aggregations object alongside the regular results. For each selected field, it returns a buckets array of distinct values and the number of matching records per value (doc_count).

Regular fields

For plain fields the key is the field value as stored:

{
  "aggregations": {
    "category": {
      "buckets": [
        { "key": "Shoes",       "doc_count": 134 },
        { "key": "Clothing",    "doc_count": 98  },
        { "key": "Accessories", "doc_count": 53  }
      ]
    }
  }
}

Nested / object fields

For fields from referenced nested or object models (selected with dot notation, e.g. brand.name), the key is stored internally as value|primaryKey — combining the display value with the primary key of the related record. The aggregation key in the response reflects this format:

{
  "aggregations": {
    "brand_name": {
      "buckets": [
        { "key": "Nike|5",    "doc_count": 142 },
        { "key": "Adidas|3",  "doc_count": 98  },
        { "key": "Puma|8",    "doc_count": 45  }
      ]
    }
  }
}

Note that the dot in the field path (brand.name) is replaced with an underscore in the response key (brand_name). The value|primaryKey format lets your application display the label and use the ID for filtering in a single request.

The Aggregation panel in the endpoint editor lets you select which fields to include. Aggregation settings are saved separately with the Save Aggregation button.

Any field can be aggregated except the primary key and system fields. For a relation, pick one of its fields (for example brand.name); only fields marked Visible In The Related Model are listed, because only those are stored with the record. A text field is counted by its whole value, so it suits short labels such as an author or a brand name; values longer than 256 characters are not counted.

Field boosts

Field boosts control relevance ranking on the GET list endpoint. A boost is a positive weight per field: a match on a field with boost 3 counts three times as much toward a record's score as a match on a field with the default weight (1). Use it to rank, for example, matches on name above matches on description.

The Field Boosts panel in the endpoint editor lists every boostable field with a number input. It is shown only when the group has a GET list endpoint. Boosts weight matches of the q full-text search, which covers Searchable fields only, so only Searchable fields are listed.

• Plain fields of the model that are Searchable can be boosted directly.
• Nested / object fields cannot be boosted themselves; instead, their sub-fields that are marked Visible In The Related Model and Searchable are listed with dot notation (e.g. brand.name) and can be boosted individually.
• The value must be a positive number. Leave the input blank to keep the default weight.

When any boost is set, or a q search is sent, results are ordered by relevance score (highest first, then by primary key) unless the request specifies a sort parameter, which always takes precedence.

Boosts are saved separately with the Save Field Boost button. Unlike most endpoint settings, they stay editable after the API version is published and take effect immediately — no redeploy is needed. Changing the endpoint's model resets its boosts.

API keys

API key assignment happens from the Endpoint List page, not the editor. Each endpoint row shows a lock icon — locked if at least one API key is assigned, open if none is. To assign keys:

1. On the endpoint row, click the key-shaped Set API Keys button. A modal opens.
2. Select which API keys are authorised to call that specific endpoint, or create a new one directly from the modal.
3. Optionally, toggle Assign to entire endpoint group to apply the selected key(s) to every method in the group at once. This is additive: it only adds the selected key(s) to endpoints that don't already have them and never removes an existing assignment from any endpoint in the group.

Set API Keys modal

For more details on managing API keys, see API keys.

Reference

URL structure

Every endpoint URL is composed of four parts:

For example: acme.searchapi.net/acme-api/v1/products

Path rules

The endpoint path follows the same rules as the API path:

• Only lowercase letters (a–z), numbers (0–9), - and _ are allowed
• Must start with a lowercase letter or number
• Cannot consist of only numbers
• An optional leading / is accepted
• Maximum 80 bytes

Locking

Publishing an API version locks most endpoint settings. See the Important note in Edit an endpoint.

Last updated: November 6, 2026