Core Concepts
Versioning & Deprecation
The API uses a single major version in the URL path. Backwards-compatible additions ship without a version bump; breaking changes require a new major version.
Version in the URL
Every endpoint is prefixed with /v1/. The version is part of the URL path, not a header.
bash
https://api.hillwinds.ai/v1/companies
https://api.hillwinds.ai/v1/personnel
https://api.hillwinds.ai/v1/creditsWhat's a breaking change?
| Change | Breaking? | Why |
|---|---|---|
| Adding a new endpoint | No | Existing clients are unaffected. |
| Adding a new field to an existing response | No | Clients ignore unknown fields. |
| Adding a new optional query parameter | No | Existing requests continue to behave the same way. |
| Removing or renaming a field | Yes | Existing clients reading that field will break. |
| Renaming or removing a query parameter | Yes | Existing requests would fail. |
| Changing the type or semantics of a field | Yes | Schema-validating clients will reject the response. |
| Changing default behavior of an existing parameter | Yes | Subtle but breaks idempotency for existing callers. |
| Renaming a flat-mode column | Yes | Flat-mode columns are part of the public contract — see Flat-File Mode. |
Deprecation window
Any breaking change requires a new major version (/v2/). When that happens, /v1/ is supported for at least 6 months after /v2/ ships. During that window, deprecated endpoints continue to work but respond with two informational headers:
http
X-API-Version: 1.0
Sunset: 2027-06-01X-API-Versionreports the version your request was served by.Sunsetis the date after which the deprecated path stops working. ISO date.
What's covered by the contract
The following are part of /v1/'s public contract and won't change without a version bump:
- Endpoint paths and HTTP methods.
- Field names, types, and tier (basic vs advanced) of every documented response field.
- Query parameter names, types, and behavior.
- Error envelope shape (
code,issue,request_id). - Response header names —
X-Org-Credits-Remaining,X-RateLimit-*,X-Request-Id, etc. - Flat-mode column names.
- Status code → error code mapping.
What's not covered
Internal implementation details — query plan, latency, exact ML model behind predictive signals, signal computation cohorts — may change without a version bump as long as documented inputs/outputs stay consistent.
Need a key?
Keys are issued by our team, not a signup form. Book a 25-minute walkthrough and you'll leave with sandbox and live credentials.