{"openapi":"3.1.0","info":{"title":"HostedScan (BYOK) API","version":"0.1.0","description":"HostedScan (BYOK) lets an AI assistant read your own HostedScan data through the HostedScan API with a key you supply (HostedScan API key). Read-only: 7 tools (list_targets, get_target, list_scans, get_scan, list_scheduled_scans, list_risks, get_risk). 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-hostedscan.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-hostedscan/docs"},"termsOfService":"https://connectorbay.com/byok-hostedscan/terms"},"servers":[{"url":"https://byok-hostedscan.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-hostedscan/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_targets":{"post":{"operationId":"list_targets","summary":"List scan targets (domains, IPs, URLs) with label, tags and health score and grade, newest first. Use for \"Which targets","description":"List scan targets (domains, IPs, URLs) with label, tags and health score and grade, newest first. Use for \"Which targets do I scan with HostedScan and what are their health grades\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional JSON object as text with arrays as values; allowed keys tags, label, target, source_id. Example: {\"tags\": [\"prod\"]}.","title":"Filters"},"sort":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Sort fields, comma separated, each optionally followed by ' desc', for example 'created_at desc'.","title":"Sort"},"page_size":{"anyOf":[{"maximum":499,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many objects per page (1 to 499; the API default and maximum is 500).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token: the next_page_token value of the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_targetsArguments","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_target":{"post":{"operationId":"get_target","summary":"Get one scan target by id with label, tags and health score. Use for \"Show HostedScan target t1\".","description":"Get one scan target by id with label, tags and health score. Use for \"Show HostedScan target t1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Target id.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_targetArguments","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_scans":{"post":{"operationId":"list_scans","summary":"List scans, newest first, with scanner type, state, progress, authenticated flag and requested targets. Use for \"Which H","description":"List scans, newest first, with scanner type, state, progress, authenticated flag and requested targets. Use for \"Which HostedScan scans failed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional JSON object as text with arrays as values; allowed keys type, state, scheduled_by, requested_targets.target_id, requested_targets.target, requested_targets.label. Example: {\"state\": [\"FAILED\"]}.","title":"Filters"},"page_size":{"anyOf":[{"maximum":499,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many objects per page (1 to 499; the API default and maximum is 500).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token: the next_page_token value of the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_scansArguments","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_scan":{"post":{"operationId":"get_scan","summary":"Get one scan by id: scanner type, state, progress, requested targets and the ids of risks that were newly opened, still ","description":"Get one scan by id: scanner type, state, progress, requested targets and the ids of risks that were newly opened, still open or closed. Use for \"How did HostedScan scan s1 go\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Scan id.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_scanArguments","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_scheduled_scans":{"post":{"operationId":"list_scheduled_scans","summary":"List scheduled scans with name, cron-style schedule, scanner types and last and next run. Use for \"What scans are schedu","description":"List scheduled scans with name, cron-style schedule, scanner types and last and next run. Use for \"What scans are scheduled in HostedScan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_size":{"anyOf":[{"maximum":499,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many objects per page (1 to 499; the API default and maximum is 500).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token: the next_page_token value of the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_scheduled_scansArguments","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_risks":{"post":{"operationId":"list_risks","summary":"List risks (findings) including closed ones, newest first, with target, status, threat level, scanner, title, CVSS and a","description":"List risks (findings) including closed ones, newest first, with target, status, threat level, scanner, title, CVSS and accepted flag. Descriptions and solutions are left out. Use for \"What high threat risks are open in HostedScan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filters":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Optional JSON object as text with arrays as values; allowed keys target_id, status (OPEN or CLOSED), tags, label, risk_definition.scan_type, risk_definition.threat_level, risk_definition.title, risk_definition.cve_ids. Example: {\"status\": [\"OPEN\"], \"risk_definition.threat_level\": [\"HIGH\"]}.","title":"Filters"},"page_size":{"anyOf":[{"maximum":499,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many objects per page (1 to 499; the API default and maximum is 500).","title":"Page Size"},"page_token":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination token: the next_page_token value of the previous answer (leave empty for the first page).","title":"Page Token"}},"title":"list_risksArguments","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_risk":{"post":{"operationId":"get_risk","summary":"Get one risk by id with target, status, scanner, title, threat level and CVSS. Use for \"Show HostedScan risk r1\".","description":"Get one risk by id with target, status, scanner, title, threat level and CVSS. Use for \"Show HostedScan risk r1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Risk id.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_riskArguments","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}}}}