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.

URL Structure

Every endpoint URL is composed of four parts:

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

Creating an Endpoint

In the dashboard sidebar, navigate to APIs, click Endpoint List and click Add New Endpoint. A modal form will appear with the following 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.
• Path — the URL path segment for this endpoint (see rules below).
• Verb — one or more HTTP methods: GET, POST, PUT, DELETE, PATCH. A separate endpoint is created for each selected verb.

Click Save to create the endpoint(s) and close the modal, or Save and Continue to add another endpoint without closing.

Add endpoint modal screenshot

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

Endpoint List

Endpoints are grouped by path on the API's endpoint list page. For each group you can view the Mappings (Elasticsearch mapping JSON). Expanding an endpoint accordion row shows its model's field table — Name, Type, Required, and Searchable — as well as an Edit button to open the endpoint editor.

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

Endpoint list screenshot

Editing an Endpoint

Click the Edit (pencil) icon to open the endpoint editor. The following fields are available:

• 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
• Page Size — number of records returned per page; visible only for GET list endpoints (not detail endpoints)

Endpoint editor screenshot

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.

API Keys

The API Keys panel on the endpoint editor lets you assign which API keys are authorised to call this endpoint. You can also create a new API key directly from this panel. Save your selection with the Save API Keys button.

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

Locking

Once an API version is published, all its endpoints are locked. The editor will show a warning: "You can't edit this version. Create a new version to update this endpoint." This applies to all endpoint settings — including aggregation fields. To make any changes, create a new API version and update the endpoints there.