{
  "openapi": "3.1.0",
  "info": {
    "title": "AxisDatum Research API",
    "version": "0.3.0",
    "description": "Public geographic observations, keyed USDA routes, and gated market-data contracts. Commerce, social and search-demand customer access is disabled until distribution rights and operating controls are confirmed. Model analysis is separately gated. No paid checkout or commercial SLA is enabled."
  },
  "servers": [
    {
      "url": "https://axisdatum.com",
      "description": "Cloudflare deployment"
    }
  ],
  "tags": [
    {
      "name": "System"
    },
    {
      "name": "Agriculture"
    },
    {
      "name": "Vessels"
    },
    {
      "name": "Aircraft"
    },
    {
      "name": "Market data",
      "description": "Integration-preview routes; customer distribution is disabled by default."
    },
    {
      "name": "Model analysis",
      "description": "Model-generated hypotheses, disabled until configured."
    }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "summary": "Health and catalog import timestamp",
        "tags": [
          "System"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/catalog": {
      "get": {
        "summary": "USDA regions, years and crop legends",
        "tags": [
          "Agriculture"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/history": {
      "get": {
        "summary": "Annual CDL classifications at one coordinate; rows contain independent per-year status",
        "tags": [
          "Agriculture"
        ],
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "description": "conus or hawaii; field geometry currently supports conus",
            "schema": {
              "type": "string",
              "example": "conus"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "Longitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": -93.6
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": 42.1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/field": {
      "get": {
        "summary": "Inferred CSB field polygon and 2015–2022 field majority crops",
        "tags": [
          "Agriculture"
        ],
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "description": "conus or hawaii; field geometry currently supports conus",
            "schema": {
              "type": "string",
              "example": "conus"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "Longitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": -93.6
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": 42.1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/vessels": {
      "get": {
        "summary": "Recently received AIS positions in a bounded view; not a complete census",
        "tags": [
          "Vessels"
        ],
        "parameters": [
          {
            "name": "client",
            "in": "query",
            "required": true,
            "description": "Session ID, 8–80 characters, used for temporary collection lease",
            "schema": {
              "type": "string",
              "example": "my-research-session"
            }
          },
          {
            "name": "bbox",
            "in": "query",
            "required": true,
            "description": "west,south,east,north in decimal degrees",
            "schema": {
              "type": "string",
              "example": "3.9,51.8,4.6,52.1"
            }
          },
          {
            "name": "release",
            "in": "query",
            "required": false,
            "description": "Set to 1 to release the session lease",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/vessels/history": {
      "get": {
        "summary": "Available Open Waters observations for one MMSI; follow nextBefore for older pages",
        "tags": [
          "Vessels"
        ],
        "parameters": [
          {
            "name": "mmsi",
            "in": "query",
            "required": true,
            "description": "Nine-digit MMSI",
            "schema": {
              "type": "string",
              "example": "123456789"
            }
          },
          {
            "name": "days",
            "in": "query",
            "required": true,
            "description": "Lookback window: 1, 7, 30, or 90",
            "schema": {
              "type": "string",
              "example": "30"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Millisecond cursor from nextBefore",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "end",
            "in": "query",
            "required": false,
            "description": "Millisecond timestamp from requestedTo, preserving the same window across pages",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/aircraft": {
      "get": {
        "summary": "Recent ADSB.lol observations in a bounded view",
        "tags": [
          "Aircraft"
        ],
        "parameters": [
          {
            "name": "bbox",
            "in": "query",
            "required": true,
            "description": "west,south,east,north in decimal degrees; wide views may require zoom",
            "schema": {
              "type": "string",
              "example": "3.9,51.8,4.6,52.1"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Provider or API capacity limit"
          },
          "502": {
            "description": "Upstream provider unavailable"
          }
        }
      }
    },
    "/api/tiles/{region}/{year}/{z}/{x}/{y}.png": {
      "get": {
        "summary": "USDA crop tile for a locked year",
        "tags": [
          "Agriculture"
        ],
        "parameters": [
          {
            "name": "region",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "year",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "z",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "x",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "y",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "crop",
            "in": "query",
            "required": false,
            "description": "Optional CDL class code",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PNG tile",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "description": "Invalid region, year, tile or crop code"
          },
          "502": {
            "description": "USDA imagery unavailable"
          }
        }
      }
    },
    "/v1/catalog": {
      "get": {
        "summary": "Keyed USDA catalog access",
        "tags": [
          "Agriculture"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Monthly trial quota reached"
          },
          "502": {
            "description": "Upstream provider unavailable"
          },
          "401": {
            "description": "Missing or revoked API key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/field": {
      "get": {
        "summary": "Keyed USDA field access",
        "tags": [
          "Agriculture"
        ],
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "description": "conus or hawaii; field geometry currently supports conus",
            "schema": {
              "type": "string",
              "example": "conus"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "Longitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": -93.6
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": 42.1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Monthly trial quota reached"
          },
          "502": {
            "description": "Upstream provider unavailable"
          },
          "401": {
            "description": "Missing or revoked API key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/history": {
      "get": {
        "summary": "Keyed USDA history access",
        "tags": [
          "Agriculture"
        ],
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "required": true,
            "description": "conus or hawaii; field geometry currently supports conus",
            "schema": {
              "type": "string",
              "example": "conus"
            }
          },
          {
            "name": "lon",
            "in": "query",
            "required": true,
            "description": "Longitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": -93.6
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": true,
            "description": "Latitude in decimal degrees",
            "schema": {
              "type": "number",
              "example": 42.1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "JSON response; source and coverage fields vary by dataset",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid query"
          },
          "429": {
            "description": "Monthly trial quota reached"
          },
          "502": {
            "description": "Upstream provider unavailable"
          },
          "401": {
            "description": "Missing or revoked API key"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    },
    "/v1/market/commerce/product": {
      "get": {
        "summary": "Amazon product listing snapshot",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommerceProductSnapshot"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/commerce/shop-product": {
      "get": {
        "summary": "TikTok Shop product listing snapshot",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CommerceProductSnapshot"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/social/x-post": {
      "get": {
        "summary": "Observed public X post",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialPost"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/social/tiktok-post": {
      "get": {
        "summary": "Observed public TikTok post",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialPost"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/social/x-profile": {
      "get": {
        "summary": "X public profile snapshot and available posts",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialProfileSnapshot"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "relatedPosts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialPost"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/social/tiktok-profile": {
      "get": {
        "summary": "Available TikTok public profile posts",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "url",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "description": "Supported public platform URL."
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/SocialPost"
                      }
                    },
                    "collectedAt": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Collection pending; poll the jobToken with the same key and respect Retry-After."
          }
        }
      }
    },
    "/v1/market/catalog": {
      "get": {
        "summary": "Connected and integration-preview family availability",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/market/domain-search": {
      "get": {
        "summary": "Estimated monthly search traffic, not total website visits",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "domain",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "example.com"
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DomainSearchEstimate"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/market/collections/{jobToken}": {
      "get": {
        "summary": "Poll an asynchronous collection using the original API key",
        "tags": [
          "Market data"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "parameters": [
          {
            "name": "jobToken",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Still collecting; Retry-After indicates poll interval."
          }
        }
      }
    },
    "/v1/market/social/analyze": {
      "post": {
        "summary": "Analyze user-supplied public post text into reviewable hypotheses",
        "tags": [
          "Model analysis"
        ],
        "security": [
          {
            "MarketKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Normalized observation, not a raw upstream response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MarketImpactHypothesis"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Missing or invalid API key"
          },
          "503": {
            "description": "Customer access is not enabled or a required credential is missing.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "postId",
                  "publishedAt",
                  "text"
                ],
                "properties": {
                  "postId": {
                    "type": "string"
                  },
                  "publishedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "text": {
                    "type": "string",
                    "maxLength": 5000
                  }
                }
              }
            }
          }
        },
        "description": "Model output requires human review. No trade is submitted. Available only when model analysis is explicitly enabled."
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "MarketKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "CommerceProductSnapshot": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "platform",
          "productId",
          "url",
          "title",
          "price",
          "currency",
          "availability",
          "rating",
          "reviewCount",
          "displayedRecentPurchases",
          "displayedSoldCount",
          "observedAt",
          "collectedAt",
          "limitations"
        ],
        "properties": {
          "type": {
            "const": "commerce_product_snapshot"
          },
          "platform": {
            "type": "string",
            "enum": [
              "amazon",
              "tiktok_shop"
            ]
          },
          "productId": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": [
              "number",
              "null"
            ]
          },
          "currency": {
            "type": [
              "string",
              "null"
            ]
          },
          "availability": {
            "type": [
              "string",
              "null"
            ]
          },
          "rating": {
            "type": [
              "number",
              "null"
            ]
          },
          "reviewCount": {
            "type": [
              "number",
              "null"
            ]
          },
          "displayedRecentPurchases": {
            "type": [
              "string",
              "null"
            ],
            "description": "Platform-displayed purchase indicator, not audited units sold."
          },
          "displayedSoldCount": {
            "type": [
              "number",
              "null"
            ],
            "description": "Platform-displayed sold count, not independently verified sales."
          },
          "observedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "collectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SocialPost": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "platform",
          "postId",
          "authorHandle",
          "url",
          "text",
          "publishedAt",
          "collectedAt",
          "engagement",
          "limitations"
        ],
        "properties": {
          "type": {
            "const": "social_post"
          },
          "platform": {
            "type": "string",
            "enum": [
              "x",
              "tiktok"
            ]
          },
          "postId": {
            "type": [
              "string",
              "null"
            ]
          },
          "authorHandle": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "text": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "collectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "engagement": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "likes": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "shares": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "comments": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "views": {
                "type": [
                  "number",
                  "null"
                ]
              }
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "DomainSearchEstimate": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "domain",
          "geography",
          "searchEngine",
          "estimatedMonthlyOrganicSearchVisits",
          "estimatedMonthlyPaidSearchVisits",
          "rankingOrganicKeywords",
          "observedAt",
          "collectedAt",
          "updateCadence",
          "limitations"
        ],
        "properties": {
          "type": {
            "const": "domain_search_estimate"
          },
          "domain": {
            "type": "string"
          },
          "geography": {
            "type": "string"
          },
          "searchEngine": {
            "type": "string"
          },
          "estimatedMonthlyOrganicSearchVisits": {
            "type": [
              "number",
              "null"
            ]
          },
          "estimatedMonthlyPaidSearchVisits": {
            "type": [
              "number",
              "null"
            ]
          },
          "rankingOrganicKeywords": {
            "type": [
              "number",
              "null"
            ]
          },
          "observedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "collectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "updateCadence": {
            "type": "string",
            "enum": [
              "weekly"
            ]
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "MarketImpactHypothesis": {
        "type": "object",
        "required": [
          "type",
          "postId",
          "publishedAt",
          "analyzedAt",
          "model",
          "status",
          "analysis"
        ],
        "properties": {
          "type": {
            "const": "market_impact_hypothesis"
          },
          "postId": {
            "type": "string"
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "analyzedAt": {
            "type": "string",
            "format": "date-time"
          },
          "model": {
            "type": "string"
          },
          "status": {
            "const": "requires_human_review"
          },
          "analysis": {
            "type": "object",
            "required": [
              "sentiment",
              "topics",
              "summary",
              "assets",
              "uncertainty"
            ],
            "properties": {
              "sentiment": {
                "type": "string",
                "enum": [
                  "positive",
                  "negative",
                  "mixed",
                  "neutral",
                  "uncertain"
                ]
              },
              "topics": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "summary": {
                "type": "string"
              },
              "assets": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "symbol": {
                      "type": "string"
                    },
                    "direction": {
                      "type": "string",
                      "enum": [
                        "potential_upside",
                        "potential_downside",
                        "scenario_dependent",
                        "unclear"
                      ]
                    },
                    "rationale": {
                      "type": "string"
                    },
                    "counterargument": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "number"
                    }
                  }
                }
              },
              "uncertainty": {
                "type": "string"
              }
            }
          }
        }
      },
      "SocialProfileSnapshot": {
        "type": "object",
        "required": [
          "type",
          "platform",
          "profileId",
          "handle",
          "url",
          "followers",
          "postCount",
          "observedAt",
          "collectedAt",
          "limitations"
        ],
        "properties": {
          "type": {
            "const": "social_profile_snapshot"
          },
          "platform": {
            "const": "x"
          },
          "profileId": {
            "type": [
              "string",
              "null"
            ]
          },
          "handle": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "followers": {
            "type": [
              "number",
              "null"
            ]
          },
          "postCount": {
            "type": [
              "number",
              "null"
            ]
          },
          "observedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "collectedAt": {
            "type": "string",
            "format": "date-time"
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}