Using Your API

Once you have created an API, defined your models, set up endpoints, and deployed the API version, you can start making requests. All requests go to a subdomain-based URL and require an API key in the header.

Base URL

Every request targets a specific endpoint within an API version:

https://{subdomain}.searchapi.net/{api-name}/{version}/{endpoint-path}

• {subdomain} — your company subdomain, set during company setup
• {api-name} — the API slug (e.g. catalog)
• {version} — the API version (e.g. v1)
• {endpoint-path} — the path configured for the endpoint (e.g. products)

Example:

https://acme.searchapi.net/catalog/v1/products

Authentication

Every request must include an X-API-KEY header. API keys are scoped per endpoint type — a key may allow GET but not POST. Requests with a missing or invalid key are rejected.

X-API-KEY: your-api-key-here

Response Format

All responses follow a consistent JSON envelope:

{
  "status": "success" | "error" | "warning",
  "type":   "ok" | "created" | "no_content" | "bad_request" | ...,
  "code":   200,
  "message": "...",
  "data":   { ... }
}

The type field gives a machine-readable classification. The data field is present only when there is a payload to return.

Endpoints

GET — List / Search

GET https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}

Returns a paginated list of documents. Supports full-text search, field filtering, and sorting.

Query parameters

Range filters — for numeric and date fields use bracket notation with from / to:

?price[from]=10&price[to]=50
?created_at[from]=2024-01-01&created_at[to]=2024-12-31

Object field filters — pass a JSON object; each key filters the matching sub-field:

?address={"city":"New York"}
?address={"city":"New York","zip":"10001"}

Nested field filters — pass a JSON string or pipe-delimited JSON objects:

?tags=[{"id":1}]
?tags={"id":1}|{"id":5}

GET — Fetch by ID

GET https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}/{id}

Returns a single document by its primary key. Returns 404 if not found.

POST — Create Document

POST https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}
Content-Type: application/json

Creates a new document. The request body must be a JSON object. Required fields must be present and non-empty. Returns 201 Created with the created document, or 409 Conflict if a document with the same primary key already exists.

Relational fields (object / nested)

For fields that reference another model, send an object containing only the primary key. The API looks up the related document and embeds it automatically — including all configured visible fields.

Date field formats

PUT — Full Update

PUT https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}/{id}
Content-Type: application/json

Replaces an existing document. The request body must be a JSON object. Required fields must be present. Returns 201 with the updated document, or 404 if the document does not exist.

Update confirmation for relational fields

If the record is referenced by other models and the update touches a field that is embedded in those models, the API requires explicit confirmation before applying the change.

{
  "status": "warning",
  "type": "confirmation_required",
  "code": 409,
  "message": "Update requires confirmation because this record is referenced by existing models.",
  "meta": {
    "update_confirmation_token": "abc123...",
    "impact": [
      { "modelName": "products", "count": 42 }
    ]
  }
}

{
  "id": 5,
  "name": "Sports",
  "slug": "sports",
  "update_confirmation_token": "abc123..."
}

PATCH — Partial Update

PATCH https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}/{id}
Content-Type: application/json

Updates only the fields included in the request body. The request body must be a JSON object. Fields omitted from the body are left unchanged. Returns 201 with the updated document, or 404 if the document does not exist.

DELETE — Remove Document

DELETE https://{subdomain}.searchapi.net/{api}/{version}/{endpoint-path}/{id}

Deletes a document by its primary key. Returns 204 No Content on success, 404 if not found. If the document is currently referenced by other documents, the delete is rejected with 422 and a list of the models that hold references.

Error Reference