API Reference

http://localhost:3000/api       # Backward-compatible (no version prefix)
http://localhost:3000/api/v1    # Versioned (includes X-API-Version: 1 header)

# Bearer token
curl -H "Authorization: Bearer <your-api-key>" http://localhost:3000/api/agents
 
# X-API-Key header
curl -H "X-API-Key: <your-api-key>" http://localhost:3000/api/agents

dojops serve credentials   # Generates API key, saves to ~/.dojops/server.json

{
  "status": "ok",
  "authRequired": true,
  "timestamp": "2026-01-15T10:30:00.000Z"
}

{
  "status": "ok",
  "authRequired": false,
  "provider": "openai",
  "tools": ["github-actions", "terraform", "kubernetes", ...],
  "metricsEnabled": true,
  "timestamp": "2026-01-15T10:30:00.000Z"
}

{
  "prompt": "Create a Kubernetes deployment for nginx",
  "temperature": 0.7
}

{
  "content": "apiVersion: apps/v1\nkind: Deployment\n...",
  "agent": {
    "name": "kubernetes-specialist",
    "domain": "container-orchestration",
    "confidence": 0.92,
    "reason": "Matched keywords: kubernetes, deployment, nginx"
  },
  "historyId": "gen-a1b2c3d4"
}

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a Kubernetes deployment for nginx", "temperature": 0.7}'

{
  "goal": "Set up CI/CD for a Node.js app",
  "execute": false,
  "autoApprove": false
}

{
  "graph": {
    "nodes": [
      { "id": "1", "tool": "github-actions", "input": {...}, "deps": [] },
      { "id": "2", "tool": "dockerfile", "input": {...}, "deps": ["1"] }
    ]
  },
  "result": null,
  "historyId": "plan-e5f6g7h8"
}

curl -X POST http://localhost:3000/api/plan \
  -H "Content-Type: application/json" \
  -d '{"goal": "Set up CI/CD for a Node.js app", "execute": false}'

{
  "log": "ERROR: npm ERR! ERESOLVE unable to resolve dependency tree"
}

{
  "diagnosis": {
    "errorType": "dependency-resolution",
    "rootCause": "Conflicting peer dependency versions",
    "affectedFiles": ["package.json"],
    "fixes": [
      {
        "description": "Use --legacy-peer-deps flag",
        "command": "npm install --legacy-peer-deps",
        "confidence": 0.85
      }
    ]
  },
  "historyId": "debug-i9j0k1l2"
}

curl -X POST http://localhost:3000/api/debug-ci \
  -H "Content-Type: application/json" \
  -d '{"log": "ERROR: npm ERR! ERESOLVE unable to resolve dependency tree"}'

{
  "diff": "+ resource \"aws_s3_bucket\" \"main\" { bucket = \"my-bucket\" }",
  "before": "optional previous state",
  "after": "optional new state"
}

{
  "analysis": {
    "riskLevel": "low",
    "costImpact": "minimal",
    "securityImpact": "none",
    "rollbackComplexity": "simple",
    "recommendations": ["Enable bucket versioning", "Add encryption"]
  },
  "historyId": "diff-m3n4o5p6"
}

curl -X POST http://localhost:3000/api/diff \
  -H "Content-Type: application/json" \
  -d '{"diff": "+ resource \"aws_s3_bucket\" \"main\" { bucket = \"my-bucket\" }"}'

{
  "target": "/path/to/project",
  "scanType": "all"
}

{
  "id": "scan-q7r8s9t0",
  "projectPath": "/path/to/project",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "scanType": "all",
  "findings": [
    {
      "id": "npm-1",
      "tool": "npm-audit",
      "severity": "HIGH",
      "category": "DEPENDENCY",
      "message": "prototype-pollution in lodash <4.17.21",
      "recommendation": "Upgrade lodash to >=4.17.21",
      "autoFixAvailable": true
    }
  ],
  "summary": {
    "total": 5,
    "critical": 0,
    "high": 2,
    "medium": 2,
    "low": 1
  },
  "scannersRun": ["npm-audit", "trivy", "gitleaks"],
  "scannersSkipped": ["pip-audit: no Python project detected"],
  "durationMs": 3200,
  "historyId": "scan-q7r8s9t0"
}

curl -X POST http://localhost:3000/api/scan \
  -H "Content-Type: application/json" \
  -d '{"scanType": "security"}'

{
  "sessionId": "chat-a1b2c3d4",
  "message": "How should I set up Terraform state management?",
  "agent": "terraform-specialist"
}

