{"components":{"headers":{"RateLimitHeaders":{"description":"Rate limit response headers","schema":{"properties":{"X-RateLimit-Limit":{"description":"Maximum requests per minute for this tier","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in current window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit window resets","schema":{"type":"integer"}}},"type":"object"}}},"responses":{"NotFound":{"content":{"application/json":{"example":{"error":"not_found"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Resource not found"},"RateLimited":{"content":{"application/json":{"example":{"error":"rate_limited","retry_after":47},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds until rate limit resets","schema":{"type":"integer"}}}},"ServiceUnavailable":{"content":{"application/json":{"example":{"error":"service_unavailable"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Service temporarily unavailable"},"Unauthorized":{"content":{"application/json":{"example":{"error":"unauthorized"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Missing or invalid authentication"}},"schemas":{"AnnotationCreateRequest":{"properties":{"agent_id":{"description":"Identifier for the posting agent or service","type":"string"},"annotation":{"description":"Interpretive text. Should include: observation, supporting evidence, confidence statement, and any caveats.","maxLength":2000,"type":"string"},"confidence":{"description":"0.0-1.0. Be honest \u2014 low confidence annotations are valuable if clearly labeled.","maximum":1,"minimum":0,"type":"number"},"expires":{"description":"When this annotation expires. Max: 7 days. Expired annotations are hidden but not deleted.","format":"date-time","type":"string"},"region":{"description":"Geographic scope. If omitted, annotation is global.","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"radius_km":{"type":"number"}},"type":"object"},"severity":{"default":"informational","enum":["informational","watch","elevated","critical"],"type":"string"},"source":{"description":"Stream ID this annotation is attached to (e.g. eq_magnitude)","type":"string"},"source_data":{"description":"Source IDs used to produce this annotation","items":{"type":"string"},"type":"array"},"tags":{"description":"Free-form tags for filtering and discovery (cascade IDs, event names, source keys)","items":{"type":"string"},"type":"array"}},"required":["source","annotation","agent_id"],"type":"object"},"AnnotationListResponse":{"properties":{"annotations":{"items":{"$ref":"#/components/schemas/AnnotationResponse"},"type":"array"},"count":{"type":"integer"}},"type":"object"},"AnnotationResponse":{"properties":{"active":{"type":"boolean"},"agent_id":{"type":"string"},"annotation":{"type":"string"},"confidence":{"type":"number"},"created_at":{"format":"date-time","type":"string"},"expires":{"format":"date-time","type":["string","null"]},"id":{"type":"string"},"region":{"type":"object"},"severity":{"type":"string"},"source":{"type":"string"},"tags":{"items":{"type":"string"},"type":"array"}},"type":"object"},"AttributionEntry":{"properties":{"category":{"type":"string"},"id":{"type":"string"},"license":{"type":"string"},"name":{"type":"string"},"provider":{"type":"string"},"update_frequency":{"type":"string"},"url":{"format":"uri","type":"string"}},"type":"object"},"AttributionResponse":{"properties":{"attributions":{"items":{"$ref":"#/components/schemas/AttributionEntry"},"type":"array"},"count":{"type":"integer"},"notice":{"type":"string"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"BriefingCondition":{"description":"Compact watch-level anomaly condition included in a deterministic briefing","properties":{"category":{"type":["string","null"]},"confidence":{"type":["string","null"]},"distance_km":{"type":["number","null"]},"level":{"enum":["watch","elevated","critical"],"type":"string"},"percentile":{"type":["number","null"]},"source_id":{"type":"string"},"summary":{"type":"string"},"unit":{"type":["string","null"]},"value":{"type":["number","string","null"]}},"type":"object"},"BriefingGlobalResponse":{"properties":{"_meta":{"$ref":"#/components/schemas/BriefingMeta"},"active_cascades":{"description":"IDs of cascade sequences currently triggered or monitoring","items":{"type":"string"},"type":"array"},"confidence_global":{"maximum":1,"minimum":0,"type":"number"},"data_gaps":{"items":{"$ref":"#/components/schemas/DataGap"},"type":"array"},"domain_status":{"additionalProperties":{"enum":["normal","watch","elevated","critical"],"type":"string"},"description":"Current status per domain","type":"object"},"highlights":{"description":"Notable events ordered by anomaly severity","items":{"$ref":"#/components/schemas/Highlight"},"type":"array"},"sources_used":{"items":{"type":"string"},"type":"array"},"summary":{"description":"Top-level narrative summary of global conditions","type":"string"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"BriefingMeta":{"description":"Metadata envelope present on all briefing responses","properties":{"anomaly_count":{"type":"integer"},"cache_age_seconds":{"type":"integer"},"cache_ttl_seconds":{"type":"integer"},"cached":{"type":"boolean"},"data_freshness":{"enum":["good","degraded","stale"],"type":"string"},"degraded_mode":{"type":"boolean"},"detail":{"type":"string"},"endpoint":{"type":"string"},"framework":{"type":"string"},"generated_at":{"format":"date-time","type":"string"},"model":{"description":"Claude model used for generation","type":"string"},"next_refresh":{"format":"date-time","type":"string"},"sources_fresh":{"type":"integer"},"sources_polled":{"type":"integer"},"sources_stale":{"type":"integer"},"stale":{"description":"True if serving stale content beyond TTL","type":"boolean"},"stale_reason":{"enum":["regeneration_in_progress","ai_backend_unavailable"],"type":"string"}},"type":"object"},"BriefingRegionResponse":{"properties":{"_meta":{"$ref":"#/components/schemas/BriefingMeta"},"active_cascades":{"items":{"type":"string"},"type":"array"},"anomaly_summary":{"type":"string"},"confidence_regional":{"type":"number"},"location":{"properties":{"city":{"type":["string","null"]},"country":{"type":["string","null"]},"lat":{"type":"number"},"lon":{"type":"number"},"radius_km":{"type":"integer"},"timezone":{"type":["string","null"]}},"type":"object"},"next_monitoring_window":{"type":"string"},"sections":{"description":"Domain sections ordered by city's primary_hazard then anomaly severity","items":{"$ref":"#/components/schemas/BriefingSection"},"type":"array"},"sources_used":{"items":{"type":"string"},"type":"array"},"summary":{"type":"string"}},"type":"object"},"BriefingResponse":{"description":"Deterministic structured location briefing produced from the live anomaly engine","properties":{"cached":{"type":"boolean"},"conditions":{"items":{"$ref":"#/components/schemas/BriefingCondition"},"type":"array"},"generated_at":{"format":"date-time","type":"string"},"headline":{"type":"string"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"},"name":{"type":"string"}},"required":["lat","lon"],"type":"object"},"normal_count":{"type":"integer"},"radius_km":{"type":"number"},"risk":{"properties":{"level":{"enum":["normal","watch","elevated","critical"],"type":"string"},"score":{"maximum":100,"minimum":0,"type":"integer"}},"required":["score","level"],"type":"object"},"sources_consulted":{"type":"integer"},"sources_unavailable":{"type":"integer"}},"required":["location","radius_km","risk","headline","conditions","normal_count","sources_consulted","sources_unavailable","generated_at","cached"],"type":"object"},"BriefingSection":{"properties":{"confidence":{"type":"number"},"content":{"type":"string"},"domain":{"type":"string"},"id":{"type":"string"},"metrics":{"additionalProperties":true,"description":"Domain-specific key metrics as key-value pairs","type":"object"},"priority_rank":{"type":"integer"},"status":{"enum":["normal","watch","elevated","critical"],"type":"string"}},"type":"object"},"BriefingSourceResponse":{"properties":{"_meta":{"$ref":"#/components/schemas/BriefingMeta"},"baseline_comparison":{"properties":{"anomaly_level":{"type":"string"},"baseline_30d_mean":{"type":"number"},"baseline_30d_stddev":{"type":"number"},"current_24h":{"type":"number"},"deviation_pct":{"type":"number"},"z_score":{"type":"number"}},"type":"object"},"correlation_context":{"items":{"properties":{"check":{"type":"string"},"correlation_id":{"type":"string"},"current_status":{"type":"string"},"relevant_if":{"type":"string"}},"type":"object"},"type":"array"},"current_extremes":{"additionalProperties":true,"description":"Current max/min events \u2014 schema varies by source domain","type":"object"},"source_profile":{"properties":{"coverage":{"type":"string"},"data_freshness":{"type":"string"},"display_name":{"type":"string"},"last_fetch":{"format":"date-time","type":"string"},"provider":{"type":"string"},"reliability_score":{"type":"number"},"update_interval_minutes":{"type":"integer"}},"type":"object"},"summary":{"type":"string"},"trend_48h":{"properties":{"period_end":{"format":"date-time","type":"string"},"period_start":{"format":"date-time","type":"string"},"trend_direction":{"enum":["increasing","decreasing","stable"],"type":"string"},"trend_driver":{"type":"string"}},"type":"object"}},"type":"object"},"DataGap":{"properties":{"impact":{"type":"string"},"issue":{"type":"string"},"source":{"type":"string"}},"type":"object"},"DataRangeResponse":{"properties":{"ranges":{"additionalProperties":{"properties":{"earliest":{"format":"date-time","type":"string"},"latest":{"format":"date-time","type":"string"},"snapshot_count":{"type":"integer"}},"type":"object"},"description":"Map of source_id to archive range","type":"object"},"sources_archived":{"type":"integer"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"Error400":{"properties":{"error":{"type":"string"},"usage":{"description":"Example of correct usage","type":"string"}},"type":"object"},"ErrorGeneric":{"properties":{"detail":{"type":"string"},"error":{"type":"string"},"hint":{"type":"string"}},"required":["error"],"type":"object"},"HealthResponse":{"properties":{"stale_critical":{"description":"Sources with data age > 10\u00d7 expected interval \u2014 likely broken","items":{"$ref":"#/components/schemas/StaleSourceEntry"},"type":"array"},"stale_warning":{"description":"Sources with data age > 3\u00d7 expected interval","items":{"$ref":"#/components/schemas/StaleSourceEntry"},"type":"array"},"status":{"description":"ok = no critical staleness; degraded = one or more sources critically stale","enum":["ok","degraded"],"type":"string"},"streams_shared":{"type":"integer"},"streams_with_data":{"type":"integer"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"Highlight":{"description":"A notable event or anomaly in the briefing","properties":{"active_cascades":{"items":{"type":"string"},"type":"array"},"anomaly_score":{"maximum":1,"minimum":0,"type":"number"},"cascade_status":{"type":"string"},"confidence":{"maximum":1,"minimum":0,"type":"number"},"detail":{"type":"string"},"domain":{"type":"string"},"headline":{"type":"string"},"id":{"type":"string"},"lat":{"type":["number","null"]},"lon":{"type":["number","null"]},"radius_km":{"type":["number","null"]},"severity":{"enum":["normal","watch","elevated","critical"],"type":"string"},"source_keys":{"items":{"type":"string"},"type":"array"}},"type":"object"},"Point":{"additionalProperties":true,"description":"A single geospatial data point. Required fields: lat, lon, value. Additional fields vary by source (depth_km for earthquakes, altitude for flights, etc.)","properties":{"distance_km":{"description":"Present when geo-filtering is active \u2014 great-circle distance from query point","type":"number"},"lat":{"maximum":90,"minimum":-90,"type":"number"},"lon":{"maximum":180,"minimum":-180,"type":"number"},"nearest_neighbor":{"description":"true if this point was returned as a nearest-neighbor fallback (no points within radius)","type":"boolean"},"value":{"description":"Primary numeric value for this stream","type":["number","null"]}},"required":["lat","lon"],"type":"object"},"SchemaReportResponse":{"properties":{"recent_changes":{"description":"Last 20 schema change events","items":{"properties":{"change_type":{"type":"string"},"detail":{"type":"string"},"source":{"type":"string"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"type":"array"},"sources":{"additionalProperties":{"properties":{"field_count":{"type":"integer"},"last_checked":{"format":"date-time","type":"string"},"point_count":{"type":"integer"}},"type":"object"},"type":"object"},"sources_tracked":{"type":"integer"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"SourceStatusAllResponse":{"properties":{"sources":{"additionalProperties":{"$ref":"#/components/schemas/SourceStatusSingleResponse"},"description":"Map of source_id to SourceStatusSingleResponse","type":"object"},"summary":{"properties":{"backed_off":{"type":"integer"},"failing":{"type":"integer"},"healthy":{"type":"integer"},"never_fetched":{"type":"integer"},"total":{"type":"integer"}},"type":"object"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"SourceStatusSingleResponse":{"properties":{"avg_duration_ms":{"type":"number"},"backoff_until":{"format":"date-time","type":["string","null"]},"consecutive_failures":{"type":"integer"},"first_fetched":{"format":"date-time","type":["string","null"]},"history":{"description":"Ring buffer of last 20 fetch attempts","items":{"properties":{"duration_ms":{"type":"number"},"error":{"type":["string","null"]},"success":{"type":"boolean"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"maxItems":20,"type":"array"},"last_fetched":{"format":"date-time","type":["string","null"]},"status":{"enum":["ok","failing","unknown"],"type":"string"},"uptime_pct":{"type":"number"}},"type":"object"},"SourceSummary":{"description":"Aggregated summary for one source, optionally geo-filtered","properties":{"category":{"type":"string"},"count":{"description":"Number of points in response (after geo-filter)","type":"integer"},"max":{"type":"number"},"mean":{"type":"number"},"min":{"description":"Minimum value across all points in response. Omitted if no numeric values.","type":"number"},"name":{"type":"string"},"nearest":{"description":"The single nearest point to the query location","properties":{"distance_km":{"type":"number"},"lat":{"type":"number"},"lon":{"type":"number"},"value":{"type":["number","null"]}},"type":"object"},"nearest_distance_km":{"type":"number"},"nearest_neighbor":{"type":"boolean"},"note":{"description":"Human-readable note, e.g. nearest-neighbor fallback explanation","type":"string"},"source_id":{"type":"string"},"timestamp":{"description":"When this source's data was last fetched","format":"date-time","type":"string"}},"type":"object"},"StaleSourceEntry":{"properties":{"age_hours":{"type":"number"},"expected_interval":{"type":"string"},"source":{"type":"string"}},"type":"object"},"StreamCatalogResponse":{"properties":{"streams":{"additionalProperties":{"items":{"$ref":"#/components/schemas/StreamEntry"},"type":"array"},"description":"Streams grouped by category name","type":"object"},"timestamp":{"format":"date-time","type":"string"},"total":{"type":"integer"}},"type":"object"},"StreamDataResponse":{"properties":{"count":{"description":"Points returned (after geo-filter and limit)","type":"integer"},"name":{"type":"string"},"points":{"items":{"$ref":"#/components/schemas/Point"},"type":"array"},"stream_id":{"type":"string"},"timestamp":{"format":"date-time","type":["string","null"]},"total_available":{"description":"Total points in cache before filtering","type":"integer"}},"type":"object"},"StreamEntry":{"properties":{"color":{"description":"Hex color for visualization","type":"string"},"count":{"description":"Current point count in cache","type":"integer"},"description":{"type":"string"},"has_data":{"description":"Whether data has been fetched for this stream","type":"boolean"},"id":{"description":"Unique source identifier (snake_case)","type":"string"},"name":{"type":"string"},"timestamp":{"format":"date-time","type":["string","null"]},"unit":{"description":"Unit of measurement (e.g. \u00b0C, magnitude Mw, ft)","type":"string"}},"type":"object"},"StreamSearchResponse":{"properties":{"count":{"type":"integer"},"query":{"type":"string"},"results":{"items":{"properties":{"category":{"type":"string"},"count":{"type":"integer"},"description":{"type":"string"},"has_data":{"type":"boolean"},"id":{"type":"string"},"name":{"type":"string"}},"type":"object"},"type":"array"}},"type":"object"},"SubscriptionCreateRequest":{"properties":{"anomaly_z_score":{"description":"Required when trigger_type=anomaly_score. Alert when Z-score >= this. Typical: 1.5 (elevated), 2.5 (critical).","type":"number"},"cascade_id":{"description":"Required when trigger_type=cascade. E.g. cascade_001 (coastal earthquake\u2192tsunami). See burnbot-output/anomaly-patterns/cascade-rules.yaml for full list.","type":"string"},"cooldown_seconds":{"default":3600,"description":"Minimum seconds between deliveries for the same event. Prevents alert storms during sustained events.","type":"integer"},"description":{"type":"string"},"location_filter":{"description":"Optional geographic scope for the trigger. If omitted, global scope.","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"radius_km":{"type":"number"}},"type":"object"},"min_severity":{"default":"elevated","description":"Minimum severity level to trigger delivery","enum":["watch","elevated","critical"],"type":"string"},"name":{"description":"Human-readable label for this subscription","type":"string"},"source_id":{"description":"Required when trigger_type=threshold or anomaly_score. Stream ID to monitor.","type":"string"},"threshold_operator":{"default":"gte","enum":["gte","lte","gt","lt"],"type":"string"},"threshold_value":{"description":"Required when trigger_type=threshold. Alert when source value >= this.","type":"number"},"trigger_type":{"description":"cascade: fires when a cascade sequence is triggered. threshold: fires when a source value exceeds a threshold. anomaly_score: fires when Z-score exceeds threshold.","enum":["cascade","threshold","anomaly_score"],"type":"string"},"webhook_secret":{"description":"Optional HMAC-SHA256 signing secret. If provided, all webhook deliveries include X-Orbital-Signature header.","type":"string"},"webhook_url":{"description":"HTTPS URL to receive POST notifications. Must be publicly reachable.","format":"uri","type":"string"}},"required":["trigger_type","webhook_url"],"type":"object"},"SubscriptionListResponse":{"properties":{"count":{"type":"integer"},"subscriptions":{"items":{"$ref":"#/components/schemas/SubscriptionResponse"},"type":"array"}},"type":"object"},"SubscriptionResponse":{"properties":{"created_at":{"format":"date-time","type":"string"},"id":{"type":"string"},"last_triggered":{"format":"date-time","type":["string","null"]},"name":{"type":"string"},"status":{"enum":["active","suspended","paused"],"type":"string"},"trigger_count":{"type":"integer"},"trigger_type":{"type":"string"},"webhook_url":{"type":"string"}},"type":"object"},"ValidationReportResponse":{"properties":{"details":{"additionalProperties":{"type":"object"},"description":"Per-source validation stats: output_count, dropped_latlon, clipped_values, field_ranges","type":"object"},"issue_count":{"type":"integer"},"issues":{"items":{"properties":{"detail":{"type":"string"},"issue":{"enum":["volume_anomaly","bad_coordinates","out_of_range"],"type":"string"},"source":{"type":"string"}},"type":"object"},"type":"array"},"sources_checked":{"type":"integer"},"timestamp":{"format":"date-time","type":"string"}},"type":"object"},"WebhookEventPayload":{"description":"Payload delivered to subscriber webhook URLs when a trigger fires","properties":{"affected_region":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"},"radius_km":{"type":"number"}},"type":"object"},"cascade_id":{"type":["string","null"]},"cascade_name":{"type":["string","null"]},"cascade_steps":{"description":"Next steps in the cascade sequence to monitor. Only present for cascade_trigger events.","items":{"properties":{"description":{"type":"string"},"expected_delay_hours":{"description":"[min_hours, max_hours] expected delay before this step","items":{"type":"number"},"maxItems":2,"minItems":2,"type":"array"},"source":{"type":"string"},"status":{"enum":["monitoring","triggered","expired"],"type":"string"},"step":{"type":"integer"}},"type":"object"},"type":"array"},"confidence":{"maximum":1,"minimum":0,"type":"number"},"data_snapshot_url":{"description":"Pre-formed URL to fetch current world-state data for the affected region. Copy-paste into /api/v1/world for context.","format":"uri","type":"string"},"delivery_attempt":{"maximum":3,"minimum":1,"type":"integer"},"event_id":{"description":"Unique event ID","type":"string"},"event_type":{"enum":["cascade_trigger","threshold_crossed","anomaly_detected"],"type":"string"},"severity":{"enum":["watch","elevated","critical"],"type":"string"},"subscription_id":{"type":"string"},"timestamp":{"format":"date-time","type":"string"},"trigger":{"properties":{"description":{"type":"string"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"},"source":{"type":"string"},"threshold":{"type":["number","null"]},"value":{"type":"number"}},"type":"object"}},"required":["event_id","subscription_id","event_type","timestamp","severity"],"type":"object"},"WorldStateResponse":{"properties":{"attribution":{"description":"URL for attribution data","type":"string"},"location":{"properties":{"lat":{"type":"number"},"lon":{"type":"number"}},"type":"object"},"radius_km":{"type":"number"},"sources":{"description":"Number of sources with data in response","type":"integer"},"state":{"additionalProperties":{"items":{"$ref":"#/components/schemas/SourceSummary"},"type":"array"},"description":"Sources grouped by category (snake_case category keys). Each key maps to an array of SourceSummary objects.","type":"object"},"timestamp":{"format":"date-time","type":"string"},"total_points":{"description":"Total data points across all sources","type":"integer"}},"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"description":"API key header. Alternative to JWT for server-to-server integrations. Key issued per account.","in":"header","name":"X-API-Key","type":"apiKey"},"BearerAuth":{"bearerFormat":"JWT","description":"JWT bearer token obtained from /auth/login. Include as `Authorization: Bearer <token>`. Current endpoints do not enforce auth on read-only data endpoints, but briefing and subscription endpoints require it.","scheme":"bearer","type":"http"},"X402Payment":{"description":"x402 micropayment protocol (EIP-7702 compatible). Pass a signed payment payload in USDC on Base or Solana. No account required. Per-call billing: $0.001 (cached briefing), $0.005 (global briefing), $0.010 (regional briefing). See x402-research/ for full protocol spec.","in":"header","name":"X-Payment-Payload","type":"apiKey"}}},"info":{"contact":{"name":"Orbital Streams","url":"https://orbitalstreams.com"},"description":"Real-time global data API aggregating 125 live streams across 7 categories: Earth & Climate, Geology & Space, Disasters & Events, Human Activity, Humanitarian, Nature, and Infrastructure. One normalized interface for earthquakes, weather, flights, ships, fires, ocean temps, conflicts, biodiversity, and more.\n\n**For AI agents:** Use `/api/v1/world?lat=LAT&lon=LON` as your first call \u2014 it returns multi-domain situational awareness in one request. Use `/api/v1/briefing?lat=LAT&lon=LON` for a deterministic structured risk summary. Use `/api/v1/streams` to discover available data streams. Use `/api/v1/subscriptions` to receive push notifications when anomalies occur.\n\n**Rate limits:** 60 req/min on all endpoints. Briefing endpoints have separate per-tier limits. See `X-RateLimit-*` response headers.\n\n**Authentication:** Bearer JWT for most endpoints. API key via `X-API-Key` header. x402 micropayment (USDC) for per-call agent access \u2014 no signup required.\n\n**Data freshness:** All data sourced from public APIs, cached in Redis (live) and TimescaleDB (48h archive). Each source has its own fetch interval (5min \u2192 24h). Check `timestamp` fields and `/api/v1/health` for staleness status.","license":{"name":"Data sourced from third-party providers \u2014 see /api/v1/attribution","url":"https://orbitalstreams.com/api/v1/attribution"},"title":"Orbital Streams World State API","version":"1.0.0","x-agent-context":{"attribution_endpoint":"GET /api/v1/attribution","attribution_required":true,"categories":["earth_climate","geology_space","disasters_events","human_activity","humanitarian","nature","infrastructure"],"data_type":"real_time_geospatial","discovery_endpoint":"GET /api/v1/streams","primary_use_case":"world_state_monitoring","recommended_first_call":"GET /api/v1/world?lat={lat}&lon={lon}","stream_count":125}},"openapi":"3.1.0","paths":{"/annotations":{"get":{"description":"Returns annotations posted by agents, optionally filtered by location, source, agent_id, or time range. Annotations are interpretive context that agents attach to world-state data.\n\n**Status:** PLANNED \u2014 not yet implemented. Vision-layer capability from AI_LAYER_ROADMAP.md section 6.","operationId":"listAnnotations","parameters":[{"in":"query","name":"lat","required":false,"schema":{"format":"float","type":"number"}},{"in":"query","name":"lon","required":false,"schema":{"format":"float","type":"number"}},{"in":"query","name":"radius_km","required":false,"schema":{"default":500,"type":"number"}},{"description":"Filter by source ID (e.g. eq_magnitude)","in":"query","name":"source","required":false,"schema":{"type":"string"}},{"description":"Filter by posting agent ID","in":"query","name":"agent_id","required":false,"schema":{"type":"string"}},{"description":"Minimum confidence score (0.0 to 1.0)","in":"query","name":"min_confidence","required":false,"schema":{"maximum":1,"minimum":0,"type":"number"}},{"description":"If true, only return annotations that have not yet expired","in":"query","name":"active_only","required":false,"schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationListResponse"}}},"description":"Annotation list"}},"summary":"List agent annotations [PLANNED]","tags":["annotations"],"x-status":"planned"},"post":{"description":"Agents post interpretive context to the shared world-state blackboard. Annotations are visible to other agents and human users. They expire automatically (max TTL: 7 days).\n\n**Status:** PLANNED \u2014 not yet implemented.\n\n**Use case:** A seismic monitoring agent detects a foreshock pattern and posts an annotation flagging elevated M7+ risk for the next 48h. Other agents and users see this context alongside the raw earthquake data.","operationId":"createAnnotation","requestBody":{"content":{"application/json":{"example":{"agent_id":"orbital-seismic-monitor-v1","annotation":"Foreshock pattern detected: 12 events M2.5+ in 6h near Tokyo, 2x 30-day baseline. Consistent with precursor sequences for M6+ events in this tectonic setting. Confidence: low \u2014 no reliable short-term earthquake prediction exists, but pattern is worth monitoring.","confidence":0.35,"expires":"2026-03-20T14:30:00Z","region":{"lat":35.6762,"lon":139.6503,"radius_km":500},"severity":"watch","source":"eq_magnitude","source_data":["eq_magnitude","eq_depth","eq_gap"],"tags":["foreshock","seismic","Tokyo","cascade_002"]},"schema":{"$ref":"#/components/schemas/AnnotationCreateRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnotationResponse"}}},"description":"Annotation created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Invalid annotation (missing required fields, TTL too long, confidence out of range)"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Post an agent annotation to the world-state [PLANNED]","tags":["annotations"],"x-status":"planned"}},"/attribution":{"get":{"description":"Returns provider, license, source URL, and update frequency for every shared data stream. Required for API consumers to comply with upstream data license terms.\n\n**AI agent usage:** Include attribution data when presenting Orbital Streams data to end users or downstream systems. Most sources are Creative Commons or open government data, but some have specific attribution requirements.","operationId":"getAttribution","responses":{"200":{"content":{"application/json":{"example":{"attributions":[{"category":"Geology & Space","id":"eq_magnitude","license":"Public Domain (US Government)","name":"Earthquake Magnitude","provider":"USGS Earthquake Hazards Program","update_frequency":"5 minutes","url":"https://earthquake.usgs.gov/earthquakes/feed/v1.0/geojson.php"}],"count":109,"notice":"Data is provided by third-party sources. Please respect individual license terms.","timestamp":"2026-03-18T14:30:00Z"},"schema":{"$ref":"#/components/schemas/AttributionResponse"}}},"description":"Full attribution list"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Attribution and licensing for all data sources","tags":["attribution"]}},"/briefing":{"get":{"description":"Returns a compact, deterministic briefing for a location. Pass either `lat` + `lon` or `location=<city>` matching the curated city-profile list. This endpoint uses the live anomaly engine and returns structured risk, headline, and ranked watch-level conditions. It does not call an LLM.","operationId":"getBriefing","parameters":[{"description":"Latitude. If both lat and lon are provided, they take precedence over location.","example":35.68,"in":"query","name":"lat","required":false,"schema":{"format":"float","maximum":90,"minimum":-90,"type":"number"}},{"description":"Longitude. Required with lat when using coordinate lookup.","example":139.69,"in":"query","name":"lon","required":false,"schema":{"format":"float","maximum":180,"minimum":-180,"type":"number"}},{"description":"Case-insensitive exact city-profile name, e.g. Tokyo. This is curated lookup, not geocoding.","example":"Tokyo","in":"query","name":"location","required":false,"schema":{"type":"string"}},{"description":"Optional JMESPath projection expression applied to the response.","example":"risk","in":"query","name":"fields","required":false,"schema":{"type":"string"}},{"description":"If true, collapse long arrays after projection.","in":"query","name":"summary","required":false,"schema":{"default":false,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"cached":false,"conditions":[{"category":"earth_climate","confidence":"medium","distance_km":4.2,"level":"elevated","percentile":97.2,"source_id":"temperature","summary":"Elevated condition from Temperature","unit":"C","value":34.1}],"generated_at":"2026-06-28T00:00:00Z","headline":"Elevated: 2 watch-level condition(s) near Tokyo","location":{"lat":35.6762,"lon":139.6503,"name":"Tokyo"},"normal_count":12,"radius_km":500,"risk":{"level":"elevated","score":42},"sources_consulted":14,"sources_unavailable":3},"schema":{"$ref":"#/components/schemas/BriefingResponse"}}},"description":"Structured location briefing","headers":{"$ref":"#/components/headers/RateLimitHeaders"}},"400":{"content":{"application/json":{"example":{"error":"location name or lat and lon are required","usage":"/api/v1/briefing?location=Tokyo or /api/v1/briefing?lat=35.68&lon=139.69"},"schema":{"$ref":"#/components/schemas/Error400"}}},"description":"Missing location or unknown curated city name"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Deterministic structured location briefing","tags":["briefing"]}},"/briefing/global":{"get":{"description":"Returns an AI-generated multi-domain world situation report across all active sources. Sections are ordered by current anomaly severity. Includes highlights for elevated events, domain status grid, active cascade warnings, and overall confidence score.\n\n**Status:** PLANNED \u2014 not yet implemented. Documented here for discovery by agent frameworks and to communicate the product roadmap.\n\n**Caching:** Briefings are AI-generated and cached (default 600s / 10 min). Cache hits are served immediately at no AI generation cost. Active anomalies trigger a 300s TTL override. The `_meta.cached` and `_meta.cache_age_seconds` fields communicate freshness.\n\n**Frameworks:** `standard` = general purpose. `emergency` = factual, action-oriented. `creative` = poetic spatial language. `technical` = raw metric context. `minimal` = plain text, machine-embeddable.","operationId":"getBriefingGlobal","parameters":[{"description":"Narrative framework. standard=general; emergency=action-oriented; creative=spatial/poetic; technical=metric-focused; minimal=plain text for LLM ingestion","in":"query","name":"framework","required":false,"schema":{"default":"standard","enum":["standard","emergency","creative","technical","minimal"],"type":"string"}},{"description":"Verbosity level. oneliner=single sentence; paragraph=3-5 sentences; full=complete report with all sections","in":"query","name":"detail","required":false,"schema":{"default":"paragraph","enum":["oneliner","paragraph","full"],"type":"string"}},{"description":"Domain scope filter. all=all categories; specify domain to get a focused briefing","in":"query","name":"focus","required":false,"schema":{"default":"all","enum":["all","geology","climate","disasters","aviation","maritime","humanitarian","infrastructure","space"],"type":"string"}},{"in":"query","name":"include_confidence","required":false,"schema":{"default":true,"type":"boolean"}},{"in":"query","name":"include_sources","required":false,"schema":{"default":true,"type":"boolean"}},{"in":"query","name":"include_cascades","required":false,"schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingGlobalResponse"}}},"description":"Global briefing (may be cached)","headers":{"X-Briefing-Cache-Hit":{"description":"true if response was served from cache","schema":{"type":"boolean"}},"X-Briefing-Generated":{"description":"ISO timestamp when briefing was generated","schema":{"format":"date-time","type":"string"}},"X-Briefing-Model":{"description":"AI model used for generation (e.g. claude-haiku-4-5-20251001)","schema":{"type":"string"}},"X-RateLimit-Limit":{"description":"Rate limit for this tier","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp when rate limit resets","schema":{"type":"integer"}}}},"206":{"description":"Partial briefing \u2014 some sources unavailable, data_gaps array populated"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"AI backend unavailable \u2014 stale briefing served with degraded_mode: true in _meta"}},"summary":"AI-generated global world situation report [PLANNED]","tags":["briefing"],"x-implementation-notes":"Implement as dashboard/api_v1/briefing.py. Requires ANTHROPIC_API_KEY env var. Claude Haiku for standard/creative/technical, Sonnet for emergency. Redis cache key: briefing:global:{framework}:{detail}:{focus}","x-status":"planned"}},"/briefing/region":{"get":{"description":"Returns a location-scoped intelligence briefing. Uses city profile data (from burnbot city-profiles task) to contextualize anomaly thresholds \u2014 e.g. 'what's normal for Tokyo in March' vs raw values.\n\n**Status:** PLANNED \u2014 not yet implemented.\n\n**AI agent usage:** This is the highest-value endpoint for location-specific agents. Pass `lat` + `lon` or a `city` name. The response includes: current conditions, anomaly detection vs location-specific baselines, active cascade monitoring, next monitoring windows, and confidence scores.","operationId":"getBriefingRegion","parameters":[{"description":"Latitude. Either lat+lon or city is required.","in":"query","name":"lat","required":false,"schema":{"format":"float","maximum":90,"minimum":-90,"type":"number"}},{"description":"Longitude. Either lat+lon or city is required.","in":"query","name":"lon","required":false,"schema":{"format":"float","maximum":180,"minimum":-180,"type":"number"}},{"description":"City name (matches city-profiles database \u2014 Tokyo, London, New York, etc.). Alternative to lat+lon. If both provided, city takes precedence for profile lookup.","example":"Tokyo","in":"query","name":"city","required":false,"schema":{"type":"string"}},{"in":"query","name":"radius_km","required":false,"schema":{"default":300,"maximum":2000,"minimum":50,"type":"integer"}},{"in":"query","name":"framework","required":false,"schema":{"default":"standard","enum":["standard","emergency","creative","technical","minimal"],"type":"string"}},{"in":"query","name":"detail","required":false,"schema":{"default":"paragraph","enum":["oneliner","paragraph","full"],"type":"string"}},{"description":"If true, embed the full city hazard profile (primary_hazard, baselines, tectonic context) in the response.","in":"query","name":"include_city_profile","required":false,"schema":{"default":false,"type":"boolean"}},{"description":"Include current vs 48h baseline deviation per metric.","in":"query","name":"include_baseline_comparison","required":false,"schema":{"default":true,"type":"boolean"}},{"description":"Express timestamps in city local time.","in":"query","name":"local_time","required":false,"schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingRegionResponse"}}},"description":"Regional briefing"},"400":{"content":{"application/json":{"example":{"error":"Either lat+lon or city parameter is required"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Neither lat+lon nor city provided"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"AI-generated location-scoped intelligence briefing [PLANNED]","tags":["briefing"],"x-status":"planned"}},"/briefing/source/{source_id}":{"get":{"description":"Single-domain briefing for one stream or category. Provides raw metric context, 48h trend, global comparison, correlation context, and narrative intelligence. Designed for domain experts and specialized agents.\n\n**Status:** PLANNED \u2014 not yet implemented.\n\n**source_id accepts:** Individual stream IDs (eq_magnitude, pm25, sea_surface_temp) OR category slugs (earthquakes, fires, weather, air_quality, ocean, flights, ships, disasters, humanitarian, solar, infrastructure).","operationId":"getBriefingSource","parameters":[{"description":"Stream ID or category slug. Category slugs aggregate all streams in that domain.","example":"earthquakes","in":"path","name":"source_id","required":true,"schema":{"type":"string"}},{"in":"query","name":"lat","required":false,"schema":{"format":"float","type":"number"}},{"in":"query","name":"lon","required":false,"schema":{"format":"float","type":"number"}},{"in":"query","name":"radius_km","required":false,"schema":{"default":500,"type":"integer"}},{"in":"query","name":"framework","required":false,"schema":{"default":"technical","enum":["standard","emergency","creative","technical","minimal"],"type":"string"}},{"in":"query","name":"detail","required":false,"schema":{"default":"paragraph","enum":["oneliner","paragraph","full"],"type":"string"}},{"in":"query","name":"include_trend","required":false,"schema":{"default":true,"type":"boolean"}},{"in":"query","name":"include_extremes","required":false,"schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BriefingSourceResponse"}}},"description":"Source briefing"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"content":{"application/json":{"example":{"error":"source_not_found","hint":"Use /api/v1/streams to browse valid source IDs","source_id":"xyz"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Unknown source_id or category slug"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"AI-generated single-domain deep dive [PLANNED]","tags":["briefing"],"x-status":"planned"}},"/health":{"get":{"description":"Returns overall platform status (ok/degraded), stream counts, and lists of stale sources. A source is 'warning' if its data age exceeds 3\u00d7 its expected interval. 'Critical' if 10\u00d7.\n\n**AI agent usage:** Check this before depending on time-sensitive data (seismics, weather). If `status=degraded`, specific sources may have outdated data. Check `stale_critical` for sources that are likely returning stale cached values.","operationId":"getHealth","responses":{"200":{"content":{"application/json":{"example":{"stale_critical":[],"stale_warning":[],"status":"ok","streams_shared":109,"streams_with_data":104,"timestamp":"2026-03-18T14:30:00Z"},"schema":{"$ref":"#/components/schemas/HealthResponse"}}},"description":"Platform health report"}},"summary":"Platform health and staleness status","tags":["health"]}},"/health/data-range":{"get":{"description":"Returns earliest/latest timestamps and snapshot count for each archived source, merging the Redis hot layer (48h) and TimescaleDB cold layer (90 days). Use to determine what historical range is queryable for a given stream.","operationId":"getDataRange","responses":{"200":{"content":{"application/json":{"example":{"ranges":{"eq_magnitude":{"earliest":"2025-12-18T00:00:00Z","latest":"2026-03-18T14:27:00Z","snapshot_count":26280}},"sources_archived":98,"timestamp":"2026-03-18T14:30:00Z"},"schema":{"$ref":"#/components/schemas/DataRangeResponse"}}},"description":"Archive coverage per source"}},"summary":"Data coverage \u2014 archive range per source","tags":["health"]}},"/health/schemas":{"get":{"description":"Shows when each upstream source's response schema was last checked, field count, and any recent structural changes detected. Used to catch when upstream APIs silently change their response format.","operationId":"getSchemaReport","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchemaReportResponse"}}},"description":"Schema tracking report"}},"summary":"Schema tracking status \u2014 upstream API change detection","tags":["health"]}},"/health/status":{"get":{"description":"Detailed per-source health: uptime %, consecutive failures, backoff state, last/first fetch timestamps, avg fetch duration, and a ring buffer of the last 20 fetch attempts with success/fail/duration/error for each.","operationId":"getSourceStatus","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceStatusAllResponse"}}},"description":"Full source status report"}},"summary":"Fetch history and health for all sources","tags":["health"]}},"/health/status/{source_id}":{"get":{"description":"Same schema as /health/status but for one source. Includes the last 20 fetch attempts.","operationId":"getSingleSourceStatus","parameters":[{"description":"Source ID to query (e.g. eq_magnitude, temperature, flight_altitude)","example":"eq_magnitude","in":"path","name":"source_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceStatusSingleResponse"}}},"description":"Source fetch history"},"404":{"content":{"application/json":{"example":{"error":"Source 'xyz' not found"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Source not found"}},"summary":"Fetch history for a single source","tags":["health"]}},"/health/validation":{"get":{"description":"Runs the 89-rule data validator against all cached source data. Returns per-source stats: point counts, dropped points (bad coordinates), clipped values (out of valid range), field ranges, and volume anomaly flags.","operationId":"getValidationReport","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationReportResponse"}}},"description":"Validation report"}},"summary":"Data quality validation report","tags":["health"]}},"/openapi.json":{"get":{"description":"Returns this specification document. Enables agent frameworks to auto-discover the full API surface via standard OpenAPI discovery.","operationId":"getOpenAPISpec","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OpenAPI 3.1.0 spec"}},"security":[],"summary":"This OpenAPI specification","tags":["meta"]}},"/streams":{"get":{"description":"Returns all available data streams grouped by category. Each stream entry includes: ID, name, description, unit, current data availability, and point count.\n\n**AI agent usage:** Call this once at the start of a session to discover what's available. Cache the result \u2014 the catalog is stable (new sources are added rarely). Use `has_data: true` to filter to currently active streams.","operationId":"listStreams","parameters":[{"description":"Filter streams by category name (case-insensitive substring match). E.g. 'geology' returns all geology streams.","example":"geology","in":"query","name":"category","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"streams":{"Geology & Space":[{"color":"#ff6b35","count":847,"description":"USGS real-time earthquake feed \u2014 magnitude of each event (Richter/moment magnitude)","has_data":true,"id":"eq_magnitude","name":"Earthquake Magnitude","timestamp":"2026-03-18T14:27:00Z","unit":"magnitude (Mw)"}]},"timestamp":"2026-03-18T14:30:00Z","total":109},"schema":{"$ref":"#/components/schemas/StreamCatalogResponse"}}},"description":"Stream catalog","headers":{"$ref":"#/components/headers/RateLimitHeaders"}},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Browse the stream catalog","tags":["streams"]}},"/streams/search":{"get":{"description":"Full-text search across stream ID, name, description, and category. Returns matching streams with current data status.\n\n**AI agent usage:** Use this to find streams by domain keyword when you don't know the exact stream ID. Example: `q=earthquake` returns all seismic streams. `q=air quality` returns PM2.5, AQI, NO2, CO. `q=ship` returns all maritime streams.","operationId":"searchStreams","parameters":[{"description":"Search query. Searches across stream ID, name, description, and category name. Case-insensitive.","example":"earthquake","in":"query","name":"q","required":true,"schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"count":8,"query":"earthquake","results":[{"category":"Geology & Space","count":847,"description":"USGS real-time earthquake feed \u2014 magnitude of each event","has_data":true,"id":"eq_magnitude","name":"Earthquake Magnitude"}]},"schema":{"$ref":"#/components/schemas/StreamSearchResponse"}}},"description":"Search results"},"400":{"content":{"application/json":{"example":{"error":"q parameter is required"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Missing q parameter"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Search streams by keyword","tags":["streams"]}},"/streams/{stream_id}":{"get":{"description":"Returns the full point array for one data stream, optionally geo-filtered. Each point has lat, lon, value, and optional metadata fields depending on the source.\n\n**AI agent usage:** Use this when you need raw individual data points \u2014 e.g. all earthquake events in an area, or all flight positions. For aggregated summaries, prefer `/api/v1/world` instead.\n\n**Point schema varies by source:** Earthquake points include depth_km, alert, tsunami fields. Flight points include altitude, velocity, heading. Weather points include only value. Use `/api/v1/streams` to see the description/unit for a stream before querying it.\n\n**Limit:** Default 1000 points, max 10000. Large sources (weather grid, flights) may have many more \u2014 use geo-filtering with lat/lon/radius_km to scope the response.","operationId":"getStream","parameters":[{"description":"Stream ID from the catalog (e.g. eq_magnitude, pm25, temperature, flight_altitude). Use /api/v1/streams to browse valid IDs.","example":"eq_magnitude","in":"path","name":"stream_id","required":true,"schema":{"type":"string"}},{"description":"Latitude for geo-filtering. Must be provided with lon.","in":"query","name":"lat","required":false,"schema":{"format":"float","maximum":90,"minimum":-90,"type":"number"}},{"description":"Longitude for geo-filtering. Must be provided with lat.","in":"query","name":"lon","required":false,"schema":{"format":"float","maximum":180,"minimum":-180,"type":"number"}},{"description":"Geo-filter radius in km. Only used when lat and lon are provided. Default: 500.","in":"query","name":"radius_km","required":false,"schema":{"default":500,"minimum":1,"type":"number"}},{"description":"Maximum number of points to return. Default: 1000. Hard cap: 10000.","in":"query","name":"limit","required":false,"schema":{"default":1000,"maximum":10000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"example":{"count":23,"name":"Earthquake Magnitude","points":[{"alert":"green","depth_km":12,"distance_km":45.2,"lat":34.2,"lon":-118.5,"tsunami":false,"value":3.1}],"stream_id":"eq_magnitude","timestamp":"2026-03-18T14:27:00Z","total_available":847},"schema":{"$ref":"#/components/schemas/StreamDataResponse"}}},"description":"Stream data. Returns empty points array (not 404) if stream has no current data.","headers":{"$ref":"#/components/headers/RateLimitHeaders"}},"404":{"content":{"application/json":{"example":{"error":"Stream 'xyz' not found or not available"},"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Stream not found or not available for public access"},"429":{"$ref":"#/components/responses/RateLimited"}},"summary":"Get raw point data for a single stream","tags":["streams"]}},"/subscriptions":{"get":{"description":"Returns all active webhook subscriptions for the authenticated user or agent. Each subscription specifies a trigger condition (cascade_id, source, threshold) and a delivery endpoint.\n\n**Status:** PLANNED \u2014 not yet implemented.","operationId":"listSubscriptions","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}},"description":"Active subscriptions"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"List active webhook subscriptions [PLANNED]","tags":["subscriptions"],"x-status":"planned"},"post":{"description":"Register a webhook URL to receive push notifications when anomaly thresholds are crossed. Supports three trigger types: cascade (one of the 18 defined cascade sequences), threshold (a single source exceeds a value), and anomaly_score (source Z-score exceeds a threshold).\n\n**Status:** PLANNED \u2014 not yet implemented.\n\n**Delivery format:** POST to your webhook URL with payload matching WebhookEventPayload schema. Retries: 3 attempts with exponential backoff. If all retries fail, subscription is marked as `suspended`.\n\n**x402 integration:** Per-notification billing option available \u2014 charge only when alerts fire, not for the subscription itself.","operationId":"createSubscription","requestBody":{"content":{"application/json":{"example":{"cascade_id":"cascade_001","cooldown_seconds":3600,"description":"Alert when coastal earthquake triggers cascade_001 within 500km of Tokyo","location_filter":{"lat":35.6762,"lon":139.6503,"radius_km":500},"min_severity":"elevated","name":"Tokyo seismic alert","trigger_type":"cascade","webhook_secret":"my-signing-secret","webhook_url":"https://my-agent.example.com/orbital-hook"},"schema":{"$ref":"#/components/schemas/SubscriptionCreateRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"Subscription created"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorGeneric"}}},"description":"Invalid request (bad trigger config, unreachable URL)"},"401":{"$ref":"#/components/responses/Unauthorized"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Register a webhook for event-driven alerts [PLANNED]","tags":["subscriptions"],"x-status":"planned"}},"/subscriptions/{subscription_id}":{"delete":{"operationId":"cancelSubscription","parameters":[{"in":"path","name":"subscription_id","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Subscription cancelled"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Cancel a webhook subscription [PLANNED]","tags":["subscriptions"],"x-status":"planned"},"get":{"operationId":"getSubscription","parameters":[{"in":"path","name":"subscription_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}},"description":"Subscription details"},"404":{"$ref":"#/components/responses/NotFound"}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"summary":"Get a single subscription [PLANNED]","tags":["subscriptions"],"x-status":"planned"}},"/world":{"get":{"description":"The primary endpoint. Returns data from all active streams, geo-filtered to a radius around the specified location. Results are grouped by category. Each source returns: point count, min/max/mean value, nearest point, and timestamp.\n\n**AI agent usage:** Call this first for any location-aware task. The response gives you a complete world-state snapshot \u2014 earthquakes nearby, current weather, air quality, flight density, active fires, maritime traffic, and more \u2014 in a single request.\n\n**Nearest-neighbor fallback:** If no data falls within `radius_km` for a grid source (e.g. weather), the single nearest grid cell is returned with `nearest_neighbor: true`. This ensures weather/climate sources always respond even for ocean coordinates.\n\n**Category filter:** Use `category=geology_space,disasters_events` to scope the query to relevant domains and reduce response size.","operationId":"getWorldState","parameters":[{"description":"Latitude of the focal point (-90 to 90)","example":34.05,"in":"query","name":"lat","required":true,"schema":{"format":"float","maximum":90,"minimum":-90,"type":"number"}},{"description":"Longitude of the focal point (-180 to 180)","example":-118.24,"in":"query","name":"lon","required":true,"schema":{"format":"float","maximum":180,"minimum":-180,"type":"number"}},{"description":"Search radius in kilometers. Default 500. For city-scale queries use 100-200. For regional use 500-1000. Grid sources (weather) use nearest-neighbor if no points fall within the radius.","example":300,"in":"query","name":"radius_km","required":false,"schema":{"default":500,"format":"float","maximum":20000,"minimum":1,"type":"number"}},{"description":"Comma-separated list of categories to include. Omit for all categories. Valid values: earth_climate, geology_space, disasters_events, human_activity, humanitarian, nature, infrastructure","example":"geology_space,disasters_events","in":"query","name":"category","required":false,"schema":{"type":"string"}},{"description":"Comma-separated list of specific source IDs to include. Use /api/v1/streams to discover valid IDs. Overrides category filter if both are specified.","example":"eq_magnitude,pm25,temperature,flight_altitude","in":"query","name":"sources","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"attribution":"/api/v1/attribution","location":{"lat":34.05,"lon":-118.24},"radius_km":300,"sources":47,"state":{"earth_climate":[{"category":"Earth & Climate","count":1,"max":18.4,"mean":18.4,"min":18.4,"name":"Temperature","nearest":{"distance_km":8.1,"lat":34.0,"lon":-118.3,"value":18.4},"nearest_distance_km":8.1,"nearest_neighbor":true,"source_id":"temperature","timestamp":"2026-03-18T14:00:00Z"}],"geology_space":[{"category":"Geology & Space","count":23,"max":4.1,"mean":2.9,"min":2.5,"name":"Earthquake Magnitude","nearest":{"distance_km":31.2,"lat":33.8,"lon":-118.1,"value":2.7},"source_id":"eq_magnitude","timestamp":"2026-03-18T14:27:00Z"}]},"timestamp":"2026-03-18T14:30:00Z","total_points":12843},"schema":{"$ref":"#/components/schemas/WorldStateResponse"}}},"description":"World state snapshot for the requested location","headers":{"$ref":"#/components/headers/RateLimitHeaders"}},"400":{"content":{"application/json":{"example":{"error":"lat and lon are required","usage":"/api/v1/world?lat=34.05&lon=-118.24&radius_km=500"},"schema":{"$ref":"#/components/schemas/Error400"}}},"description":"Missing or invalid lat/lon parameters"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}},"summary":"Multi-stream situational awareness for a location","tags":["world-state"]}}},"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]},{"X402Payment":[]}],"servers":[{"description":"Production server","url":"https://orbitalstreams.com/api/v1"},{"description":"Local development server","url":"http://localhost:5050/api/v1"}],"tags":[{"description":"Multi-stream situational awareness \u2014 the primary consumption pattern for AI agents. Returns aggregated, geo-filtered data across all active sources in a single call.","name":"world-state","x-agent-priority":1},{"description":"Stream catalog and individual stream data access. Use /streams to discover what's available, /streams/{id} for raw point data.","name":"streams","x-agent-priority":2},{"description":"AI-generated natural language intelligence. Turns raw world-state data into interpretable summaries with anomaly detection, confidence scores, and cascade monitoring. PLANNED \u2014 not yet implemented.","name":"briefing","x-agent-priority":3,"x-status":"planned"},{"description":"Webhook subscriptions for event-driven alerts. Register to receive push notifications when anomaly thresholds are crossed. PLANNED \u2014 not yet implemented.","name":"subscriptions","x-status":"planned"},{"description":"Agent annotation layer. Agents can attach interpretive context to world-state data. Creates a shared, living intelligence layer on top of raw streams. PLANNED \u2014 not yet implemented.","name":"annotations","x-status":"planned"},{"description":"Platform health, data freshness, validation status, and source reliability. Use before depending on critical data.","name":"health"},{"description":"Data source attribution and licensing. Programmatically access provider, license, and URL for all streams.","name":"attribution"},{"description":"API self-description and discovery.","name":"meta"}],"webhooks":{"anomalyEvent":{"post":{"description":"Delivered when a subscribed trigger condition fires. POST body contains the anomaly event with full context: trigger source, location, severity, active cascade chains, and relevant correlation IDs.","requestBody":{"content":{"application/json":{"example":{"affected_region":{"lat":-17.2,"lon":168.8,"radius_km":1000},"cascade_id":"cascade_001","cascade_name":"Coastal Earthquake \u2192 Tsunami","cascade_steps":[{"description":"Monitor for wave height > 0.5m at nearest coastal gauge","expected_delay_hours":[0.25,2.0],"source":"tsunami_height","status":"monitoring","step":1}],"confidence":0.91,"data_snapshot_url":"https://orbitalstreams.com/api/v1/world?lat=-17.2&lon=168.8&radius_km=1000&sources=eq_magnitude,eq_depth,tsunami_height,disaster_alert","delivery_attempt":1,"event_id":"evt_a3f7c92","event_type":"cascade_trigger","severity":"critical","subscription_id":"sub_abc123","timestamp":"2026-03-18T14:32:17Z","trigger":{"description":"M7.8 earthquake 23km depth, offshore Vanuatu","location":{"lat":-17.2,"lon":168.8},"source":"eq_magnitude","threshold":7.5,"value":7.8}},"schema":{"$ref":"#/components/schemas/WebhookEventPayload"}}},"required":true},"responses":{"200":{"description":"Webhook received successfully"},"2XX":{"description":"Any 2xx response is treated as successful delivery"}},"summary":"Anomaly event notification delivered to subscriber webhook URL"}}}}