{"openapi":"3.1.0","info":{"title":"Socket (BYOK) API","version":"0.1.0","description":"Socket (BYOK) lets an AI assistant read your own Socket data through the Socket API with a key you supply (Socket organization API token (sktsec_...)). Read-only: 11 tools (get_quota, list_organizations, list_repositories, get_repository, list_full_scans, get_full_scan_metadata, list_alerts, list_diff_scans, list_threat_feed, list_audit_log, list_webhooks). The BYOK key travels with each request,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-socketdev.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-socketdev/docs"},"termsOfService":"https://connectorbay.com/byok-socketdev/terms"},"servers":[{"url":"https://byok-socketdev.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-socketdev/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_quota":{"post":{"operationId":"get_quota","summary":"Show how many Socket API quota units the token has left, the maximum and when the window refreshes. This call uses no qu","description":"Show how many Socket API quota units the token has left, the maximum and when the window refreshes. This call uses no quota. Use for \"How much Socket API quota do I have left\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_quotaArguments","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_organizations":{"post":{"operationId":"list_organizations","summary":"List the Socket organizations the token belongs to, keyed by organization id, with name, slug and plan. Each call uses 1","description":"List the Socket organizations the token belongs to, keyed by organization id, with name, slug and plan. Each call uses 1 unit of the key's Socket API quota. Use for \"Which Socket organization is my token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_organizationsArguments","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_repositories":{"post":{"operationId":"list_repositories","summary":"List the repositories of an organization with visibility, default branch, workspace and the id of the latest full scan. ","description":"List the repositories of an organization with visibility, default branch, workspace and the id of the latest full scan. Each call uses 1 unit of the key's Socket API quota. Use for \"Which repositories are tracked in my Socket organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"sort":{"anyOf":[{"enum":["name","updated_at","created_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by name, updated_at or created_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include archived repositories.","title":"Include Archived"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["org_slug"],"title":"list_repositoriesArguments","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_repository":{"post":{"operationId":"get_repository","summary":"Get one repository of an organization by slug: visibility, default branch, workspace, latest full scan id and tracked br","description":"Get one repository of an organization by slug: visibility, default branch, workspace, latest full scan id and tracked branch patterns. Each call uses 1 unit of the key's Socket API quota. Use for \"Show the Socket repository web-app in my organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"repo_slug":{"description":"Repository slug, as listed by list_repositories.","maxLength":200,"title":"Repo Slug","type":"string"},"workspace":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Workspace the repository belongs to, if any.","title":"Workspace"}},"required":["org_slug","repo_slug"],"title":"get_repositoryArguments","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_full_scans":{"post":{"operationId":"list_full_scans","summary":"List full scans of an organization with repository, branch, commit, scan type, state and report link; filter by reposito","description":"List full scans of an organization with repository, branch, commit, scan type, state and report link; filter by repository, branch, pull request or commit. Each call uses 1 unit of the key's Socket API quota. Use for \"What are the latest Socket scans of the main branch of web-app\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"repo":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans of this repository slug.","title":"Repo"},"branch":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans of this branch.","title":"Branch"},"pull_request":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans of this pull request number.","title":"Pull Request"},"commit_hash":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only scans of this commit hash.","title":"Commit Hash"},"sort":{"anyOf":[{"enum":["name","created_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by name or created_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["org_slug"],"title":"list_full_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_full_scan_metadata":{"post":{"operationId":"get_full_scan_metadata","summary":"Get metadata of one full scan by id: repository, branch, commit, pull request, scan type, state and report link. Each ca","description":"Get metadata of one full scan by id: repository, branch, commit, pull request, scan type, state and report link. Each call uses 1 unit of the key's Socket API quota. Use for \"Show metadata of Socket full scan s1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"full_scan_id":{"description":"Full scan id, as returned by list_full_scans.","maxLength":100,"title":"Full Scan Id","type":"string"}},"required":["org_slug","full_scan_id"],"title":"get_full_scan_metadataArguments","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_alerts":{"post":{"operationId":"list_alerts","summary":"List the latest security alerts of an organization with type, category, severity, status, title and dashboard link; filt","description":"List the latest security alerts of an organization with type, category, severity, status, title and dashboard link; filter by severity, status, type or repository. Each call uses 1 unit of the key's Socket API quota. Use for \"Which critical Socket alerts are open in my organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"severity":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated severities to include: low, medium, high, critical.","title":"Severity"},"status":{"anyOf":[{"enum":["open","cleared"],"type":"string"},{"type":"null"}],"default":null,"description":"A single alert status: open or cleared.","title":"Status"},"alert_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated alert types to include, for example usesEval, unmaintained.","title":"Alert Type"},"repo_slug":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated repository slugs to include.","title":"Repo Slug"},"per_page":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 5000, default 1000).","title":"Per Page"},"start_after_cursor":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: pass the endCursor of the previous answer to get the next page.","title":"Start After Cursor"}},"required":["org_slug"],"title":"list_alertsArguments","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_diff_scans":{"post":{"operationId":"list_diff_scans","summary":"List diff scans (comparisons between two full scans) of an organization with before and after scan ids, description and ","description":"List diff scans (comparisons between two full scans) of an organization with before and after scan ids, description and links. Each call uses 1 unit of the key's Socket API quota. Use for \"Which Socket diff scans were run for my repositories\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"repository_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only diff scans of this repository id.","title":"Repository Id"},"sort":{"anyOf":[{"enum":["created_at","updated_at"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort by created_at or updated_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page.","title":"Per Page"},"start_after_cursor":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: pass the endCursor of the previous answer to get the next page.","title":"Start After Cursor"}},"required":["org_slug"],"title":"list_diff_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_threat_feed":{"post":{"operationId":"list_threat_feed","summary":"List packages Socket flagged as threats (malware, vulnerability, typosquat and others) with ecosystem purl, threat type,","description":"List packages Socket flagged as threats (malware, vulnerability, typosquat and others) with ecosystem purl, threat type, review flag and dates. Each call uses 1 unit of the key's Socket API quota. Use for \"Which npm packages did Socket flag as malware recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"filter":{"anyOf":[{"enum":["u","c","fp","tp","mal","vuln","anom","joke","spy","typo","obf","dual"],"type":"string"},{"type":"null"}],"default":null,"description":"Threat class: mal (malware), vuln, typo, spy, obf, anom, dual, joke, u, c, fp or tp.","title":"Filter"},"ecosystem":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this ecosystem, for example npm, pypi, gem, maven, golang, cargo or nuget.","title":"Ecosystem"},"name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only threats for this package name.","title":"Name"},"is_human_reviewed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to only return threats a human reviewed.","title":"Is Human Reviewed"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Threats per page.","title":"Per Page"},"start_after_cursor":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor: pass the endCursor of the previous answer to get the next page.","title":"Start After Cursor"}},"required":["org_slug"],"title":"list_threat_feedArguments","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_audit_log":{"post":{"operationId":"list_audit_log","summary":"List organization audit log events (needs a token with the audit-log scope) with time, type, user email and status code.","description":"List organization audit log events (needs a token with the audit-log scope) with time, type, user email and status code. Each call uses 1 unit of the key's Socket API quota. Use for \"What recent actions were taken in my Socket organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this type, for example CreateApiToken or ChangeMemberRole.","title":"Type"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Events per page.","title":"Per Page"},"page":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Page token from the previous answer's nextPage field.","title":"Page"},"from_time":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Unix timestamp in seconds; events before this time are returned.","title":"From Time"}},"required":["org_slug"],"title":"list_audit_logArguments","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_webhooks":{"post":{"operationId":"list_webhooks","summary":"List the organization's webhooks with name, target URL and subscribed events (secrets are not returned). Each call uses ","description":"List the organization's webhooks with name, target URL and subscribed events (secrets are not returned). Each call uses 1 unit of the key's Socket API quota. Use for \"Which Socket webhooks are configured for my organization\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"org_slug":{"description":"Socket organization slug, as shown in list_organizations (the slug field), for example 'acme'.","maxLength":100,"title":"Org Slug","type":"string"},"sort":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Sort field, for example created_at.","title":"Sort"},"direction":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort direction: asc or desc.","title":"Direction"},"per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["org_slug"],"title":"list_webhooksArguments","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}}}}