{
  "content": "For Terraform state management, I recommend...",
  "agent": "terraform-specialist",
  "sessionId": "chat-a1b2c3d4"
}

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "How should I set up Terraform state management?"}'

{
  "name": "infra-planning",
  "mode": "INTERACTIVE"
}

{
  "id": "chat-a1b2c3d4",
  "name": "infra-planning",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z",
  "mode": "INTERACTIVE",
  "messages": [],
  "metadata": {
    "totalTokensEstimate": 0,
    "messageCount": 0
  }
}

curl -X POST http://localhost:3000/api/chat/sessions \
  -H "Content-Type: application/json" \
  -d '{"name": "infra-planning"}'

[
  {
    "id": "chat-a1b2c3d4",
    "name": "infra-planning",
    "updatedAt": "2026-01-15T10:30:00.000Z",
    "mode": "INTERACTIVE",
    "metadata": { "messageCount": 12 }
  }
]

curl http://localhost:3000/api/chat/sessions

curl http://localhost:3000/api/chat/sessions/chat-a1b2c3d4

curl -X DELETE http://localhost:3000/api/chat/sessions/chat-a1b2c3d4

[
  {
    "name": "terraform-specialist",
    "domain": "infrastructure",
    "description": "Expert in Terraform, HCL, modules, state management...",
    "keywords": ["terraform", "infrastructure", "iac", "hcl", ...],
    "type": "built-in"
  },
  {
    "name": "sre-specialist",
    "domain": "site-reliability",
    "description": "SRE specialist for incident response and reliability",
    "keywords": ["sre", "incident", "reliability", ...],
    "type": "custom"
  }
]

curl http://localhost:3000/api/agents

{
  "entries": [...],
  "count": 42
}

curl "http://localhost:3000/api/history?type=generate&limit=10"

curl http://localhost:3000/api/history/gen-a1b2c3d4

curl -X DELETE http://localhost:3000/api/history

curl http://localhost:3000/api/metrics

{
  "totalPlans": 15,
  "totalExecutions": 12,
  "successRate": 0.83,
  "avgExecutionTimeMs": 4500,
  "criticalFindings": 2,
  "highFindings": 5,
  "mostUsedCommands": {"generate": 20, "plan": 15, "scan": 8},
  "recentActivity": [...]
}

curl http://localhost:3000/api/metrics/overview

{
  "totalScans": 8,
  "severityBreakdown": {"critical": 2, "high": 5, "medium": 12, "low": 8},
  "categoryBreakdown": {"SECURITY": 10, "DEPENDENCY": 8, "IAC": 5, "SECRETS": 4},
  "findingsTrend": [...],
  "topIssues": [...],
  "scanHistory": [...]
}

curl http://localhost:3000/api/metrics/security

{
  "totalEntries": 45,
  "chainIntegrity": true,
  "statusBreakdown": {"success": 38, "failure": 5, "cancelled": 2},
  "commandDistribution": {"generate": 20, "apply": 12, "scan": 8, "plan": 5},
  "timeline": [...]
}

curl http://localhost:3000/api/metrics/audit

{
  "error": "Validation failed",
  "details": "prompt is required"
}

{
  "error": "Validation failed",
  "details": [{ "path": ["prompt"], "message": "Required" }]
}

{
  "tokens": [
    {
      "id": "clx1abc...",
      "name": "My laptop",
      "tokenPrefix": "dojops_a1b2c3",
      "expiresAt": "2026-06-01T00:00:00.000Z",
      "lastUsedAt": "2026-03-01T14:30:00.000Z",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ]
}

{
  "name": "CI/CD pipeline",
  "expiration": "3months"
}

{
  "id": "clx1abc...",
  "name": "CI/CD pipeline",
  "tokenPrefix": "dojops_a1b2c3",
  "expiresAt": "2026-06-01T00:00:00.000Z",
  "createdAt": "2026-03-01T10:00:00.000Z",
  "rawToken": "dojops_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}

{
  "deleted": true
}

# Publish using an API token
curl -X POST https://hub.dojops.ai/api/packages \
  -H "Authorization: Bearer dojops_a1b2c3d4e5f6..." \
  -F "file=@my-tool.dops" \
  -F "sha256=$(sha256sum my-tool.dops | cut -d' ' -f1)" \
  -F "changelog=Initial release"

{
  "slug": "my-tool",
  "version": "1.0.0",
  "created": true
}

{
  "slug": "my-tool",
  "version": "1.1.0",
  "updated": true
}