Base URLs & Versioning Strategy
Configure your endpoints correctly. Aevum Zenth uses path-based versioning with strict backward compatibility guarantees. Select your environment and target version below.
Base URL Configuration
All API requests must be routed through the appropriate environment base URL. Credentials are environment-scoped and non-interchangeable.
| Environment | Base URL | Authentication | Usage |
|---|---|---|---|
| Production | https://api.aevumzenth.com |
Bearer Token / OAuth2 | Live data, commercial workloads |
| Sandbox | https://sandbox.api.aevumzenth.com |
Test Keys | Development, integration testing |
| Staging | https://staging.api.aevumzenth.com |
Internal Service Account | Pre-release validation, UAT |
| Internal Mesh | https://mesh.internal.zenth.io |
mTLS + SPIFFE ID | Cross-division microservices |
Versioning Matrix
Aevum Zenth follows semantic versioning (SemVer) with a 18-month deprecation lifecycle. Major versions indicate breaking changes.
v3 introduces unified resource identifiers, webhook v2 support, streaming responses, and improved pagination. All new features ship exclusively in v3.
GET https://api.aevumzenth.com/v3/divisions/{division_id}/endpoints
Accept: application/json
Authorization: Bearer <prod_key>
v2 remains operational for legacy integrations. No new endpoints will be added. Migration to v3 is strongly recommended before 2027-06-01.
GET https://api.aevumzenth.com/v2/resources/list?cursor=next_page_token
Accept: application/vnd.aevum.v2+json
v1 will cease processing requests after the sunset date. All clients must upgrade. Response formats in v1 used legacy XML/JSON hybrid schemas.
POST https://api.aevumzenth.com/v1/legacy/sync
Content-Type: text/xml
X-Zenth-Key: <legacy_api_key>
Endpoint Construction Rules
Follow these structural conventions when routing requests across the Aevum Zenth network:
- Path Prefix: Always include the version segment:
/v{major}/ - Resource Naming: Use kebab-case plural nouns:
/v3/health-scis/trials - Headers: Set
X-Zenth-Versionas a fallback if path versioning is omitted - Idempotency: Include
Idempotency-Keyfor POST/PUT operations to prevent duplicate processing
# Valid endpoint structure
<BASE_URL>/v3/<division>/<resource>/<id>?<query_params>
# Example
https://api.aevumzenth.com/v3/energy/smart-grid/meters/mtr_8821?fields=status,firmware,location
Deprecation & Migration Policy
Aevum Zenth guarantees 18 months of notice before any major version sunset. The following signals indicate deprecation status:
| Signal | Header / Field | Meaning |
|---|---|---|
| Deprecation Warning | Sunset: Thu, 31 Dec 2026 23:59:59 GMT |
Version enters end-of-life countdown |
| Migration Guide | Link: <url>; rel="deprecation-guide" |
Direct documentation link for upgrading |
| Client Identifier | X-Zenth-Client: your-app/v1.2.0 |
Required for rate-limit tier allocation |