{"openapi":"3.1.0","info":{"title":"Sofar Ocean (BYOK) API","version":"0.1.0","description":"Sofar Ocean (BYOK) lets an AI assistant read your own Sofar Ocean data through the Sofar Ocean API with a key you supply (Sofar API token). Read-only: 7 tools (list_spotters, get_latest_data, get_historical_data, search_spotters_by_area, get_sensor_data, get_sensor_configuration_history, list_wave_spectra_locations). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-sofarocean.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-sofarocean/docs"},"termsOfService":"https://connectorbay.com/byok-sofarocean/terms"},"servers":[{"url":"https://byok-sofarocean.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-sofarocean/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_spotters":{"post":{"operationId":"list_spotters","summary":"List the Spotter buoys you can access (registered to or shared with your account) with id, display name and hull type. U","description":"List the Spotter buoys you can access (registered to or shared with your account) with id, display name and hull type. Use for \"Which Sofar Spotter buoys can I see\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"exclude_shared_devices":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only buoys registered directly to your account, leaving out shared ones.","title":"Exclude Shared Devices"}},"title":"list_spottersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_latest_data":{"post":{"operationId":"get_latest_data","summary":"Get the most recent transmission of one Spotter: battery, latest wave height and period, and optionally wind, surface te","description":"Get the most recent transmission of one Spotter: battery, latest wave height and period, and optionally wind, surface temperature and barometer samples with positions. Use for \"What are the current wave conditions at Sofar Spotter SPOT-0018\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spotter_id":{"description":"Spotter id of a buoy registered to or shared with your account, for example 'SPOT-0018' (see list_spotters).","maxLength":200,"title":"Spotter Id","type":"string"},"include_wind_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include wind speed and direction samples.","title":"Include Wind Data"},"include_surface_temp_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include sea surface temperature samples (buoys with a temperature sensor).","title":"Include Surface Temp Data"},"include_barometer_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include barometric pressure samples (buoys with a barometer).","title":"Include Barometer Data"}},"required":["spotter_id"],"title":"get_latest_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_historical_data":{"post":{"operationId":"get_historical_data","summary":"Get waves and optional wind, surface temperature, barometer and position data of one Spotter between two dates (default ","description":"Get waves and optional wind, surface temperature, barometer and position data of one Spotter between two dates (default 20 samples, at most 500). Shared buoys only return the last 30 days. Use for \"Show wave heights at Sofar Spotter SPOT-0018 for the first days of February 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spotter_id":{"description":"Spotter id of a buoy registered to or shared with your account, for example 'SPOT-0018' (see list_spotters).","maxLength":200,"title":"Spotter Id","type":"string"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum samples per data type (1 to 500; default 20).","title":"Limit"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the window as an ISO 8601 timestamp, for example 2026-02-01T00:00:00Z (omit for the latest samples).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"End of the window as an ISO 8601 timestamp (default now).","title":"End Date"},"include_wind_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include wind samples.","title":"Include Wind Data"},"include_surface_temp_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include sea surface temperature samples.","title":"Include Surface Temp Data"},"include_barometer_data":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include barometric pressure samples.","title":"Include Barometer Data"},"include_track":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include position tracking samples.","title":"Include Track"}},"required":["spotter_id"],"title":"get_historical_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_spotters_by_area":{"post":{"operationId":"search_spotters_by_area","summary":"Beta: get samples from buoys registered to your account inside a circle or rectangle during a time window (shared buoys ","description":"Beta: get samples from buoys registered to your account inside a circle or rectangle during a time window (shared buoys are not included). Paged through the cursor URL in metadata. Use for \"Which of my Sofar buoys reported waves near San Francisco in early February 2026\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"shape":{"description":"Search area shape: circle or envelope.","enum":["circle","envelope"],"title":"Shape","type":"string"},"shape_params":{"description":"Comma-separated latitude,longitude values: one pair for a circle, two pairs (corners) for an envelope, for example '37.788480,-122.387461'.","maxLength":200,"title":"Shape Params","type":"string"},"start_date":{"description":"Start of the window as an ISO 8601 timestamp.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"End of the window as an ISO 8601 timestamp.","maxLength":200,"title":"End Date","type":"string"},"radius":{"anyOf":[{"maximum":10000000,"minimum":1,"type":"number"},{"type":"null"}],"default":null,"description":"Radius in meters; required when shape is circle.","title":"Radius"},"page_size":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":500,"description":"Number of samples to return (default 500).","title":"Page Size"}},"required":["shape","shape_params","start_date","end_date"],"title":"search_spotters_by_areaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_sensor_data":{"post":{"operationId":"get_sensor_data","summary":"Get Smart Mooring sensor samples (for example subsurface temperature) of one Spotter between two dates with sensor posit","description":"Get Smart Mooring sensor samples (for example subsurface temperature) of one Spotter between two dates with sensor position, units and value. Use for \"What did the Smart Mooring sensors on SPOT-0222 report on 1 December 2021\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spotter_id":{"description":"Spotter id of a buoy registered to or shared with your account, for example 'SPOT-0018' (see list_spotters).","maxLength":200,"title":"Spotter Id","type":"string"},"start_date":{"description":"Start of the time window as an ISO 8601 timestamp, for example 2026-02-01T00:00:00Z.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"End of the time window as an ISO 8601 timestamp, for example 2026-02-02T00:00:00Z.","maxLength":200,"title":"End Date","type":"string"}},"required":["spotter_id","start_date","end_date"],"title":"get_sensor_dataArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_sensor_configuration_history":{"post":{"operationId":"get_sensor_configuration_history","summary":"Get the Smart Mooring sensor configurations a Spotter reported between two dates (only available from June 2025 onward).","description":"Get the Smart Mooring sensor configurations a Spotter reported between two dates (only available from June 2025 onward). Use for \"How was the Smart Mooring on SPOT-31082C configured in December 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"spotter_id":{"description":"Spotter id of a buoy registered to or shared with your account, for example 'SPOT-0018' (see list_spotters).","maxLength":200,"title":"Spotter Id","type":"string"},"start_date":{"description":"Start of the time window as an ISO 8601 timestamp, for example 2026-02-01T00:00:00Z.","maxLength":200,"title":"Start Date","type":"string"},"end_date":{"description":"End of the time window as an ISO 8601 timestamp, for example 2026-02-02T00:00:00Z.","maxLength":200,"title":"End Date","type":"string"}},"required":["spotter_id","start_date","end_date"],"title":"get_sensor_configuration_historyArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_wave_spectra_locations":{"post":{"operationId":"list_wave_spectra_locations","summary":"List the grid points (0.5 degree) for which you have access to the 7-day operational wave spectra forecast, with their d","description":"List the grid points (0.5 degree) for which you have access to the 7-day operational wave spectra forecast, with their data file URL. Use for \"For which locations can I get the Sofar wave spectra forecast\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_wave_spectra_locationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}