{
  "openapi": "3.1.0",
  "info": {
    "title": "Arcanist API",
    "version": "1.0.0",
    "description": "Start a Zeus review for a GitHub pull request and read the review status. The official Arcanist CLI is the preferred client for most agents."
  },
  "servers": [{ "url": "https://app.tryarcanist.com", "description": "Arcanist production API" }],
  "security": [{ "bearerAuth": [] }],
  "paths": {
    "/api/pr-reviews": {
      "post": {
        "operationId": "startPrReview",
        "summary": "Start a Zeus pull request review",
        "description": "Starts a Zeus review for a GitHub pull request that the authenticated user can write to. The Arcanist GitHub App must be installed for the repository owner.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/StartPrReviewRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The review started, a completed result was reused, or a duplicate diff was skipped.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPrReviewResponse" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "409": { "$ref": "#/components/responses/Conflict" },
          "503": { "$ref": "#/components/responses/Unavailable" }
        }
      }
    },
    "/api/pr-reviews/status": {
      "get": {
        "operationId": "getPrReviewStatus",
        "summary": "Read the latest Zeus review status",
        "description": "Returns the latest Zeus review attempt for the supplied GitHub pull request URL.",
        "parameters": [{
          "name": "prUrl",
          "in": "query",
          "required": true,
          "description": "The complete GitHub pull request URL.",
          "schema": { "type": "string", "format": "uri", "pattern": "^https://github\\.com/[^/]+/[^/]+/pull/[0-9]+$" }
        }],
        "responses": {
          "200": {
            "description": "The latest review status and any completed findings.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrReviewStatus" } } }
          },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": { "type": "http", "scheme": "bearer", "description": "An Arcanist CLI or user session token." }
    },
    "schemas": {
      "StartPrReviewRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": ["prUrl"],
        "properties": {
          "prUrl": { "type": "string", "format": "uri", "description": "A GitHub pull request URL." },
          "focus": { "type": "string", "description": "An optional concern for Zeus to examine." },
          "model": { "type": "string", "maxLength": 200, "description": "An optional reviewer model available to authorized Arcanist members." }
        }
      },
      "StartPrReviewResponse": {
        "type": "object",
        "description": "The accepted or reused review result.",
        "properties": {
          "sessionId": { "type": ["string", "null"], "description": "The Arcanist session identifier when a session exists." },
          "claimed": { "type": "boolean", "description": "Whether a new review was claimed." },
          "cached": { "type": "boolean", "description": "Whether a completed result was reused." },
          "skipped": { "type": "boolean", "description": "Whether the review was skipped." },
          "reason": { "type": "string", "description": "The skip reason when skipped." },
          "sourcePrUrl": { "type": "string", "format": "uri", "description": "The pull request with the matching diff when skipped." },
          "verdict": { "$ref": "#/components/schemas/Verdict" },
          "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } }
        }
      },
      "PrReviewStatus": {
        "type": "object",
        "additionalProperties": false,
        "required": ["status", "sessionId", "verdict", "findings"],
        "properties": {
          "status": { "type": "string", "enum": ["in_flight", "completed"], "description": "The current state of the review." },
          "sessionId": { "type": ["string", "null"], "description": "The Arcanist session identifier." },
          "verdict": { "anyOf": [{ "$ref": "#/components/schemas/Verdict" }, { "type": "null" }], "description": "The verdict after completion." },
          "findings": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" } },
          "headSha": { "type": ["string", "null"], "description": "The reviewed Git commit SHA when available." }
        }
      },
      "Finding": {
        "type": "object",
        "additionalProperties": false,
        "required": ["file", "line", "severity", "title", "body"],
        "properties": {
          "file": { "type": "string", "description": "The repository relative file path." },
          "line": { "type": "integer", "minimum": 1, "description": "The ending line for the finding." },
          "startLine": { "type": "integer", "minimum": 1, "description": "The optional starting line for a multi-line finding." },
          "severity": { "type": "string", "enum": ["P1", "P2"], "description": "The defect severity." },
          "title": { "type": "string", "description": "A short description of the defect." },
          "body": { "type": "string", "description": "Evidence and impact for the defect." }
        }
      },
      "Verdict": { "type": "string", "enum": ["clear", "issues_found", "inconclusive"], "description": "The completed Zeus review verdict." },
      "Error": {
        "type": "object",
        "description": "An error returned by the Arcanist API.",
        "properties": {
          "error": { "type": "string", "description": "A human-readable error message." },
          "code": { "type": "string", "description": "A stable error code when available." }
        }
      }
    },
    "responses": {
      "BadRequest": { "description": "The request is invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unauthorized": { "description": "Authentication is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Forbidden": { "description": "The user cannot access the repository or feature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Conflict": { "description": "The review cannot start in the current state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
      "Unavailable": { "description": "The review could not start because a dependency is unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }
    }
  }
}