{"openapi":"3.1.0","info":{"title":"N2YO (BYOK) API","version":"0.1.0","description":"N2YO (BYOK) lets an AI assistant read your own N2YO data through the N2YO API with a key you supply (API license key). Read-only: 6 tools (get_tle, get_satellite_positions, get_current_position, get_visual_passes, get_radio_passes, get_satellites_above). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-n2yo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-n2yo/docs"},"termsOfService":"https://connectorbay.com/byok-n2yo/terms"},"servers":[{"url":"https://byok-n2yo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-n2yo/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/get_tle":{"post":{"operationId":"get_tle","summary":"Get the latest two-line element set (TLE) of a satellite, the orbit description used to compute its position. The two li","description":"Get the latest two-line element set (TLE) of a satellite, the orbit description used to compute its position. The two lines are separated by a carriage return and line feed. Limit: 1000 calls per hour. Use for \"What is the current TLE of the International Space Station\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"satellite_id":{"description":"NORAD catalogue ID of the satellite (not the Alpha-5 ID), for example 25544 for the International Space Station.","minimum":1,"title":"Satellite Id","type":"integer"}},"required":["satellite_id"],"title":"get_tleArguments","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_satellite_positions":{"post":{"operationId":"get_satellite_positions","summary":"Get a satellite's future positions for the next N seconds (one per second, at most 300), as seen from an observer: latit","description":"Get a satellite's future positions for the next N seconds (one per second, at most 300), as seen from an observer: latitude, longitude, altitude, azimuth, elevation, right ascension, declination and time. Limit: 1000 calls per hour. Use for \"Where will the ISS be over the next 60 seconds as seen from Scranton\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"satellite_id":{"description":"NORAD catalogue ID of the satellite (not the Alpha-5 ID), for example 25544 for the International Space Station.","minimum":1,"title":"Satellite Id","type":"integer"},"observer_lat":{"description":"Observer latitude in decimal degrees, -90 to 90.","maximum":90,"minimum":-90,"title":"Observer Lat","type":"number"},"observer_lng":{"description":"Observer longitude in decimal degrees, -180 to 180.","maximum":180,"minimum":-180,"title":"Observer Lng","type":"number"},"observer_alt":{"description":"Observer altitude above sea level in whole metres.","title":"Observer Alt","type":"integer"},"seconds":{"description":"How many future seconds of positions to return, 1 to 300.","maximum":300,"minimum":1,"title":"Seconds","type":"integer"}},"required":["satellite_id","observer_lat","observer_lng","observer_alt","seconds"],"title":"get_satellite_positionsArguments","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_current_position":{"post":{"operationId":"get_current_position","summary":"Get where a satellite is right now: latitude, longitude, altitude, azimuth and elevation from the observer's point. Retu","description":"Get where a satellite is right now: latitude, longitude, altitude, azimuth and elevation from the observer's point. Returns a single position. Use for \"Where is the International Space Station right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"satellite_id":{"description":"NORAD catalogue ID of the satellite (not the Alpha-5 ID), for example 25544 for the International Space Station.","minimum":1,"title":"Satellite Id","type":"integer"},"observer_lat":{"description":"Observer latitude in decimal degrees, -90 to 90.","maximum":90,"minimum":-90,"title":"Observer Lat","type":"number"},"observer_lng":{"description":"Observer longitude in decimal degrees, -180 to 180.","maximum":180,"minimum":-180,"title":"Observer Lng","type":"number"},"observer_alt":{"description":"Observer altitude above sea level in whole metres.","title":"Observer Alt","type":"integer"},"seconds":{"description":"Keep 1 to get just the current position.","maximum":1,"minimum":1,"title":"Seconds","type":"integer"}},"required":["satellite_id","observer_lat","observer_lng","observer_alt","seconds"],"title":"get_current_positionArguments","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_visual_passes":{"post":{"operationId":"get_visual_passes","summary":"Predict visible passes of a satellite over an observer for the next days (at most 10): start, peak and end time, azimuth","description":"Predict visible passes of a satellite over an observer for the next days (at most 10): start, peak and end time, azimuth, elevation, magnitude (100000 means unknown) and duration. Limit: 100 calls per hour. Use for \"When can I see the ISS from Scranton in the next 5 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"satellite_id":{"description":"NORAD catalogue ID of the satellite (not the Alpha-5 ID), for example 25544 for the International Space Station.","minimum":1,"title":"Satellite Id","type":"integer"},"observer_lat":{"description":"Observer latitude in decimal degrees, -90 to 90.","maximum":90,"minimum":-90,"title":"Observer Lat","type":"number"},"observer_lng":{"description":"Observer longitude in decimal degrees, -180 to 180.","maximum":180,"minimum":-180,"title":"Observer Lng","type":"number"},"observer_alt":{"description":"Observer altitude above sea level in whole metres.","title":"Observer Alt","type":"integer"},"days":{"description":"Days of prediction, 1 to 10.","maximum":10,"minimum":1,"title":"Days","type":"integer"},"min_visibility":{"description":"Only passes visible at least this many seconds.","minimum":0,"title":"Min Visibility","type":"integer"}},"required":["satellite_id","observer_lat","observer_lng","observer_alt","days","min_visibility"],"title":"get_visual_passesArguments","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_radio_passes":{"post":{"operationId":"get_radio_passes","summary":"Predict radio passes of a satellite over an observer for the next days (at most 10) above a minimum elevation: start, pe","description":"Predict radio passes of a satellite over an observer for the next days (at most 10) above a minimum elevation: start, peak and end time and azimuth. Limit: 100 calls per hour. Use for \"When will the ISS pass above 40 degrees elevation over Scranton in the next 3 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"satellite_id":{"description":"NORAD catalogue ID of the satellite (not the Alpha-5 ID), for example 25544 for the International Space Station.","minimum":1,"title":"Satellite Id","type":"integer"},"observer_lat":{"description":"Observer latitude in decimal degrees, -90 to 90.","maximum":90,"minimum":-90,"title":"Observer Lat","type":"number"},"observer_lng":{"description":"Observer longitude in decimal degrees, -180 to 180.","maximum":180,"minimum":-180,"title":"Observer Lng","type":"number"},"observer_alt":{"description":"Observer altitude above sea level in whole metres.","title":"Observer Alt","type":"integer"},"days":{"description":"Days of prediction, 1 to 10.","maximum":10,"minimum":1,"title":"Days","type":"integer"},"min_elevation":{"description":"Only passes reaching at least this elevation in degrees.","maximum":90,"minimum":0,"title":"Min Elevation","type":"integer"}},"required":["satellite_id","observer_lat","observer_lng","observer_alt","days","min_elevation"],"title":"get_radio_passesArguments","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_satellites_above":{"post":{"operationId":"get_satellites_above","summary":"List satellites currently above an observer within a search radius (0 to 90 degrees) for a category (0 for all): name, I","description":"List satellites currently above an observer within a search radius (0 to 90 degrees) for a category (0 for all): name, ID, launch date, latitude, longitude and altitude in km. Limit: 100 calls per hour; the call is heavy for the provider, so use it sparingly. Use for \"Which satellites are above Scranton right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"observer_lat":{"description":"Observer latitude in decimal degrees, -90 to 90.","maximum":90,"minimum":-90,"title":"Observer Lat","type":"number"},"observer_lng":{"description":"Observer longitude in decimal degrees, -180 to 180.","maximum":180,"minimum":-180,"title":"Observer Lng","type":"number"},"observer_alt":{"description":"Observer altitude above sea level in whole metres.","title":"Observer Alt","type":"integer"},"search_radius":{"description":"Search radius in degrees, 0 to 90.","maximum":90,"minimum":0,"title":"Search Radius","type":"integer"},"category_id":{"description":"Satellite category ID; 0 means all categories.","minimum":0,"title":"Category Id","type":"integer"}},"required":["observer_lat","observer_lng","observer_alt","search_radius","category_id"],"title":"get_satellites_aboveArguments","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}}}}