Endpoints¶

API endpoints are auto-generated from dbt model metadata. Each dbt model tagged with production and an api:* tag becomes a REST endpoint. No Python code is needed to add or modify endpoints -- changes to dbt models are automatically reflected in the API after the next manifest refresh. This page explains how routing works: how a model's tags map to a URL path, how categories are derived, and how the granularity and window segments behave.

Base URL¶

All endpoints are served under a versioned base path:

https://api.analytics.gnosis.io/v1

URL Convention¶

Endpoint paths follow a structured contract:

/v1/{category}/{resource}/{granularity}[/{window}]

The trailing window segment appears only when the model has a window:{period} tag and its value differs from the granularity. It distinguishes rolling metric windows (7-day, 30-day, 60-day variants) that share the same resource and granularity.

Path Examples¶

How Endpoints Are Generated¶

The API reads the dbt manifest.json file and discovers all models that meet two conditions:

1. The model has the production tag
2. The model has an api:{resource_name} tag

For each qualifying model, the API builds a route from the model's tags and registers it on the FastAPI router. A model that sets meta.api.exclude_from_api: true is skipped entirely, even when both tags are present. The manifest is refreshed on a configurable interval (default: every 5 minutes), so newly deployed dbt models become API endpoints without restarting the service.

flowchart LR
    A[dbt model] -->|tags + meta.api| B[manifest.json]
    B -->|auto-discovery| C[FastAPI Router]
    C -->|serves| D[REST Endpoint]

Categories¶

The category is the first tag on the dbt model that is:

1. Not a system tag -- production, view, table, incremental, staging, intermediate, daily, weekly, monthly, hourly, latest, in_ranges, last_30d, last_7d, all_time
2. Not a tier tag -- tier0 through tier3
3. Colon-free -- any tag containing : (such as api:*, granularity:*, window:*) is skipped

The matched tag is lowercased and used as both the URL prefix and the grouping header in the Swagger UI. If no tag qualifies, the category falls back to general.

Categories are dynamic -- new categories appear automatically when dbt models use new tag values. The live manifest currently exposes 469 endpoints across 11 categories:

Supported Granularities¶

Granularity defines the time aggregation level of the data. It appears as the URL segment after the resource (followed by the window segment, when one exists) and is set via the granularity:{period} dbt tag. Multiple granularities can exist for the same resource -- each is backed by a separate dbt model.

The granularity value is free-form: any granularity:{value} tag becomes the URL segment, so additional values such as snapshot and rolling_180d also appear in the catalog. Unknown values are simply sorted after the well-known ones in the Swagger UI (see below).

Granularity Ordering in Swagger UI¶

Endpoints in the Swagger UI are sorted deterministically within each resource group:

1. Endpoints without a granularity suffix appear first
2. Then: latest, daily, weekly, monthly, last_7d, last_30d, in_ranges, all_time
3. Unknown granularity values appear last, sorted alphabetically

Multiple Granularities for One Resource¶

A single resource often has multiple granularity endpoints, each backed by a separate dbt model with the same api: tag but different granularity: and tier tags:

GET /v1/consensus/blob_commitments/latest    (tier0 -- public)
GET /v1/consensus/blob_commitments/daily     (tier1 -- partner)
GET /v1/consensus/blob_commitments/last_30d  (tier1 -- partner)
GET /v1/consensus/blob_commitments/all_time  (tier2 -- premium)

A common pattern is to expose /latest at tier0 (free, no key needed) so anyone can check current values, while historical data at /daily or /all_time requires partner or premium access.

HTTP Methods¶

Each endpoint supports one or more HTTP methods as declared in the dbt model's meta.api.methods field:

When both GET and POST are enabled for an endpoint, the POST variant appears as a separate entry in the Swagger UI with a (POST) suffix in its summary.

curl "https://api.analytics.gnosis.io/v1/execution/token_balances/daily?symbol=GNO&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X POST "https://api.analytics.gnosis.io/v1/execution/token_balances/daily" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"symbol": "GNO", "limit": 50}'

See Filtering & Pagination for full details on request formats.

Legacy vs Metadata-Driven Endpoints¶

Endpoints fall into two categories based on whether the dbt model includes a meta.api configuration block:

Tag Reference¶

dbt tags control every aspect of how a model becomes an API endpoint:

Example dbt Model Configuration¶

{{
    config(
        materialized='view',
        tags=[
            'production',       -- Required: marks for API exposure
            'consensus',        -- Category: URL prefix + Swagger group
            'tier1',            -- Access: requires partner key or above
            'api:blob_commitments',    -- Resource: URL segment
            'granularity:daily'        -- Granularity: URL suffix
        ],
        meta={
            "api": {
                "methods": ["GET", "POST"],
                "allow_unfiltered": false,
                "parameters": [
                    {"name": "start_date", "column": "date", "operator": ">=", "type": "date"},
                    {"name": "end_date", "column": "date", "operator": "<=", "type": "date"}
                ],
                "pagination": {"enabled": true, "default_limit": 100, "max_limit": 5000},
                "sort": [{"column": "date", "direction": "DESC"}]
            }
        }
    )
}}

SELECT date, total_blob_commitments AS value
FROM {{ ref('int_consensus_blocks_daily') }}

Result:

• Endpoint: GET /v1/consensus/blob_commitments/daily and POST /v1/consensus/blob_commitments/daily
• Swagger Section: Consensus
• Access: tier1 (partner and above)
• Filters: start_date, end_date
• Pagination: default 100 rows, max 5000
• Sort: date DESC

System Endpoints¶

In addition to auto-generated data endpoints, the API provides built-in system routes:

Endpoint Summary¶

The summary table below is generated from the dbt manifest. For a searchable catalog of every endpoint, use the Metrics Explorer; for a per-category reference with columns and filters, see the Endpoint Catalog.

503 endpoints total. Browse them interactively in the Metrics Explorer or per category in the Endpoint Catalog.

Next Steps¶

• Filtering & Pagination -- Learn how to query endpoints with filters, pagination, and sort.
• Authentication -- Understand the tier system and API key usage.
• Swagger UI -- Explore endpoints interactively in the browser.