API Reference

API v1 Overview

Overview of the public read-only v1 API for metric discovery, metric detail, and agent-facing metric contracts.

The public v1 API is a read-only interface for external consumers that need governed metric context. It is designed for BI tools, AI agents, CI checks, and internal services that need to know which metric definition is canonical and whether it can be trusted.

The v1 API is not a warehouse execution API. It does not run metric queries for you, and it does not replace the BI or semantic-layer system that renders dashboards. It returns the governed context those systems should use.

Base URL

https://app.clarilayer.com/api/v1

All examples in these docs use sample IDs and sample API keys. Replace them with values from your own workspace.

Authentication model

v1 metric reads use API keys in the Authorization header:

Authorization: Bearer cl_0000000000000000000000000000000000000000

Current API keys created through the API-key route default to the Agent Contract scope pair: canonical-metric-api:read and definition:read. Existing legacy keys with metrics:read remain compatible with the v1 read routes.

Read authentication details

Routes covered here

The public read docs cover these routes:

GET /api/v1/metrics lists metrics, searches by q, and supports filters.
GET /api/v1/metrics/{id} returns detail context for one metric.
GET /api/v1/metrics/{id}/contract returns the agent-facing contract envelope.

The list and detail routes request the legacy-compatible metrics:read scope internally. The contract route requests canonical-metric-api:read. The compatibility layer lets current Agent Contract keys and older metrics:read keys continue to read the appropriate v1 surfaces.

Product context

Read API responses as the output of the public product journey. The Metric Registry explains discovery context, Warehouse Validation explains validation evidence, Governance and Release explains lifecycle status, approved versions, and release bundle context, and the Reasoning Trail explains pinned notes and discourse signals.

Use Metric Registry, Warehouse Validation, Governance and Release, and The Reasoning Trail for the product context behind those response fields.

Response envelopes

List responses use a paginated envelope:

{
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 0,
    "totalPages": 0
  },
  "meta": { "apiVersion": "v1" }
}

Detail and contract responses use a single-resource envelope:

{
  "data": {},
  "meta": { "apiVersion": "v1" }
}

Consumers should treat additive fields as normal for v1. Fields may be added to help AI agents and BI systems interpret metric context, but the current read routes remain read-only.

Discovery flow

A typical integration starts with search, then detail, then the contract envelope:

GET https://app.clarilayer.com/api/v1/metrics?q=active%20customer&page=1&pageSize=20
Authorization: Bearer cl_0000000000000000000000000000000000000000

Use the returned id to fetch detail:

GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b
Authorization: Bearer cl_0000000000000000000000000000000000000000

Then fetch the agent contract when the consumer needs the governed business meaning:

GET https://app.clarilayer.com/api/v1/metrics/5e6f7a1b-2c3d-4e5f-8a9b-0c1d2e3f4a5b/contract
Authorization: Bearer cl_0000000000000000000000000000000000000000

Error model

Authentication runs before metric lookup. Missing, malformed, invalid, or revoked API keys return 401. A valid key with insufficient scope returns 403. Rate limits return 429 with a Retry-After header when available.

Metric IDs are UUIDs. Invalid ID shape returns 400. A missing metric or a metric outside the API key's organization returns 404, so callers cannot use the API to discover cross-organization existence.

Database or dependency failures return 500 or a route-specific degraded response where documented. Contract fields that read supporting context are intentionally shape-stable: counts can fall back to 0, arrays can fall back to [], and optional summary fields can return null with explanatory headers.