{
  "openapi": "3.1.0",
  "info": {
    "title": "Noah Predict External API",
    "version": "0.1.0",
    "summary": "Headless API for Noah Predict saved methods, saved reports, runs, packages and data packs.",
    "description": "Noah Predict is a predictive signal intelligence engine. This public OpenAPI description is intended for developers and AI agents evaluating account-scoped API access. Production access requires an account API key created inside Noah Predict."
  },
  "servers": [
    {
      "url": "https://noahpredict.com/api"
    },
    {
      "url": "https://www.noahpredict.com/api"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/external/v1/recipes": {
      "get": {
        "operationId": "listSavedReports",
        "summary": "List saved Noah Predict reports or methods for the API key account.",
        "description": "Returns account-owned saved recipes/reports that the API key is allowed to run.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Saved reports listed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecipeListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          }
        }
      }
    },
    "/external/v1/recipes/{recipe_id}/run": {
      "post": {
        "operationId": "runSavedReport",
        "summary": "Run a saved Noah Predict report or method.",
        "parameters": [
          {
            "name": "recipe_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunSetupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Run started or completed with the first turn response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/external/v1/reports": {
      "post": {
        "operationId": "createFreshReport",
        "summary": "Create a fresh Noah Predict investigation.",
        "description": "Requires a full-dashboard API key and plan entitlement.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/RunSetupRequest"
                  },
                  {
                    "type": "object",
                    "required": [
                      "question"
                    ],
                    "properties": {
                      "question": {
                        "type": "string",
                        "description": "Forward-looking question for Noah Predict."
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Fresh investigation run returned.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          }
        }
      }
    },
    "/external/v1/runs/{session_id}": {
      "get": {
        "operationId": "getRunStatus",
        "summary": "Get run status for an API-created Noah Predict run.",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Run status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/external/v1/runs/{session_id}/package": {
      "get": {
        "operationId": "getRunPackage",
        "summary": "Retrieve the latest structured Noah Predict package for a run.",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Structured package.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          },
          "404": {
            "description": "Package is not ready or run was not found."
          }
        }
      }
    },
    "/external/v1/runs/{session_id}/data-pack": {
      "get": {
        "operationId": "downloadDataPack",
        "summary": "Download a redacted machine-readable JSON data pack.",
        "parameters": [
          {
            "name": "session_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON data pack attachment.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/AuthError"
          },
          "404": {
            "description": "Data pack is not ready or run was not found."
          }
        }
      }
    }
  },
  "x-planned-artifacts": {
    "description": "Future external API artifact downloads should be implemented as run-scoped endpoints with the same account ownership and packages:read checks as package/data-pack retrieval.",
    "candidate_endpoints": {
      "pdf": "GET /external/v1/runs/{session_id}/artifacts/report.pdf",
      "markdown": "GET /external/v1/runs/{session_id}/artifacts/report.md",
      "evidence_csv": "GET /external/v1/runs/{session_id}/artifacts/evidence.csv"
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Noah Predict account API key. Create inside the account area. Store only in server-side secret management."
      }
    },
    "schemas": {
      "RunSetupRequest": {
        "type": "object",
        "properties": {
          "framework_id": {
            "type": "string",
            "default": "auto"
          },
          "decision_purpose": {
            "type": "string",
            "default": "general"
          },
          "horizon": {
            "type": "string",
            "enum": [
              "7 days",
              "30 days",
              "90 days",
              "180 days"
            ],
            "default": "90 days"
          },
          "geography": {
            "type": "string"
          },
          "source_mode": {
            "type": "string",
            "default": "balanced"
          },
          "freshness": {
            "type": "string",
            "default": "recent"
          },
          "output_depth": {
            "type": "string",
            "default": "standard"
          },
          "second_pass_preference": {
            "type": "string",
            "default": "auto"
          }
        }
      },
      "RecipeListResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "count": {
            "type": "integer"
          },
          "recipes": {
            "type": "array",
            "items": {
              "type": "object"
            }
          }
        }
      },
      "RunResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          },
          "result": {
            "type": "object"
          },
          "next": {
            "type": "object"
          }
        }
      },
      "RunStatusResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "reply": {
            "type": "string"
          },
          "package_available": {
            "type": "boolean"
          },
          "route_readiness": {
            "type": "object"
          },
          "links": {
            "type": "object"
          }
        }
      },
      "PackageResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          },
          "package_id": {
            "type": "string"
          },
          "package": {
            "type": "object"
          },
          "links": {
            "type": "object"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "AuthError": {
        "description": "Missing, invalid, revoked or insufficiently scoped API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found or not owned by the account.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}