Versioning

URL path versioning

The API version is part of the URL path. All current endpoints live under /v1/:

https://eapi.askedgar.io/v1/dilution-rating?ticker=DVLT

Every response includes an X-API-Version header confirming which version served the request:

X-API-Version: v1

What counts as a breaking change

We treat the following as breaking changes that require a new API version:

• Removing an endpoint or field from a response
• Renaming a field or changing its data type
• Changing the meaning or behavior of an existing parameter
• Altering the authentication mechanism

These changes will never land in an existing version without notice. They ship in a new version (e.g. /v2/).

What we ship without a new version

The following are non-breaking and may be added to the current version at any time:

• New endpoints
• New optional query parameters on existing endpoints
• New fields in response objects
• Bug fixes that correct incorrect data or behavior
• Performance improvements

How we handle deprecations

When a field, endpoint, or behavior is being retired, we follow a consistent process:

1. Announce — We notify customers via email that a deprecation is coming, with a timeline and migration guidance.
2. Sunset — The deprecated feature continues to work unchanged, but every response from it carries the deprecation headers described below. Documentation is updated to flag the change and name the replacement.
3. Remove — After the sunset date, the feature is removed. Requests to removed endpoints return a clear error explaining what changed.

We won't pull the rug out from under you. Deprecations come with advance notice and enough time to migrate.

Deprecation headers

A deprecated endpoint returns three standard headers on every response — success, error, and cached alike — so you can detect the schedule in code rather than by reading release notes:

Deprecation: @1788998400
Sunset: Thu, 30 Sep 2027 23:59:59 GMT
Link: <https://eapi.askedgar.io/v1/ticker-changes>; rel="successor-version", <https://eapi.askedgar.io/v1/docs>; rel="deprecation"; type="text/html"

• Deprecation (RFC 9745) is the date the deprecation was announced, as a structured-field date: @ followed by Unix seconds.
• Sunset (RFC 8594) is the date after which the endpoint may stop responding, as an HTTP-date. It is omitted while no removal date has been committed.
• Link names the replacement endpoint (rel="successor-version") and the documentation (rel="deprecation").

The two date headers deliberately use different formats; parse each with the matching routine rather than one shared one.

The same information is available as data. GET /endpoints returns deprecated and sunset fields for every endpoint, and the OpenAPI schema marks deprecated operations with deprecated: true and an x-sunset date.

Endpoint deprecations versus version sunsets

Retiring a single endpoint in favour of a replacement, as above, carries a minimum twelve-month overlap during which both work. Retiring an entire API version (for example /v1/ after /v2/ ships) follows the same three steps with the same headers on every /v1/ response, and also carries a minimum twelve-month overlap.

How we notify you

You'll hear from us when:

• A new API version is released
• Endpoints or fields are deprecated
• Breaking changes are planned (with migration timelines)
• Significant new features or endpoints are added

Notifications are sent via email to the account associated with your API Platform account. Make sure your contact details are current.

You can also track all changes, additions, and deprecations on our changelog.

Legacy URL redirects

If you're using the older URL pattern /enterprise/v1/*, those requests are permanently redirected (HTTP 301) to /v1/*. Your client will follow the redirect automatically, but you should update your base URL to avoid the extra hop.

Next steps