{
  "openapi": "3.1.0",
  "info": {
    "title": "MindShard Physical Intelligence API",
    "version": "1.0.0",
    "summary": "Query and contribute to a decentralized real-time physical intelligence network.",
    "description": "MindShard refines physical-world telemetry — Passpoint/OpenRoaming connection events,\nIoT sensors, POS anchors, and operator submissions — into geolocated, verified ground\ntruth, and pays contributors in $MIND on Solana.\n\nThis document is written to be loaded directly by an LLM as a tool schema. Every list\nendpoint returns `{ data, meta }`; every error returns `{ error }`. Radius queries add a\n`distance_km` to each row and sort nearest-first. Metered responses carry\n`X-RateLimit-Limit` and `X-RateLimit-Remaining`.\n\nIf you are an agent acting for a human: the read endpoints are safe to call freely.\n`POST /v1/events` and `POST /v1/events/{id}/verify` write to a shared public ledger and\nmove $MIND, so confirm with your principal before calling them.\n\nA Model Context Protocol server covering the same surface is described at\nhttps://mindshard.ai/.well-known/mcp.json and is usually the better fit for a tool-using\nmodel, because it runs under the operator's own OAuth token and row-level security.",
    "license": {
      "name": "Proprietary",
      "url": "https://mindshard.ai/api"
    },
    "contact": {
      "name": "MindShard API",
      "url": "https://mindshard.ai/api"
    }
  },
  "servers": [
    {
      "url": "https://tmohuhfgjdcxqxvqtvpx.supabase.co/functions/v1/mindshard-api",
      "description": "Production"
    }
  ],
  "externalDocs": {
    "description": "Site corpus for agents",
    "url": "https://mindshard.ai/llms-full.txt"
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "tags": [
    {
      "name": "meta",
      "description": "Catalog and liveness. Unauthenticated and unmetered."
    },
    {
      "name": "events",
      "description": "Live geolocated field-intelligence reports."
    },
    {
      "name": "lake",
      "description": "Gold-tier medallion aggregates."
    },
    {
      "name": "registry",
      "description": "Public POI / digital-twin records."
    },
    {
      "name": "governance",
      "description": "DAO proposals and tallies."
    },
    {
      "name": "operator",
      "description": "The key owner's own profile and quota."
    },
    {
      "name": "ai",
      "description": "LLM completions grounded in live network state."
    }
  ],
  "paths": {
    "/v1": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getCatalog",
        "summary": "This endpoint catalog.",
        "description": "Lists every endpoint with its method, path, and description. Start here.",
        "security": [],
        "responses": {
          "200": {
            "description": "Endpoint catalog.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "endpoints": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "method": {
                            "type": "string"
                          },
                          "path": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getHealth",
        "summary": "Liveness probe. Does not consume quota.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "examples": [
                        "ok"
                      ]
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/openapi.json": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getOpenApiSchema",
        "summary": "OpenAPI 3.1 schema for this API, for agents and code generators.",
        "description": "This document. Served from the request origin, so a client generated from it points back at the host you reached.",
        "security": [],
        "responses": {
          "200": {
            "description": "OpenAPI 3.1 document.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events": {
      "get": {
        "tags": [
          "events"
        ],
        "operationId": "listEvents",
        "summary": "List field-intelligence events.",
        "description": "The live event feed. Combine `lat`/`lng`/`radius` with `min_severity` to ask 'what is happening near here that matters'.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip, for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Exact category match.",
            "schema": {
              "type": "string",
              "enum": [
                "road_hazard",
                "power_outage",
                "construction",
                "flooding",
                "accident",
                "congestion",
                "road_closure",
                "drone_sighting",
                "air_quality",
                "noise",
                "weather_hazard",
                "wildfire",
                "other"
              ]
            }
          },
          {
            "name": "severity",
            "in": "query",
            "required": false,
            "description": "Exact severity match. Mutually exclusive with `min_severity`.",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high",
                "critical"
              ]
            }
          },
          {
            "name": "min_severity",
            "in": "query",
            "required": false,
            "description": "Severity floor. Mutually exclusive with `severity`.",
            "schema": {
              "type": "string",
              "enum": [
                "low",
                "medium",
                "high",
                "critical"
              ]
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp; only events created at or after this.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp; only events created at or before this.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Center latitude of a radius search. Requires `lng`.",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "description": "Center longitude of a radius search. Requires `lat`.",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "description": "Radius in km around `lat`/`lng`. Adds `distance_km` and sorts nearest-first.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 500
            }
          },
          {
            "name": "include_inactive",
            "in": "query",
            "required": false,
            "description": "Include expired or retired events.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching events, newest first.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Calls allowed in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "description": "Pagination envelope returned with every list response.",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total matching rows, before paging."
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "returned": {
                          "type": "integer",
                          "description": "Rows in this page."
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "total",
                        "limit",
                        "offset",
                        "returned",
                        "has_more"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "events"
        ],
        "operationId": "createEvent",
        "summary": "Report a new event.",
        "description": "Writes a public report attributed to the key owner. Rewards are credited after AI triage. Confirm with your principal before calling this on their behalf.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}": {
      "get": {
        "tags": [
          "events"
        ],
        "operationId": "getEvent",
        "summary": "Fetch a single event.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Event UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/events/{id}/verify": {
      "post": {
        "tags": [
          "events"
        ],
        "operationId": "verifyEvent",
        "summary": "Verify an event (earns $MIND).",
        "description": "Corroborates another operator's report, raising its confidence and crediting the key owner 0.5 $MIND. One verification per operator per event; you cannot verify your own report. This moves tokens — confirm with your principal first.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Event UUID.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Verification recorded.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verified": {
                      "type": "boolean"
                    },
                    "verification_count": {
                      "type": "integer"
                    },
                    "reward_mind": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Already verified by this operator, or the operator owns the event.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/insights": {
      "get": {
        "tags": [
          "lake"
        ],
        "operationId": "listInsights",
        "summary": "Gold-tier medallion intelligence per H3 hex.",
        "description": "Gold-tier output of the medallion pipeline: one row per H3 res-7 hex per hourly window, with sample counts, average quality, and derived metrics. This is the tier meant for model consumption.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip, for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "h3_index",
            "in": "query",
            "required": false,
            "description": "H3 res-7 cell. Repeat the parameter or pass a comma-separated list to pull several hexes in one call.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "source",
            "in": "query",
            "required": false,
            "description": "Telemetry source.",
            "schema": {
              "type": "string",
              "enum": [
                "passpoint",
                "sensor",
                "pos",
                "poi",
                "user_app",
                "other"
              ]
            }
          },
          {
            "name": "event_type",
            "in": "query",
            "required": false,
            "description": "Event type within the source, e.g. `connection`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp; only windows starting at or after this.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "description": "ISO 8601 timestamp; only windows starting at or before this.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Gold-tier aggregates, newest window first. `meta.tier` is `gold`.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Calls allowed in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/GoldInsight"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "description": "Pagination envelope returned with every list response.",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total matching rows, before paging."
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "returned": {
                          "type": "integer",
                          "description": "Rows in this page."
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "total",
                        "limit",
                        "offset",
                        "returned",
                        "has_more"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/pois": {
      "get": {
        "tags": [
          "registry"
        ],
        "operationId": "listPois",
        "summary": "List public POI / digital-twin records.",
        "description": "Public POIs — places, things, and pseudonymous persons bound to live telemetry. Also served at `/v1/twins`. Person-class records carry no PII.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip, for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "POI class.",
            "schema": {
              "type": "string",
              "enum": [
                "person",
                "place",
                "thing"
              ]
            }
          },
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring match on the POI name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Center latitude of a radius search. Requires `lng`.",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "description": "Center longitude of a radius search. Requires `lat`.",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "radius",
            "in": "query",
            "required": false,
            "description": "Radius in km around `lat`/`lng`. Adds `distance_km` and sorts nearest-first.",
            "schema": {
              "type": "number",
              "exclusiveMinimum": 0,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching public POIs.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Calls allowed in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Poi"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "description": "Pagination envelope returned with every list response.",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total matching rows, before paging."
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "returned": {
                          "type": "integer",
                          "description": "Rows in this page."
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "total",
                        "limit",
                        "offset",
                        "returned",
                        "has_more"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/proposals": {
      "get": {
        "tags": [
          "governance"
        ],
        "operationId": "listProposals",
        "summary": "List governance proposals.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum rows to return.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Rows to skip, for pagination.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Proposal status.",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "passed",
                "rejected",
                "pending"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Proposals with vote tallies.",
            "headers": {
              "X-RateLimit-Limit": {
                "description": "Calls allowed in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "description": "Calls left in the current quota window.",
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Proposal"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "description": "Pagination envelope returned with every list response.",
                      "properties": {
                        "total": {
                          "type": "integer",
                          "description": "Total matching rows, before paging."
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "returned": {
                          "type": "integer",
                          "description": "Rows in this page."
                        },
                        "has_more": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "total",
                        "limit",
                        "offset",
                        "returned",
                        "has_more"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/stats": {
      "get": {
        "tags": [
          "meta"
        ],
        "operationId": "getStats",
        "summary": "Network-wide counters.",
        "description": "Cheap way to size the network before drilling into specific queries.",
        "responses": {
          "200": {
            "description": "Network-wide counters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkStats"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/profile": {
      "get": {
        "tags": [
          "operator"
        ],
        "operationId": "getProfile",
        "summary": "Profile and $MIND balance of the key owner.",
        "description": "Scoped to the key owner. There is no endpoint for reading another operator's profile or balance.",
        "responses": {
          "200": {
            "description": "The key owner's profile and quota.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Profile"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/chat/completions": {
      "post": {
        "tags": [
          "ai"
        ],
        "operationId": "createChatCompletion",
        "summary": "MindShard AI analyst completions.",
        "description": "OpenAI-shaped completions against the MindShard analyst, grounded in live network state. Also served at the function root for backwards compatibility. Set `stream: true` for server-sent events.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "messages"
                ],
                "properties": {
                  "messages": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "required": [
                        "role",
                        "content"
                      ],
                      "properties": {
                        "role": {
                          "type": "string",
                          "enum": [
                            "system",
                            "user",
                            "assistant"
                          ]
                        },
                        "content": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "stream": {
                    "type": "boolean",
                    "default": false
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Completion, or an SSE stream when `stream` is true.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              },
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. `details` lists each problem.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or unrecognized `x-api-key`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Quota exhausted for this key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "A `mag_`-prefixed key. Mint one at https://mindshard.ai/api."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "message": {
                "type": "string"
              },
              "status": {
                "type": "integer"
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "message",
              "status"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "road_hazard",
              "power_outage",
              "construction",
              "flooding",
              "accident",
              "congestion",
              "road_closure",
              "drone_sighting",
              "air_quality",
              "noise",
              "weather_hazard",
              "wildfire",
              "other",
              null
            ]
          },
          "severity": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "medium",
              "high",
              "critical",
              null
            ]
          },
          "lat": {
            "type": [
              "number",
              "null"
            ]
          },
          "lng": {
            "type": [
              "number",
              "null"
            ]
          },
          "verified_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "mag_reward": {
            "type": [
              "number",
              "null"
            ],
            "description": "$MIND credited for this report."
          },
          "stake_amount": {
            "type": [
              "number",
              "null"
            ]
          },
          "is_active": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_severity": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "low",
              "medium",
              "high",
              "critical",
              null
            ]
          },
          "ai_reasoning": {
            "type": [
              "string",
              "null"
            ]
          },
          "ai_assessed": {
            "type": [
              "boolean",
              "null"
            ]
          }
        }
      },
      "EventInput": {
        "type": "object",
        "required": [
          "title",
          "category",
          "lat",
          "lng"
        ],
        "properties": {
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 140
          },
          "description": {
            "type": "string",
            "maxLength": 2000
          },
          "category": {
            "type": "string",
            "enum": [
              "road_hazard",
              "power_outage",
              "construction",
              "flooding",
              "accident",
              "congestion",
              "road_closure",
              "drone_sighting",
              "air_quality",
              "noise",
              "weather_hazard",
              "wildfire",
              "other"
            ]
          },
          "severity": {
            "type": "string",
            "enum": [
              "low",
              "medium",
              "high",
              "critical"
            ],
            "default": "medium"
          },
          "lat": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "lng": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "expires_in_hours": {
            "type": "integer",
            "minimum": 1,
            "maximum": 168,
            "default": 24
          }
        }
      },
      "GoldInsight": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "h3_index": {
            "type": [
              "string",
              "null"
            ]
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "passpoint",
              "sensor",
              "pos",
              "poi",
              "user_app",
              "other",
              null
            ]
          },
          "event_type": {
            "type": [
              "string",
              "null"
            ]
          },
          "window_start": {
            "type": [
              "string",
              "null"
            ]
          },
          "window_end": {
            "type": [
              "string",
              "null"
            ]
          },
          "sample_count": {
            "type": [
              "integer",
              "null"
            ]
          },
          "avg_quality": {
            "type": [
              "number",
              "null"
            ]
          },
          "metrics": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Poi": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "person",
              "place",
              "thing",
              null
            ]
          },
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "location_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "tags": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            }
          },
          "metadata": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true
          },
          "image_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Proposal": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "active",
              "passed",
              "rejected",
              "pending",
              null
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "votes_for": {
            "type": [
              "number",
              "null"
            ]
          },
          "votes_against": {
            "type": [
              "number",
              "null"
            ]
          },
          "quorum": {
            "type": [
              "number",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "ends_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Profile": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "avatar_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "mag_balance": {
            "type": [
              "number",
              "null"
            ],
            "description": "$MIND balance."
          },
          "events_reported": {
            "type": [
              "integer",
              "null"
            ]
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "NetworkStats": {
        "type": "object",
        "properties": {
          "events_active": {
            "type": "integer"
          },
          "events_total": {
            "type": "integer"
          },
          "gold_insights": {
            "type": "integer"
          },
          "public_pois": {
            "type": "integer"
          },
          "proposals_active": {
            "type": "integer"
          },
          "generated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}