{"openapi":"3.1.0","info":{"title":"Semgrep (BYOK) API","version":"0.1.0","description":"Semgrep (BYOK) lets an AI assistant read your own Semgrep data through the Semgrep API with a key you supply (Semgrep API token with Web API access enabled). Read-only: 9 tools (list_deployments, list_projects, get_project, list_findings, search_scans, get_scan, search_dependencies, list_secrets_findings, list_policies). The BYOK key travels with each request, is used for that one call only and...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-semgrep.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-semgrep/docs"},"termsOfService":"https://connectorbay.com/byok-semgrep/terms"},"servers":[{"url":"https://byok-semgrep.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-semgrep/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_deployments":{"post":{"operationId":"list_deployments","summary":"List the Semgrep deployment (organisation) your token can access, with its numeric id, name and slug. Use the id and slu","description":"List the Semgrep deployment (organisation) your token can access, with its numeric id, name and slug. Use the id and slug in the other tools. Use for \"Which Semgrep deployment is my token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_deploymentsArguments","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_projects":{"post":{"operationId":"list_projects","summary":"List projects (repositories) scanned by Semgrep with default branch, last scan time, creation time and tags. Archived re","description":"List projects (repositories) scanned by Semgrep with default branch, last scan time, creation time and tags. Archived repositories are left out. Use for \"Which of my repositories does Semgrep scan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_slug":{"description":"Slug of your Semgrep deployment (organisation), from list_deployments.","maxLength":100,"title":"Deployment Slug","type":"string"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number starting at 0.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Projects per page (default 100).","title":"Page Size"}},"required":["deployment_slug"],"title":"list_projectsArguments","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_project":{"post":{"operationId":"get_project","summary":"Get one project by name (for example 'acme/web'): branches, last scan time, tags and URL. Use for \"When was acme/web las","description":"Get one project by name (for example 'acme/web'): branches, last scan time, tags and URL. Use for \"When was acme/web last scanned by Semgrep\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_slug":{"description":"Slug of your Semgrep deployment (organisation), from list_deployments.","maxLength":100,"title":"Deployment Slug","type":"string"},"project_name":{"description":"Project name as listed by list_projects, usually 'owner/repo'. A slash is sent URL-encoded.","maxLength":200,"title":"Project Name","type":"string"}},"required":["deployment_slug","project_name"],"title":"get_projectArguments","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 Semgrep findings: code (sast), supply chain (sca) or AI-powered detection (ai_sast), newest first, with severity, s","description":"List Semgrep findings: code (sast), supply chain (sca) or AI-powered detection (ai_sast), newest first, with severity, status, rule, repository, file and line, and for supply chain the vulnerable package, reachability and fix versions. Use for \"What open high severity Semgrep findings do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_slug":{"description":"Slug of your Semgrep deployment (organisation), from list_deployments.","maxLength":100,"title":"Deployment Slug","type":"string"},"issue_type":{"anyOf":[{"enum":["sast","sca","ai_sast"],"type":"string"},{"type":"null"}],"default":"sast","description":"Which findings: sast (code), sca (supply chain) or ai_sast (AI-powered detection).","title":"Issue Type"},"status":{"anyOf":[{"enum":["open","fixed","ignored","reviewing","fixing","provisionally_ignored"],"type":"string"},{"type":"null"}],"default":null,"description":"Only findings with this status.","title":"Status"},"confidence":{"anyOf":[{"enum":["low","medium","high"],"type":"string"},{"type":"null"}],"default":null,"description":"Only findings of this confidence.","title":"Confidence"},"ref":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings on this ref (branch), for example 'refs/heads/main'.","title":"Ref"},"since":{"anyOf":[{"minimum":0,"type":"number"},{"type":"null"}],"default":null,"description":"Only findings detected since this Unix time in seconds.","title":"Since"},"dedup":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to deduplicate findings across branches (matches the counts in the web app); leave out for all findings on all refs.","title":"Dedup"},"is_malicious":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only findings from malicious dependencies (sca).","title":"Is Malicious"},"page":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Page number starting at 0 (100 findings per page).","title":"Page"}},"required":["deployment_slug"],"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/search_scans":{"post":{"operationId":"search_scans","summary":"List scans of the last 30 days with status, branch, commit, finding counts and duration. Filter by repository id, branch","description":"List scans of the last 30 days with status, branch, commit, finding counts and duration. Filter by repository id, branch or start time. Use for \"Which Semgrep scans failed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_id":{"description":"Numeric ID of your Semgrep deployment, from list_deployments.","maxLength":20,"title":"Deployment Id","type":"string"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many scans to return (1 to 500, default 100).","title":"Limit"},"repository_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only scans of this numeric project id (the id from list_projects).","title":"Repository Id"},"branch":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans of this branch.","title":"Branch"},"since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans created after this ISO 8601 time, for example 2026-10-01T00:00:00Z.","title":"Since"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page.","title":"Cursor"}},"required":["deployment_id"],"title":"search_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: status, exit code, branch, commit, repository, CI job URL, enabled products and statistics. Use for \"Show ","description":"Get one scan: status, exit code, branch, commit, repository, CI job URL, enabled products and statistics. Use for \"Show me the details of Semgrep scan 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_id":{"description":"Numeric ID of your Semgrep deployment, from list_deployments.","maxLength":20,"title":"Deployment Id","type":"string"},"scan_id":{"description":"Numeric scan id from search_scans.","maxLength":20,"title":"Scan Id","type":"string"}},"required":["deployment_id","scan_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/search_dependencies":{"post":{"operationId":"search_dependencies","summary":"Find a package in your projects' dependency lists (software bill of materials): ecosystem, version, licences, whether di","description":"Find a package in your projects' dependency lists (software bill of materials): ecosystem, version, licences, whether direct or transitive and where it is defined. Use for \"Which of my projects use lodash\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_id":{"description":"Numeric ID of your Semgrep deployment, from list_deployments.","maxLength":20,"title":"Deployment Id","type":"string"},"package_name":{"description":"Package name to look for, for example 'lodash' (fuzzy match).","maxLength":200,"title":"Package Name","type":"string"},"page_size":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Dependencies per page (1 to 10000, default 100).","title":"Page Size"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page.","title":"Cursor"}},"required":["deployment_id","package_name"],"title":"search_dependenciesArguments","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_secrets_findings":{"post":{"operationId":"list_secrets_findings","summary":"List secrets findings (leaked credentials detected in code) with type, severity, status, validation state, repository, f","description":"List secrets findings (leaked credentials detected in code) with type, severity, status, validation state, repository, file path and branch. The secret values themselves are not part of the answer. Use for \"Which secrets findings are open in Semgrep\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_id":{"description":"Numeric ID of your Semgrep deployment, from list_deployments.","maxLength":20,"title":"Deployment Id","type":"string"},"status":{"anyOf":[{"enum":["FINDING_STATUS_OPEN","FINDING_STATUS_IGNORED","FINDING_STATUS_FIXED","FINDING_STATUS_REMOVED","FINDING_STATUS_PROVISIONALLY_IGNORED"],"type":"string"},{"type":"null"}],"default":null,"description":"Only findings with this status.","title":"Status"},"since":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only findings since this ISO 8601 time.","title":"Since"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Findings per page.","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer to get the next page.","title":"Cursor"}},"required":["deployment_id"],"title":"list_secrets_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_policies":{"post":{"operationId":"list_policies","summary":"List Semgrep policies (rule sets applied to repositories) with name, slug, product type and whether the policy is the de","description":"List Semgrep policies (rule sets applied to repositories) with name, slug, product type and whether the policy is the default. Use for \"Which Semgrep policies are configured\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deployment_id":{"description":"Numeric ID of your Semgrep deployment, from list_deployments.","maxLength":20,"title":"Deployment Id","type":"string"}},"required":["deployment_id"],"title":"list_policiesArguments","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}}}}