Skip to main content

​
API Endpoints

Base URL: https://api.mergeguide.ai/v1

​
Evaluations

​
Create Evaluation

Analyze code against policies. 
POST /evaluations
Request: 
{
  "repository": "owner/repo",
  "ref": "feature-branch",
  "base_ref": "main",
  "files": [
    {
      "path": "src/api/users.ts",
      "content": "...",
      "status": "modified"
    }
  ],
  "policies": ["no-hardcoded-secrets", "no-sql-injection"]
}
Response: 
{
  "id": "eval_abc123",
  "status": "completed",
  "repository": "owner/repo",
  "ref": "feature-branch",
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:30:05Z",
  "passed": false,
  "summary": {
    "total_files": 1,
    "total_violations": 2,
    "errors": 1,
    "warnings": 1
  },
  "violations": [
    {
      "id": "viol_xyz789",
      "policy_id": "no-hardcoded-secrets",
      "severity": "error",
      "file": "src/api/users.ts",
      "line": 45,
      "column": 12,
      "message": "Hardcoded API key detected",
      "code_snippet": "const apiKey = 'sk-abc123...'",
      "suggestion": "Move to environment variable"
    }
  ]
}

​
Get Evaluation

Retrieve evaluation details. 
GET /evaluations/{evaluation_id}
Response: Same as create response.

​
List Evaluations

List evaluations with filtering. 
GET /evaluations
Query Parameters:
ParameterTypeDescription
repositorystringFilter by repository
statusstringFilter by status (pending, completed, failed)
passedbooleanFilter by pass/fail
sinceISO8601Evaluations after this date
untilISO8601Evaluations before this date
limitintegerMax results (default: 20, max: 100)
cursorstringPagination cursor
Response: 
{
  "evaluations": [...],
  "pagination": {
    "next_cursor": "cursor_abc123",
    "has_more": true
  }
}

​
Delete Evaluation

DELETE /evaluations/{evaluation_id}
Response: 204 No Content

​
Policies

​
List Policies

GET /policies
Query Parameters:
ParameterTypeDescription
enabledbooleanFilter by enabled state
categorystringFilter by category
severitystringFilter by severity
Response: 
{
  "policies": [
    {
      "id": "no-hardcoded-secrets",
      "name": "No Hardcoded Secrets",
      "description": "Detect secrets in code",
      "severity": "error",
      "enabled": true,
      "category": "security",
      "frameworks": ["nist-ssdf:PW", "owasp-asvs:V14"]
    }
  ]
}

​
Get Policy

GET /policies/{policy_id}
Response: 
{
  "id": "no-hardcoded-secrets",
  "name": "No Hardcoded Secrets",
  "description": "...",
  "severity": "error",
  "enabled": true,
  "patterns": [...],
  "suggestions": [...],
  "documentation_url": "https://docs.mergeguide.ai/policies/no-hardcoded-secrets"
}

​
Update Policy

PATCH /policies/{policy_id}
Request: 
{
  "enabled": true,
  "severity": "warning",
  "settings": {
    "detect_api_keys": true
  }
}

​
Create Custom Policy

POST /policies
Request: 
{
  "id": "my-custom-policy",
  "name": "My Custom Policy",
  "description": "Custom organization policy",
  "severity": "warning",
  "patterns": [
    {
      "type": "regex",
      "value": "CUSTOM_PATTERN",
      "message": "Custom violation message"
    }
  ]
}

​
Delete Custom Policy

DELETE /policies/{policy_id}

​
Repositories

​
List Repositories

GET /repositories
Response: 
{
  "repositories": [
    {
      "id": "repo_abc123",
      "name": "owner/repo",
      "provider": "github",
      "default_branch": "main",
      "connected_at": "2024-01-01T00:00:00Z",
      "last_evaluation": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Connect Repository

POST /repositories
Request: 
{
  "provider": "github",
  "name": "owner/repo"
}

​
Disconnect Repository

DELETE /repositories/{repository_id}

​
Compliance

​
Get Compliance Overview

GET /compliance
Response: 
{
  "frameworks": [
    {
      "id": "nist-ssdf",
      "name": "NIST SSDF",
      "coverage": 75,
      "controls": {
        "total": 20,
        "covered": 15
      }
    }
  ],
  "regulations": [
    {
      "id": "soc2",
      "name": "SOC 2",
      "coverage": 80
    }
  ]
}

​
Get Framework Coverage

GET /compliance/frameworks/{framework_id}
Response: 
{
  "framework": {
    "id": "nist-ssdf",
    "name": "NIST SSDF",
    "version": "1.1"
  },
  "coverage": 75,
  "controls": [
    {
      "id": "PW",
      "name": "Produce Well-Secured Software",
      "covered": true,
      "policies": ["no-hardcoded-secrets", "no-sql-injection"]
    }
  ]
}

​
Generate Compliance Report

POST /compliance/reports
Request: 
{
  "frameworks": ["nist-ssdf", "soc2"],
  "date_range": {
    "start": "2024-01-01",
    "end": "2024-01-31"
  },
  "format": "pdf"
}
Response: 
{
  "report_id": "report_abc123",
  "status": "generating",
  "download_url": null
}

​
Get Report Status

GET /compliance/reports/{report_id}

​
Organizations

​
Get Organization

GET /organization
Response: 
{
  "id": "org_abc123",
  "name": "My Organization",
  "plan": "enterprise",
  "members_count": 25,
  "repositories_count": 15,
  "created_at": "2023-06-01T00:00:00Z"
}

​
Update Organization

PATCH /organization
Request: 
{
  "name": "Updated Organization Name",
  "settings": {
    "default_severity": "error",
    "require_evaluation_pass": true
  }
}

​
Webhooks

​
List Webhooks

GET /webhooks

​
Create Webhook

POST /webhooks
Request: 
{
  "url": "https://example.com/webhook",
  "events": ["evaluation.completed", "policy.violation"],
  "secret": "webhook_secret"
}

​
Delete Webhook

DELETE /webhooks/{webhook_id}

​
Health

​
API Health Check

GET /health
Response: 
{
  "status": "healthy",
  "version": "1.2.3",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Authenticated Health Check

GET /health/auth
Verifies authentication is working. Response: 
{
  "status": "healthy",
  "authenticated": true,
  "organization": "my-org",
  "scopes": ["read:evaluations", "write:evaluations"]
}