API Reference

The Aevum Zenth API provides programmatic access to operational data across our 400+ subsidiaries. Designed for enterprise integration, it supports real-time telemetry, financial aggregation, logistics tracking, and cross-divisional analytics.

⚡ Note on Access API access requires enterprise approval. Sandbox credentials are available for development. Production keys must be scoped to specific divisions. Contact api-support@aevumzenth.com for tier upgrades.

Base URL & Versioning

All API requests are made over HTTPS to the base endpoint. Versioning is handled via URL path prefix to ensure backward compatibility.

Base URL

https://api.aevumzenth.com/v1/

Responses include version metadata in the X-AZ-API-Version header. Deprecated endpoints return a 410 Gone with migration links.

Rate Limiting

API requests are throttled per key to maintain system stability. Limits reset on a rolling minute basis.

Tier	Requests / min	Burst	Concurrent
Developer	100	20	5
Enterprise	5,000	100	50
Partner	20,000	500	200

Exceeding limits returns 429 Too Many Requests. Include the Retry-After header value in exponential backoff logic.

Authentication

API Keys

Include your API key in the request header. Keys are partitioned by division scope.

Header

X-AZ-Api-Key: az_live_sk_8f9a2c...

OAuth 2.0 (Client Credentials)

For service-to-service authentication, use the token endpoint. Tokens expire in 3600 seconds.

Token Request
curl -X POST https://auth.aevumzenth.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_ID&client_secret=YOUR_SECRET"

Endpoints

GET /divisions

Returns a paginated list of all active operational divisions with metadata, revenue classification, and status flags.

Query Parameters

Name	Type	Description
`status`	string	Filter by `active`, `acquired`, or `deprecated`
`category`	string	Filter by sector: energy, tech, healthcare, etc.
`limit`	integer	Max items per page (default: 50, max: 200)

Response 200
{
  "data": [
    {
      "id": "div_9921a",
      "name": "Aevum Energy & Power",
      "category": "energy",
      "revenue_class": "tier_1",
      "status": "active",
      "regions": ["EMEA", "APAC"]
    }
  ],
  "pagination": {
    "next_cursor": "eyJsYXN0X2lkIjoicGR2Xzk5MjFhIn0=",
    "has_more": true
  }
}

POST /energy/grid/metrics

Submit real-time telemetry from smart grid infrastructure. Data is validated, aggregated, and routed to divisional dashboards.

Request Body (JSON)

Field	Type	Required	Description
`station_id`	string	Yes	Unique grid node identifier
`load_mw`	number	Yes	Current load in megawatts
`frequency_hz`	number	No	Grid frequency (default: 50.0)
`timestamp`	string	Yes	ISO 8601 UTC timestamp

Response 201
{
  "ack_id": "txn_7f3e9b2",
  "status": "ingested",
  "processing_queue": "energy_realtime",
  "estimated_analytics_ready": "2026-03-14T08:02:15Z"
}

GET /finance/holdings

Retrieve aggregated portfolio holdings across Aevum Capital Group. Access requires finance:read scope.

Query Parameters

Name	Type	Description
`tier`	string	Filter by `public`, `private_equity`, or `venture`
`currency`	string	USD (default), EUR, GBP, JPY

Response 200
{
  "portfolio_id": "port_az_global",
  "total_aum_usd": 8420000000,
  "holdings": [
    {
      "ticker": "AZN.EQ",
      "type": "equity",
      "value_usd": 1240000000,
      "allocation_pct": 14.7
    }
  ]
}

SDKs & Libraries

Official client libraries handle authentication, retry logic, and type safety. Community-maintained wrappers are listed in the ecosystem docs.

npm

npm install @aevum-zenth/sdk

pip

pip install aevum-zenth-python

go get github.com/aevumzenth/sdk-go/v1

Full documentation, examples, and changelogs are available on GitHub. Contribute via the partner developer portal.

Error Handling

The API uses conventional HTTP status codes. Detailed error payloads follow a consistent structure.

Error Response
{
  "error": {
    "code": "invalid_scope",
    "message": "Key lacks required division access",
    "request_id": "req_88a21f",
    "docs": "https://docs.aevumzenth.com/errors/invalid_scope"
  }
}

Always log the request_id when contacting support. Rate limit violations and malformed JSON return 429 and 400 respectively.