{
  "openapi": "3.1.0",
  "info": {
    "title": "Atlasemoji BuoyNet",
    "version": "1.1.0",
    "description": "Public NOAA station discovery, observations and research exports, plus authorized AtlasEvo imports. Location geometry is a NOAA inventory snapshot, not a measured sensor depth. Depth/vertical reference and instrument details remain unknown. Catalog imports create deterministic BuoyNet source/dataset/layer/assets and records. Reading imports save up to 144 rows for one station. Transactions commit pages atomically; whole import is not atomic. Retry resumes stable identities. Dataset records are refreshable provider snapshots, not immutable scientific observation submissions. NOAA inventory cache 15 minutes; reading cache 5 minutes. Old buoy-finder endpoints remain compatible aliases. This release supports NOAA meteorological feeds, not other providers or audio."
  },
  "servers": [
    {
      "url": "/api/buoynet/v1"
    }
  ],
  "paths": {
    "/stations": {
      "get": {
        "operationId": "findBuoyStations",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "buoy",
                "all"
              ],
              "default": "buoy"
            }
          },
          {
            "name": "latitude",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "longitude",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 1500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "stations",
                    "fetchedAt"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "fetchedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "stations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Station"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stations/{stationId}": {
      "get": {
        "operationId": "getBuoyReadings",
        "parameters": [
          {
            "name": "stationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9]{5}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "station",
                    "observations",
                    "fetchedAt",
                    "sourceUrl",
                    "sourceFormat",
                    "attribution"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "fetchedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "station": {
                      "$ref": "#/components/schemas/Station"
                    },
                    "observations": {
                      "type": "array",
                      "maxItems": 144,
                      "items": {
                        "$ref": "#/components/schemas/Observation"
                      }
                    },
                    "sourceUrl": {
                      "type": "string"
                    },
                    "sourceFormat": {
                      "type": "string"
                    },
                    "attribution": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stations/export": {
      "get": {
        "operationId": "exportBuoyStationGeometry",
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "buoy",
                "all"
              ],
              "default": "buoy"
            }
          },
          {
            "name": "latitude",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            }
          },
          {
            "name": "longitude",
            "in": "query",
            "schema": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          {
            "name": "search",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "default": 1500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "NOAA inventory points with source metadata",
            "content": {
              "application/geo+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "type",
                    "features"
                  ],
                  "properties": {
                    "type": {
                      "const": "FeatureCollection"
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Feature"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/stations/{stationId}/export": {
      "get": {
        "operationId": "exportBuoyResearchData",
        "parameters": [
          {
            "name": "stationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9]{5}$"
            }
          },
          {
            "name": "format",
            "in": "query",
            "schema": {
              "enum": [
                "json",
                "csv",
                "geojson"
              ],
              "default": "json"
            }
          },
          {
            "name": "category",
            "in": "query",
            "schema": {
              "enum": [
                "all",
                "wind",
                "waves",
                "temperature",
                "weather",
                "water",
                "other"
              ],
              "default": "all"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Up to 144 source rows with selected measurement categories. CSV has one row per measurement. GeoJSON has one point per source observation using inventory position; raw source row remains intact.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "station",
                    "observations",
                    "fetchedAt"
                  ],
                  "properties": {
                    "station": {
                      "$ref": "#/components/schemas/Station"
                    },
                    "observations": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Observation"
                      }
                    }
                  }
                }
              },
              "application/geo+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "type",
                    "features"
                  ],
                  "properties": {
                    "type": {
                      "const": "FeatureCollection"
                    },
                    "features": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Feature"
                      }
                    }
                  }
                }
              },
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/workspaces/{workspaceId}/import": {
      "post": {
        "operationId": "importBuoyNetIntoAtlasEvo",
        "security": [
          {
            "firebaseBearer": []
          }
        ],
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "mode"
                    ],
                    "properties": {
                      "mode": {
                        "const": "catalog"
                      }
                    }
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "mode",
                      "stationId"
                    ],
                    "properties": {
                      "mode": {
                        "const": "readings"
                      },
                      "stationId": {
                        "type": "string",
                        "pattern": "^[a-zA-Z0-9]{5}$"
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Imported into dedicated BuoyNet source/dataset/layer. Repeated requests use stable IDs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "sourceId",
                    "datasetId",
                    "layerId",
                    "mode",
                    "imported",
                    "fetchedAt",
                    "manifestUpdated"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "sourceId": {
                      "type": "string"
                    },
                    "datasetId": {
                      "type": "string"
                    },
                    "layerId": {
                      "type": "string"
                    },
                    "mode": {
                      "enum": [
                        "catalog",
                        "readings"
                      ]
                    },
                    "imported": {
                      "type": "integer",
                      "minimum": 1
                    },
                    "fetchedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "manifestUpdated": {
                      "type": "boolean",
                      "description": "False means saved dataset/assets are available but the draft manifest failed to refresh. Retry to rebuild."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "JSON response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Station": {
        "type": "object",
        "required": [
          "id",
          "name",
          "latitude",
          "longitude",
          "platformType",
          "operator",
          "owner",
          "network",
          "meteorologicalFeed",
          "sourceUrl"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "platformType": {
            "type": "string"
          },
          "network": {
            "type": "string"
          },
          "sourceUrl": {
            "type": "string"
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "operator": {
            "type": [
              "string",
              "null"
            ],
            "description": "Operator code from NOAA inventory; not verified legal ownership."
          },
          "owner": {
            "type": "null",
            "description": "Ownership is unknown in this inventory."
          },
          "meteorologicalFeed": {
            "type": "boolean"
          },
          "distanceKm": {
            "type": "number"
          }
        }
      },
      "Measurement": {
        "type": "object",
        "required": [
          "code",
          "label",
          "category",
          "unit",
          "sourceUnit",
          "value",
          "sourceValue"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "category": {
            "type": "string",
            "enum": [
              "wind",
              "waves",
              "weather",
              "temperature",
              "water",
              "other"
            ]
          },
          "unit": {
            "type": "string"
          },
          "sourceUnit": {
            "type": [
              "string",
              "null"
            ]
          },
          "value": {
            "type": [
              "number",
              "null"
            ]
          },
          "sourceValue": {
            "type": "string"
          }
        }
      },
      "Observation": {
        "type": "object",
        "required": [
          "observedAt",
          "measurements",
          "raw"
        ],
        "properties": {
          "observedAt": {
            "type": "string",
            "format": "date-time"
          },
          "measurements": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Measurement"
            }
          },
          "raw": {
            "type": "string"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "code",
          "error"
        ],
        "properties": {
          "ok": {
            "const": false
          },
          "code": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        }
      },
      "Feature": {
        "type": "object",
        "required": [
          "type",
          "id",
          "geometry",
          "properties"
        ],
        "properties": {
          "type": {
            "const": "Feature"
          },
          "id": {
            "type": "string"
          },
          "geometry": {
            "type": "object",
            "required": [
              "type",
              "coordinates"
            ],
            "properties": {
              "type": {
                "const": "Point"
              },
              "coordinates": {
                "type": "array",
                "minItems": 2,
                "maxItems": 2,
                "prefixItems": [
                  {
                    "type": "number",
                    "minimum": -180,
                    "maximum": 180
                  },
                  {
                    "type": "number",
                    "minimum": -90,
                    "maximum": 90
                  }
                ]
              }
            }
          },
          "properties": {
            "type": "object",
            "required": [
              "buoynet",
              "recordType",
              "stationId",
              "vertical",
              "positionSource"
            ],
            "properties": {
              "buoynet": {
                "const": true
              },
              "recordType": {
                "enum": [
                  "station",
                  "observation"
                ]
              },
              "stationId": {
                "type": "string"
              },
              "vertical": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "null"
                  },
                  "unit": {
                    "const": "m"
                  },
                  "positive": {
                    "const": "down"
                  },
                  "reference": {
                    "const": "unknown"
                  }
                }
              },
              "positionSource": {
                "type": "string"
              },
              "measurements": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Measurement"
                }
              }
            }
          }
        }
      },
      "FeatureCollection": {
        "type": "object",
        "required": [
          "type",
          "features"
        ],
        "properties": {
          "type": {
            "const": "FeatureCollection"
          },
          "features": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Feature"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "firebaseBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Existing registered Atlasemoji Firebase user ID token. Workspace edit access required."
      }
    }
  }
}
