API Versioning

Versions let you evolve your API without breaking existing integrations.

What is an API Version?

An API version is an independent snapshot of your API's endpoints and their models. Each version gets its own URL path segment (e.g. v1), so consumers can pin to a specific version while you work on the next one. Once a version is deployed it becomes active and its endpoints are locked — changes must be made in a new version. Endpoint data requires a valid API key; without one the request is rejected.

Version List

Navigate to APIs in the sidebar, then open an API to reach its Version List. Each row in the table represents one version and provides:

  • Deploy / Redeploy — publish a draft version or re-publish an already deployed one
  • Version — the version number and a real-time progress bar during deployment
  • Endpoints — a link to the endpoint list for that specific version
  • Swagger 3.0 — create, download, or view the Swagger document (available after deploy)
  • API Keys — assign API keys to the endpoints of this version
Version list screenshot Version list screenshot

Creating a Version

Click Create New Version in the top-right of the Version List page. A modal will open with a pre-filled, read-only version number — the system automatically calculates the next version by incrementing the major number of the highest existing version (e.g. if 2.0 exists, the next version will be 3.0). Click Create to confirm.

A new version can only be created if the previous version has already been deployed. Draft versions that have never been published must be deployed before the next version can be created.

Version Number & Slug

Version numbers follow a major.minor format (e.g. 1.0, 2.0). Each version also has a slug derived from its major number — a v prefix is added — which appears in every endpoint URL:

acme.searchapi.net/acme-api/ v2 /products

Version 1.0 → slug v1  ·  Version 2.0 → slug v2

Deploying a Version

Click the Deploy button on the version row to publish it. The deploy process differs depending on whether a previously published version exists for the same API:

First deploy

When no prior published version exists, the system creates fresh Elasticsearch indexes for each endpoint using the version's model mappings. No data is present in the indexes yet — records can be added via the API endpoints or the Import feature. The version is published immediately once the indexes are created.

Subsequent deploys

When a previously published version already exists, the deploy involves two steps:

  • Index creation — new Elasticsearch indexes are created for the new version using its updated model mappings.
  • Data copy — records from the previous version's indexes are copied into the new indexes asynchronously. The copy respects the new mapping: fields that exist in both versions are transferred as-is; fields added in the new version receive null until updated; fields removed from the new version are not copied.

The copy runs in batches and its progress is tracked per endpoint. Each version row shows a progress bar with a live status message (e.g. "Products copying. Total: 1500 — Completed: 750"). Once all indexes finish copying, the version is automatically published and a "Deploy completed successfully" notification appears.

Deploy progress screenshot Deploy progress screenshot
Already-deployed versions show a Redeploy button instead of Deploy. Before redeploying you can make additional changes to the version — existing endpoints can be edited (except their path, including swapping the assigned model), new endpoints can be added, and API key assignments can be modified. The redeploy will process all pending changes at once: new endpoints get their Elasticsearch indexes created, data is copied from the current published state, and API key assignment changes take effect.

Swagger Documentation

After a version is deployed, the Swagger 3.0 column becomes active. Click the + button to generate the Swagger document for that version. Once created, two additional actions appear:

  • Download — save the Swagger JSON file locally
  • View — open the interactive Swagger UI in the browser

For full details on Swagger documentation, see Swagger Documentation.

API Keys

Click Add API Key on a version row to open the key assignment panel. Select an API key from the dropdown, then toggle access per endpoint using the checkboxes. Use the Apply to all endpoints switch to grant or revoke access in bulk. You can also create a new API key directly from this panel. Click Save to confirm.

API key assignments can be saved or changed at any time — before or after the version is deployed. Changes take effect when the version is redeployed. For more details, see API Keys.

Assigning keys directly from this panel is a convenient alternative to navigating to the API Keys page and back — you can set up access for all endpoints without leaving the Version List, then deploy in one go.