API Reference

Actaflow API — это REST + gRPC интерфейс к платформе. Полностью совместим с OpenTelemetry Protocol (OTLP), поэтому любые OTLP-клиенты работают из коробки.

Authentication

Все запросы требуют API-ключ. Передавайте его в заголовке x-actaflow-api-key. Ключи создаются в личном кабинете, имеют scope (ingest, query, admin) и TTL.

curl https://api.actaflow.tech/v2/services \
  -H "x-actaflow-api-key: af_live_8a3f9c1e7b2d4c6f9e8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4"

Безопасность ключей. Никогда не публикуйте ключи в публичных репозиториях, frontend-коде или логах. Используйте Kubernetes Secrets, HashiCorp Vault или cloud KMS. В случае компрометации — немедленно ротируйте в личном кабинете.

Base URL & versioning

REST:  https://api.actaflow.tech/v2/...
gRPC:  api.actaflow.tech:443 (TLS, ALPN h2)
OTLP:  ingest.actaflow.tech:4317 (gRPC) / :4318 (HTTP)

Версия указывается в пути (/v2/). Backwards-compatible изменения (добавление полей, новых endpoints) не увеличивают major-версию. Breaking changes — новая major-версия с 12-месячным периодом deprecation.

Ingestion

POST /v2/ingest/metrics

Принимает метрики в OTLP/Prometheus-формате. Батчинг обязателен — до 1000 metric datapoints или 4 MB на запрос.

POST /v2/ingest/metrics HTTP/1.1
Host: api.actaflow.tech
Content-Type: application/json
x-actaflow-api-key: af_live_...

{
  "resource_metrics": [{
    "resource": {
      "attributes": {
        "service.name": "payments-api",
        "service.version": "1.4.2"
      }
    },
    "scope_metrics": [{
      "metrics": [{
        "name": "payments_request_duration_seconds",
        "unit": "s",
        "histogram": {
          "aggregation_temporality": 2,
          "data_points": [{
            "attributes": { "endpoint": "/v1/charge" },
            "start_time_unix_nano": 1736338938000000000,
            "time_unix_nano":         1736338998000000000,
            "count": 1248,
            "sum": 14.83,
            "bucket_counts": [820, 312, 88, 18, 6, 4],
            "explicit_bounds": [0.005, 0.01, 0.025, 0.05, 0.1, 0.25]
          }]
        }
      }]
    }
  }]
}

# Ответ
HTTP/1.1 202 Accepted
{
  "accepted": 1248,
  "rejected": 0,
  "ingest_ms": 3
}

POST /v2/ingest/traces

OTLP-трейсы. Tail-sampling выполняется на стороне ingest-слоя; клиент шлёт все спаны. Рекомендуемый batch — до 100 спанов или 1 MB.

POST /v2/ingest/logs

Structured logs. Поддерживаются JSON и plaintext. Поля автоматически экстрактятся, если они consistently structured.

Query

POST /v2/query

Универсальный endpoint для запросов метрик, трейсов и логов. Использует dialect actaflowql (расширение PromQL + LogQL).

POST /v2/query HTTP/1.1
Host: api.actaflow.tech
Content-Type: application/json
x-actaflow-api-key: af_live_...

{
  "query": "histogram_quantile(0.99, sum(rate(payments_request_duration_seconds_bucket{service=\"payments-api\"}[5m])) by (le))",
  "time": "2026-01-08T12:42:00Z",
  "window": "1h",
  "step": "30s",
  "max_points": 1000
}

# Ответ
{
  "result_type": "matrix",
  "result": [{
    "metric": { "service": "payments-api", "quantile": "0.99" },
    "values": [
      [1736338980, "0.142"],
      [1736339010, "0.138"],
      [1736339040, "0.151"],
      ...
    ]
  }],
  "stats": {
    "rows_scanned": 1248392,
    "latency_ms": 78,
    "cache_hit": false
  }
}

Alerts

Method & path	Описание
`GET /v2/alerts`	Список алертов (с фильтрами)
`POST /v2/alerts`	Создать правило алерта
`GET /v2/alerts/{id}`	Получить правило
`PUT /v2/alerts/{id}`	Обновить правило
`DELETE /v2/alerts/{id}`	Удалить правило
`POST /v2/alerts/{id}/silence`	Silence на N минут
`GET /v2/alerts/incidents`	Список активных инцидентов

Dashboards

Method & path	Описание
`GET /v2/dashboards`	Список дашбордов
`POST /v2/dashboards`	Создать (Grafana JSON-совместимый)
`GET /v2/dashboards/{id}`	Получить дашборд
`PUT /v2/dashboards/{id}`	Обновить
`DELETE /v2/dashboards/{id}`	Удалить
`POST /v2/dashboards/{id}/snapshot`	Создать снимок для шеринга

Webhooks

Actaflow может дёргать ваш webhook на события: alert.fired, alert.resolved, incident.created, deploy.detected, slo.burn.

POST /your/webhook HTTP/1.1
Host: your-service.example.com
User-Agent: Actaflow-Webhook/2.4
X-Actaflow-Signature: sha256=ab12cd34...
Content-Type: application/json

{
  "event": "alert.fired",
  "timestamp": "2026-01-08T12:42:18.234Z",
  "tenant": "demo-prod-ru-1a",
  "data": {
    "alert_id": "a_8f3c2a91",
    "name": "payments-api high error rate",
    "severity": "page",
    "expr": "rate(...)>0.01",
    "fingerprint": "fp_72a1b3c9",
    "labels": { "team": "payments" },
    "annotations": { "summary": "Error rate >1%" }
  }
}

Подпись — HMAC-SHA256 от raw body, ключ задаётся в настройках webhook endpoint. Retry с экспоненциальной задержкой, до 24 часов.

Errors

Все ошибки возвращают стандартизированный JSON. Коды HTTP соответствуют семантике.

HTTP	code	Когда
400	`bad_request`	Невалидный JSON, неверный schema
401	`unauthorized`	Отсутствует или невалиден API-ключ
403	`forbidden`	Ключ не имеет нужного scope
404	`not_found`	Ресурс не существует
422	`validation_failed`	Семантическая ошибка в данных
429	`rate_limited`	Превышен лимит, см. `Retry-After`
500	`internal`	Внутренняя ошибка, повторите
503	`service_unavailable`	Planned maintenance, см. status

Rate limits

Лимиты зависят от тарифа и возвращаются в заголовках ответа:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 942
X-RateLimit-Reset:     1736338980

При превышении возвращается 429 с заголовком Retry-After: N (секунд). Ingest endpoint'ы лимитируются отдельно от query — смотрите тарифную таблицу.