Skip to main content
API Reference

REST API

Trigger analyses, retrieve results, and manage connections in code. Base URL: https://api.yagnihq.com/v1

Authentication

Every request needs a Bearer token in the Authorization header. Find your API key under Settings > API Keys in the YAGNI dashboard.

bash 
Authorization: Bearer ygn_live_xxxxxxxxxxxxxxxxxxxx

POST /analyses

Start a dead path analysis for a connected repository.

Each repository allows 10 analysis triggers per hour. Webhook notifications arrive when analysis completes.

bash 
curl -X POST https://api.yagnihq.com/v1/analyses \
  -H "Authorization: Bearer $YAGNI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_id": "repo_abc123",
    "branch": "main",
    "open_prs": true
  }'
json 
{
  "id": "analysis_xyz789",
  "repository_id": "repo_abc123",
  "status": "queued",
  "created_at": "2026-07-10T14:23:00Z"
}

GET /analyses/:id

Get an analysis run's status and results.

json 
{
  "id": "analysis_xyz789",
  "repository_id": "repo_abc123",
  "status": "completed",
  "summary": {
    "modules_analyzed": 847,
    "dead_paths_found": 23,
    "prs_opened": 3,
    "lines_removed": 1842
  },
  "completed_at": "2026-07-10T14:31:17Z"
}

Status values: queued, running, completed, failed

GET /repositories

Return every repository connected to your account.

json 
{
  "repositories": [
    {
      "id": "repo_abc123",
      "name": "acme-corp/api-service",
      "provider": "github",
      "default_branch": "main",
      "last_analysis_at": "2026-07-10T14:31:17Z"
    }
  ],
  "total": 1
}

Webhooks

Set up webhooks under Settings > Webhooks in the dashboard. YAGNI will POST to your endpoint when:

  • An analysis run completes (analysis.completed)
  • A pull request is opened (pr.opened)
  • A pull request is merged (pr.merged)
json 
{
  "event": "analysis.completed",
  "analysis_id": "analysis_xyz789",
  "repository_id": "repo_abc123",
  "summary": {
    "dead_paths_found": 23,
    "prs_opened": 3
  },
  "timestamp": "2026-07-10T14:31:17Z"
}

Verify webhook payloads through the X-YAGNI-Signature header. Compute HMAC-SHA256(webhook_secret, payload_body) and compare the values.