Versioning & Migration

The Trading Copilot API uses semantic versioning. This page explains how to discover available models, how to track changes, and what to expect when an endpoint or model is deprecated or replaced.

API versioning

All endpoints are prefixed with a major version number — currently /v1/. The major version only increments on breaking changes. Minor and patch releases add new capabilities or fix bugs without altering existing response schemas.

The current API version is always visible in the API Reference header and in the version field of the OpenAPI spec at /openapi.json.

Model registry

Models are the classification engines that power sentiment scoring and topic tagging. Each model has a stable id used as a path parameter in feed and index endpoints. Use the registry endpoints to discover which models are available on your subscription before constructing any data request.

Macro models

curl -X GET "https://copilot-api.permutable.ai/v1/headlines/models/macro" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/headlines/models/macro" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os
import requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/headlines/models/macro",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
resp.raise_for_status()
macro_models = resp.json()["models"]

Returns a list of macro model objects:

→ API Reference

Asset (ticker) models

curl -X GET "https://copilot-api.permutable.ai/v1/headlines/models/ticker" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/headlines/models/ticker" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os
import requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/headlines/models/ticker",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
resp.raise_for_status()
asset_models = resp.json()["models"]

Returns a list of asset model objects with the same id, name, and description fields. The id is used as the model_id parameter in asset headline index endpoints.

→ API Reference

Signals models

curl -X GET "https://copilot-api.permutable.ai/v1/signals/models" \
  -H "x-api-key: $PERMUTABLE_API_KEY"

Invoke-RestMethod `
  -Uri "https://copilot-api.permutable.ai/v1/signals/models" `
  -Headers @{ "x-api-key" = $env:PERMUTABLE_API_KEY }

import os
import requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/signals/models",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
resp.raise_for_status()
signal_models = resp.json()["models"]

Returns a list of signal model objects with the same id, name, and description fields. Use the id as the model_name parameter when calling GET /v1/signals.

→ API Reference

Tracking changes

All additions, changes, and deprecations are recorded in the Changelog. The changelog follows Keep a Changelog conventions and semantic versioning.

How to stay informed:

• Email — deprecation notices and sunset reminders are sent directly to the email address on your account.
• Interactive docs — deprecated endpoints are marked with a red ⛔ DEPRECATED banner in the API Reference and include the removal date and replacement endpoint in the description.
• Changelog — every release is documented at docs.copilot-api.permutable.ai/changelog, with a dedicated entry for each deprecation.

Deprecation and sunset pattern

When an endpoint or model is scheduled for removal, Permutable follows a consistent lifecycle:

The sunset period is at least 90 days from the deprecation announcement. The removal date is always stated explicitly in the deprecation notice, the changelog, and the endpoint banner in the docs.

Current active deprecations: 18 endpoints are scheduled for removal on 2026-05-01. See the Deprecated Endpoints guide for the full list and migration checklist.

Endpoint migration pattern

When an endpoint is replaced, the replacement is designed to be a superset of the deprecated endpoint — it accepts the same core parameters and returns a compatible response schema with additional fields. The steps below apply to every migration:

1. Identify — check the Deprecated Endpoints guide or the ⛔ DEPRECATED banner in the API Reference to find the replacement endpoint.
2. Read the diff — the changelog entry for the deprecation describes any parameter or schema differences between the old and new endpoint.
3. Update your calls — swap the endpoint path and adjust any renamed parameters. In most cases no other changes are required.
4. Test — validate your integration against the replacement endpoint before the removal date.
5. Contact support — if you need migration assistance, reach out via [email protected] before the sunset date.

Model updates and replacement

Models are identified by a stable id. Once a model is deployed its id is permanent and immutable — the model will never change under that id. Any change, however minor, constitutes a new model with a new id.

import os
import requests

resp = requests.get(
    "https://copilot-api.permutable.ai/v1/headlines/models/macro",
    headers={"x-api-key": os.environ["PERMUTABLE_API_KEY"]},
)
resp.raise_for_status()
latest_macro_model_id = resp.json()["models"][-1]["id"]
print(f"Using model: {latest_macro_model_id}")

Next steps

• Deprecated Endpoints — full list of endpoints scheduled for removal and their replacements
• Changelog — complete history of API changes
• API Reference — interactive docs with live deprecation banners