# EvoTrail API

Version 1.0 · OpenAPI 3.1.0

EvoTrail is the organization's audit trail, usage and metrics across every
EvoHub product, in one place. This API reads it: search and export the audit
trail, see how much each product is used, and read each product's metrics
through one prefix. Everything here is read-only and free.

**Authentication.** Send an API key as `Authorization: Bearer evohub_…` or
`X-API-Key: evohub_…`. A key works in one organization. See *API keys and
scopes* and *Errors* in these docs.

**Permissions, two layers.** Each operation names the EvoTrail permission it
needs (`x-evohub-permission`): `evotrail:audit:read` for the audit trail,
`evotrail:metrics:read` for usage, overview and metrics. On top of that, each
product's rows or numbers need that product's own permission: an audit row
needs the product's `*:audit:read` (for example `oncall:audit:read`), a
product's usage and metrics need one of its read permissions (for example
`uptime:monitor:read`). Products the key cannot read are left out of the
answer; asking only for those is **403 `FORBIDDEN`**. A refusal is never 401.

A key is always held to its scopes, even one made by an administrator. API
keys never count as owners or administrators, so the per-person views below
are not available to a key.

**Retention is fixed** for every organization: audit events 365 days, activity
events 90 days, IP addresses and user agents 90 days.

**Ranges.** `from` and `to` are a UTC date (`YYYY-MM-DD`, `to` inclusive) or an
RFC 3339 timestamp. By default the last 30 days; at most 366 days.

**Responses.** Success is `{"data": …, "success": true}`. Errors are
`{"error": {"code", "message", "request_id"}, "success": false}`; `request_id`
is sent on 403 and 500 answers. Times are RFC 3339 in UTC.

## Servers

- `https://evohub.io`

## Authentication

- `bearerAuth`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `apiKeyHeader`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Audit trail

Every product's audit and activity events, searched, counted and exported.

- [GET /api/v1/evotrail/audit](https://docs-dev.evohub.io/evotrail/search-audit-trail.md): Search the audit trail
- [GET /api/v1/evotrail/audit/facets](https://docs-dev.evohub.io/evotrail/get-audit-facets.md): Count the audit trail by dimension
- [GET /api/v1/evotrail/audit/export.csv](https://docs-dev.evohub.io/evotrail/export-audit-trail.md): Export the audit trail as CSV
- [GET /api/v1/evotrail/audit/{id}](https://docs-dev.evohub.io/evotrail/get-audit-event.md): Get one audit event

## Usage

How much each product is used, by whom and by which team.

- [GET /api/v1/evotrail/usage](https://docs-dev.evohub.io/evotrail/get-usage.md): Get usage by product
- [GET /api/v1/evotrail/usage/people](https://docs-dev.evohub.io/evotrail/get-usage-by-person.md): Get the most active people
- [GET /api/v1/evotrail/overview](https://docs-dev.evohub.io/evotrail/get-overview.md): Get the overview

## Product metrics

Each product's own analytics, read through EvoTrail.

- [GET /api/v1/evotrail/metrics/oncall/alerts](https://docs-dev.evohub.io/evotrail/get-oncall-alert-metrics.md): On-Call alert analytics
- [GET /api/v1/evotrail/metrics/oncall/incidents](https://docs-dev.evohub.io/evotrail/get-oncall-incident-metrics.md): On-Call incident analytics
- [GET /api/v1/evotrail/metrics/uptime](https://docs-dev.evohub.io/evotrail/get-uptime-metrics.md): Uptime analytics
- [GET /api/v1/evotrail/metrics/status](https://docs-dev.evohub.io/evotrail/get-status-metrics.md): Status analytics across pages
- [GET /api/v1/evotrail/metrics/status/pages/{id}](https://docs-dev.evohub.io/evotrail/get-status-page-metrics.md): One status page's visitor analytics
- [GET /api/v1/evotrail/metrics/status/pages/{id}/hourly](https://docs-dev.evohub.io/evotrail/get-status-page-hourly-metrics.md): One status page's views by the hour
- [GET /api/v1/evotrail/metrics/docs](https://docs-dev.evohub.io/evotrail/get-docs-metrics.md): Docs analytics across sites
- [GET /api/v1/evotrail/metrics/docs/sites/{id}](https://docs-dev.evohub.io/evotrail/get-docs-site-metrics.md): One docs site's analytics
- [GET /api/v1/evotrail/metrics/docs/sites/{id}/search](https://docs-dev.evohub.io/evotrail/get-docs-site-search-metrics.md): One docs site's search analytics
- [GET /api/v1/evotrail/metrics/docs/sites/{id}/ai](https://docs-dev.evohub.io/evotrail/get-docs-site-ai-metrics.md): One docs site's AI analytics
- [GET /api/v1/evotrail/metrics/docs/sites/{id}/gaps](https://docs-dev.evohub.io/evotrail/get-docs-site-gap-metrics.md): One docs site's gap analytics
- [GET /api/v1/evotrail/metrics/changelog](https://docs-dev.evohub.io/evotrail/get-changelog-metrics.md): Changelog analytics across sites
- [GET /api/v1/evotrail/metrics/changelog/sites/{id}](https://docs-dev.evohub.io/evotrail/get-changelog-site-metrics.md): One changelog's analytics
- [GET /api/v1/evotrail/metrics/board](https://docs-dev.evohub.io/evotrail/get-board-metrics.md): Board analytics
- [GET /api/v1/evotrail/metrics/retro](https://docs-dev.evohub.io/evotrail/get-retro-metrics.md): Retro analytics
- [GET /api/v1/evotrail/metrics/retro/stats](https://docs-dev.evohub.io/evotrail/get-retro-stats.md): Retro statistics
- [GET /api/v1/evotrail/metrics/billing](https://docs-dev.evohub.io/evotrail/get-billing-metrics.md): Billing summary
- [GET /api/v1/evotrail/metrics/billing/usage](https://docs-dev.evohub.io/evotrail/get-billing-usage-metrics.md): Billing usage
- [GET /api/v1/evotrail/metrics/billing/credit](https://docs-dev.evohub.io/evotrail/get-billing-credit-metrics.md): Billing credit
- [GET /api/v1/evotrail/metrics/billing/statements](https://docs-dev.evohub.io/evotrail/get-billing-statement-metrics.md): Billing statements

## Settings

EvoTrail's fixed retention.

- [GET /api/v1/evotrail/settings](https://docs-dev.evohub.io/evotrail/get-evotrail-settings.md): Get the retention periods