{
  "openapi": "3.1.0",
  "info": {
    "title": "Atlas Agent API",
    "version": "2.0.0",
    "description": "Inspect and update an Atlas knowledge workspace with scoped credentials and optimistic, idempotent transactions, or capture structured Research Missions for human review."
  },
  "servers": [{ "url": "https://atlas-knowledge-canvas-lin.netlify.app" }],
  "paths": {
    "/api/atlas/{workspaceId}": {
      "parameters": [{ "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "summary": "Read a workspace",
        "security": [{ "bearerAuth": [] }],
        "responses": { "200": { "description": "Workspace snapshot", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Unauthorized" } }
      },
      "post": {
        "summary": "Apply an atomic agent transaction",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [{ "$ref": "#/components/schemas/Transaction" }, { "$ref": "#/components/schemas/Bootstrap" }] } } } },
        "responses": { "200": { "description": "Operations applied" }, "400": { "description": "Invalid operation" }, "401": { "description": "Unauthorized" }, "403": { "description": "Credential lacks the required scope or canvas access" }, "409": { "description": "Optimistic revision conflict" } }
      },
      "put": {
        "summary": "Synchronize the Atlas web client workspace",
        "security": [{ "bearerAuth": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["workspace"], "properties": { "workspace": { "type": "object" } } } } } },
        "responses": { "200": { "description": "Workspace synchronized" }, "401": { "description": "Unauthorized" } }
      }
    },
    "/api/atlas-research/{workspaceId}": {
      "parameters": [{ "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": { "summary": "List research sessions and pending inbox candidates", "security": [{ "bearerAuth": [] }], "responses": { "200": { "description": "Research state" }, "401": { "description": "Unauthorized" } } },
      "post": { "summary": "Start, capture, checkpoint, end, ingest, or human-review a research session", "security": [{ "bearerAuth": [] }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResearchAction" } } } }, "responses": { "200": { "description": "Research action applied" }, "400": { "description": "Invalid action" }, "401": { "description": "Unauthorized" } } }
    }
  },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" } },
    "schemas": {
      "Bootstrap": {
        "type": "object",
        "description": "Initialize an unclaimed isolated workspace. Atlas web performs this automatically before issuing a bundle.",
        "required": ["action", "workspace"],
        "properties": { "action": { "const": "bootstrap" }, "workspace": { "type": "object" } }
      },
      "Transaction": {
        "type": "object",
        "required": ["operations"],
        "properties": {
          "agent": { "type": "string", "maxLength": 80 },
          "baseRevision": { "type": "integer", "minimum": 0 },
          "clientMutationId": { "type": "string", "maxLength": 120, "description": "Stable unique ID used to make retries idempotent." },
          "operations": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Operation" } }
        }
      },
      "Operation": {
        "type": "object",
        "required": ["type"],
        "properties": {
          "type": { "enum": ["create_canvas", "create_node", "update_node", "connect", "delete_node"] },
          "canvasId": { "type": "string" },
          "nodeId": { "type": "string" },
          "node": { "type": "object" },
          "patch": { "type": "object" },
          "from": { "type": "string" },
          "to": { "type": "string" },
          "relationship": { "type": "string" },
          "canvas": { "type": "object" }
        }
      },
      "ResearchAction": {
        "oneOf": [
          { "type": "object", "required": ["action", "goal"], "properties": { "action": { "const": "start" }, "canvasId": { "type": "string" }, "goal": { "type": "string", "maxLength": 500 }, "intent": { "enum": ["understand", "compare", "decide", "build"] }, "definitionOfDone": { "type": "string", "maxLength": 500 }, "agent": { "type": "string" } } },
          { "type": "object", "required": ["action", "sessionId", "candidates"], "properties": { "action": { "const": "capture" }, "sessionId": { "type": "string" }, "candidates": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/ResearchCandidate" } } } },
          { "type": "object", "required": ["action", "sessionId"], "properties": { "action": { "enum": ["checkpoint", "end"] }, "sessionId": { "type": "string" }, "label": { "type": "string" } } },
          { "type": "object", "required": ["action", "sessionId", "url"], "properties": { "action": { "const": "ingest_source" }, "sessionId": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }
        ]
      },
      "ResearchCandidate": { "type": "object", "required": ["kind", "title", "content"], "properties": { "kind": { "enum": ["source", "claim", "insight", "decision", "question", "contradiction", "next_step"] }, "title": { "type": "string", "maxLength": 140 }, "content": { "type": "string", "maxLength": 4000 }, "sourceUrl": { "type": "string", "format": "uri" }, "sourceTitle": { "type": "string", "maxLength": 180 }, "sourceAuthor": { "type": "string", "maxLength": 140 }, "sourcePublishedAt": { "type": "string", "maxLength": 80 }, "sourcePublisher": { "type": "string", "maxLength": 120 }, "sourceType": { "type": "string", "maxLength": 40 }, "evidenceQuality": { "type": "string", "maxLength": 120 }, "confidence": { "enum": ["low", "medium", "high"] }, "rationale": { "type": "string", "maxLength": 600 }, "relatedNodeIds": { "type": "array", "maxItems": 12, "items": { "type": "string" } }, "relationship": { "type": "string" } } }
    }
  }
}
