{"openapi":"3.1.0","info":{"title":"Cobalt (BYOK) API","version":"0.1.0","description":"Cobalt (BYOK) lets an AI assistant read your own Cobalt data through the Cobalt API with a key you supply (Cobalt personal API token). Read-only: 11 tools (list_assets, list_pentests, list_findings, list_engagements, get_attack_surface_stats, get_credit_balance, list_contracts, list_credit_transactions, list_dast_targets, list_dast_scans, list_dast_findings). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cobalt.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cobalt/docs"},"termsOfService":"https://connectorbay.com/byok-cobalt/terms"},"servers":[{"url":"https://byok-cobalt.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cobalt/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_assets":{"post":{"operationId":"list_assets","summary":"List the organisation's assets (the things pentested): title, type, technology stack and tags. Filter by asset type. Use","description":"List the organisation's assets (the things pentested): title, type, technology stack and tags. Filter by asset type. Use for \"Which assets does my organisation have in Cobalt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"asset_type":{"anyOf":[{"enum":["api","cloud_config","external_network","internal_network","mobile","web","web_plus_api","web_plus_mobile","wireless_network","iot","thick_client","physical","other"],"type":"string"},{"type":"null"}],"default":null,"description":"Only assets of this type.","title":"Asset Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_assetsArguments","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_pentests":{"post":{"operationId":"list_pentests","summary":"List pentests with title, asset, testing type (agile or comprehensive), methodology, start and end dates and state (new,","description":"List pentests with title, asset, testing type (agile or comprehensive), methodology, start and end dates and state (new, in_review, planned, cancelled, live, remediation, closed). Use for \"Which of my Cobalt pentests are live\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"asset":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pentests of this asset id (starts with as_).","title":"Asset"},"state":{"anyOf":[{"enum":["new","in_review","planned","cancelled","live","remediation","closed"],"type":"string"},{"type":"null"}],"default":null,"description":"Only pentests in this state.","title":"State"},"testing_type":{"anyOf":[{"enum":["agile","comprehensive"],"type":"string"},{"type":"null"}],"default":null,"description":"Only pentests of this testing type.","title":"Testing Type"},"sort":{"anyOf":[{"enum":["start_date","-start_date","end_date","-end_date"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by start_date or end_date; prefix with - for descending, for example -start_date.","title":"Sort"},"start_date_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pentests starting on or after this date (YYYY-MM-DD).","title":"Start Date Gte"},"end_date_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only pentests ending on or before this date (YYYY-MM-DD).","title":"End Date Lte"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_pentestsArguments","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_findings":{"post":{"operationId":"list_findings","summary":"List pentest findings with title, severity, state, vulnerability category, affected targets, CVSS and CVE/CWE references","description":"List pentest findings with title, severity, state, vulnerability category, affected targets, CVSS and CVE/CWE references. Filter by pentest, asset, state, severity or date. Use for \"What high severity findings do my Cobalt pentests have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"pentest":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this pentest id (starts with pt_).","title":"Pentest"},"asset":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this asset id (starts with as_).","title":"Asset"},"severity":{"anyOf":[{"enum":["low","medium","high","critical"],"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this severity.","title":"Severity"},"state":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings in this state, for example need_fix, check_fix, wont_fix, triaging, invalid or duplicate.","title":"State"},"sort":{"anyOf":[{"enum":["severity","-severity","impact","-impact","state","-state","created_at","-created_at","updated_at","-updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by severity, impact, state, created_at or updated_at; prefix with - for descending.","title":"Sort"},"created_at_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings created at or after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created At Gte"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_findingsArguments","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_engagements":{"post":{"operationId":"list_engagements","summary":"List engagements such as secure code reviews with type, tag, title, methodology, state, dates and linked asset ids. Use ","description":"List engagements such as secure code reviews with type, tag, title, methodology, state, dates and linked asset ids. Use for \"What code review engagements are running in Cobalt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_engagementsArguments","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_attack_surface_stats":{"post":{"operationId":"get_attack_surface_stats","summary":"Show attack surface counts for the organisation: total domains, hosts seen in the last 7 days and hosts first seen in th","description":"Show attack surface counts for the organisation: total domains, hosts seen in the last 7 days and hosts first seen in the last 7 days. Use for \"How many domains and hosts does Cobalt see on my attack surface\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"}},"required":["region"],"title":"get_attack_surface_statsArguments","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_credit_balance":{"post":{"operationId":"get_credit_balance","summary":"Show the organisation's current Cobalt credit balance. Use for \"How many Cobalt credits do we have left\".","description":"Show the organisation's current Cobalt credit balance. Use for \"How many Cobalt credits do we have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"}},"required":["region"],"title":"get_credit_balanceArguments","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_contracts":{"post":{"operationId":"list_contracts","summary":"List contracts with start and end date, state and total, spent and unused credits. Use for \"What Cobalt contracts do we ","description":"List contracts with start and end date, state and total, spent and unused credits. Use for \"What Cobalt contracts do we have and how many credits are unused\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"}},"required":["region"],"title":"list_contractsArguments","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_credit_transactions":{"post":{"operationId":"list_credit_transactions","summary":"List credit transactions with description, amount, date and whether pending, plus the current balance. Use for \"What did","description":"List credit transactions with description, amount, date and whether pending, plus the current balance. Use for \"What did we spend Cobalt credits on recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_credit_transactionsArguments","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_dast_targets":{"post":{"operationId":"list_dast_targets","summary":"List DAST scanner targets with name, URL and whether enabled. Use for \"Which sites does my Cobalt DAST scanner cover\".","description":"List DAST scanner targets with name, URL and whether enabled. Use for \"Which sites does my Cobalt DAST scanner cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_dast_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/list_dast_scans":{"post":{"operationId":"list_dast_scans","summary":"List DAST scans with target id, status and start and completion time. Use for \"When did the last Cobalt DAST scan run\".","description":"List DAST scans with target id, status and start and completion time. Use for \"When did the last Cobalt DAST scan run\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_dast_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_dast_findings":{"post":{"operationId":"list_dast_findings","summary":"List DAST findings with title, severity, state, affected URL and last-found time. Filter by target or scan id. Use for \"","description":"List DAST findings with title, severity, state, affected URL and last-found time. Filter by target or scan id. Use for \"What did the Cobalt DAST scanner find on target dt_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"Cobalt data centre of the account: us (api.us.cobalt.io) or eu (api.eu.cobalt.io, for app.eu.cobalt.io customers).","enum":["us","eu"],"title":"Region","type":"string"},"target":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this DAST target id (starts with dt_).","title":"Target"},"scan":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this DAST scan id (starts with dsc_).","title":"Scan"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results to return per page (default 10).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor taken from pagination.next_page of the previous answer (the value after 'cursor=').","title":"Cursor"}},"required":["region"],"title":"list_dast_findingsArguments","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}}}}