Socket full-scans API

openapi: 3.0.0
info:
  description: Socket alerts API endpoints.
  title: Socket alerts full-scans API
  version: '0'
servers:
- url: https://api.socket.dev/v0
tags:
- name: full-scans
paths:
  /orgs/{org_slug}/supported-files:
    get:
      tags:
      - full-scans
      summary: Get supported file types
      operationId: getSupportedFiles
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      security:
      - bearerAuth: []
      - basicAuth: []
      description: 'Get a list of supported files for full scan generation.

        Files are categorized first by environment (e.g. NPM or PyPI), then by name.


        Files whose names match the patterns returned by this endpoint can be uploaded for report generation.

        Examples of supported filenames include `package.json`, `package-lock.json`, and `yarn.lock`.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - No Scopes Required, but authentication is required'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      pattern:
                        type: string
                        description: ''
                        default: ''
                    required:
                    - pattern
                  properties: {}
                  description: ''
                properties: {}
                description: ''
          description: Glob patterns used to match supported files
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /alert-types:
    post:
      tags:
      - full-scans
      summary: Alert Types Metadata
      operationId: alertTypes
      parameters:
      - name: language
        in: query
        required: false
        description: Language for alert metadata
        schema:
          type: string
          enum:
          - ach-UG
          - de-DE
          - en-US
          - es-ES
          - fr-FR
          - it-IT
          default: en-US
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                description: ''
                default: ''
              description: ''
        required: false
      security: []
      description: 'For an array of alert type identifiers, returns metadata for each alert type. Optionally, specify a language via the ''language'' query parameter.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  description: ''
                  properties:
                    type:
                      type: string
                      description: ''
                      default: ''
                    title:
                      type: string
                      description: ''
                      default: ''
                    description:
                      type: string
                      description: ''
                      default: ''
                    suggestion:
                      type: string
                      description: ''
                      default: ''
                    emoji:
                      type: string
                      description: ''
                      default: ''
                    nextStepTitle:
                      type: string
                      description: ''
                      default: ''
                    props:
                      type: object
                      additionalProperties:
                        type: string
                        description: ''
                        default: ''
                      properties: {}
                      description: ''
                      nullable: true
                  required:
                  - description
                  - emoji
                  - nextStepTitle
                  - props
                  - suggestion
                  - title
                  - type
                description: ''
          description: Metadata for the requested alert types
        '400':
          $ref: '#/components/responses/SocketBadRequest'
      x-readme: {}
  /orgs/{org_slug}/full-scans:
    get:
      tags:
      - full-scans
      summary: List full scans
      operationId: getOrgFullScanList
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: Specify Sort order.
        schema:
          type: string
          enum:
          - name
          - created_at
          default: created_at
      - name: direction
        in: query
        required: false
        description: Specify sort direction.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: per_page
        in: query
        required: false
        description: Specify the maximum number of results to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: page
        in: query
        required: false
        description: The page number to return when using offset-style pagination. Ignored when cursor pagination is used.
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: startAfterCursor
        in: query
        required: false
        description: Cursor token for pagination. Pass the returned nextPageCursor from previous responses to fetch the next set of results.
        schema:
          type: string
      - name: use_cursor
        in: query
        required: false
        description: Set to true on the first request to opt into cursor-based pagination.
        schema:
          type: boolean
          default: false
      - name: from
        in: query
        required: false
        description: A Unix timestamp in seconds that filters full-scans prior to the date.
        schema:
          type: string
      - name: workspace
        in: query
        required: false
        description: A repository workspace to filter full-scans by.
        schema:
          type: string
      - name: repo
        in: query
        required: false
        description: A repository slug to filter full-scans by.
        schema:
          type: string
      - name: branch
        in: query
        required: false
        description: A branch name to filter full-scans by.
        schema:
          type: string
      - name: pull_request
        in: query
        required: false
        description: A PR number to filter full-scans by.
        schema:
          type: string
      - name: commit_hash
        in: query
        required: false
        description: A commit hash to filter full-scans by.
        schema:
          type: string
      - name: scan_type
        in: query
        required: false
        description: A scan type to filter full-scans by (e.g. socket, socket_tier1, socket_basics).
        schema:
          type: string
      security:
      - bearerAuth:
        - full-scans:list
      - basicAuth:
        - full-scans:list
      description: 'Returns a paginated list of all full scans in an org, excluding SBOM artifacts.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - full-scans:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        id:
                          type: string
                          description: ''
                          default: ''
                        created_at:
                          type: string
                          description: ''
                          default: ''
                        updated_at:
                          type: string
                          description: ''
                          default: ''
                        organization_id:
                          type: string
                          description: ''
                          default: ''
                        organization_slug:
                          type: string
                          description: ''
                          default: ''
                        repository_id:
                          type: string
                          description: ''
                          default: ''
                        repository_slug:
                          type: string
                          description: ''
                          default: ''
                        branch:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        commit_message:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        commit_hash:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        pull_request:
                          type: integer
                          description: ''
                          default: 0
                          nullable: true
                        committers:
                          type: array
                          items:
                            type: string
                            description: ''
                            default: ''
                          description: ''
                        html_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        api_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        workspace:
                          type: string
                          description: ''
                          default: ''
                        repo:
                          type: string
                          description: ''
                          default: ''
                        html_report_url:
                          type: string
                          description: ''
                          default: ''
                        integration_type:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        integration_repo_url:
                          type: string
                          description: ''
                          default: ''
                        integration_branch_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        integration_commit_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        integration_pull_request_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        scan_type:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        scan_state:
                          type: string
                          enum:
                          - pending
                          - precrawl
                          - resolve
                          - scan
                          description: The current processing status of the SBOM
                          default: pending
                          nullable: true
                      description: ''
                    description: ''
                  nextPageCursor:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  nextPage:
                    type: integer
                    description: ''
                    default: 0
                    nullable: true
                required:
                - nextPage
                - nextPageCursor
                - results
          description: Lists repositories for the specified organization. The authenticated user must be a member of the organization.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    post:
      tags:
      - full-scans
      summary: Create full scan
      operationId: CreateOrgFullScan
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: repo
        in: query
        required: true
        description: The slug of the repository to associate the full-scan with.
        schema:
          type: string
      - name: workspace
        in: query
        required: false
        description: The workspace of the repository to associate the full-scan with.
        schema:
          type: string
      - name: branch
        in: query
        required: false
        description: 'The branch name to associate the full-scan with. Branch names must follow Git branch name rules: be 1–255 characters long; cannot be exactly @;  cannot begin or end with /, ., or .lock; cannot contain "//", "..", or "@{"; and cannot include control characters, spaces, or any of ~^:?*[.'
        schema:
          type: string
      - name: commit_message
        in: query
        required: false
        description: The commit message to associate the full-scan with.
        schema:
          type: string
      - name: commit_hash
        in: query
        required: false
        description: The commit hash to associate the full-scan with.
        schema:
          type: string
      - name: pull_request
        in: query
        required: false
        description: The pull request number to associate the full-scan with.
        schema:
          type: integer
          minimum: 1
      - name: committers
        in: query
        required: false
        description: The committers to associate with the full-scan. Set query more than once to set multiple.
        schema:
          type: string
      - name: integration_type
        in: query
        required: false
        description: The integration type to associate the full-scan with. Defaults to "Api" if omitted.
        schema:
          type: string
          enum:
          - api
          - github
          - gitlab
          - bitbucket
          - azure
          - web
      - name: integration_org_slug
        in: query
        required: false
        description: The integration org slug to associate the full-scan with. If omitted, the Socket org name will be used. This is used to generate links and badges.
        schema:
          type: string
      - name: make_default_branch
        in: query
        required: false
        description: Set the default branch of the repository to the branch of this full-scan. A branch name is required with this option.
        schema:
          type: boolean
          default: false
      - name: set_as_pending_head
        in: query
        required: false
        description: Designate this full-scan as the latest scan of a given branch. Default branch head scans are included in org alerts. This is only supported on the default branch. A branch name is required with this option.
        schema:
          type: boolean
          default: false
      - name: tmp
        in: query
        required: false
        description: Create a temporary full-scan that is not listed in the reports dashboard. Cannot be used when set_as_pending_head=true.
        schema:
          type: boolean
          default: false
      - name: scan_type
        in: query
        required: false
        description: The type of scan to perform. Defaults to 'socket'. Must be 32 characters or less. Used for categorizing multiple SBOM heads per repository branch.
        schema:
          type: string
          default: socket
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties:
                type: string
                default:
                  type: Buffer
                  data: []
                format: binary
                description: ''
              properties: {}
              description: ''
        required: false
      security:
      - bearerAuth:
        - full-scans:create
      - basicAuth:
        - full-scans:create
      description: 'Create a full scan from a set of package manifest files. Returns a full scan including all SBOM artifacts.


        To get a list of supported filetypes that can be uploaded in a full-scan, see the [Get supported file types](/reference/getsupportedfiles) endpoint.


        The maximum number of files you can upload at a time is 5000 and each file can be no bigger than 268 MB.


        **Query Parameters:**

        - `scan_type` (optional): The type of scan to perform. Defaults to ''socket''. Must be 32 characters or less. Used for categorizing multiple SBOM heads per repository branch.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - full-scans:create'
      responses:
        '201':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: ''
                    default: ''
                  created_at:
                    type: string
                    description: ''
                    default: ''
                  updated_at:
                    type: string
                    description: ''
                    default: ''
                  organization_id:
                    type: string
                    description: ''
                    default: ''
                  organization_slug:
                    type: string
                    description: ''
                    default: ''
                  repository_id:
                    type: string
                    description: ''
                    default: ''
                  repository_slug:
                    type: string
                    description: ''
                    default: ''
                  branch:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  commit_message:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  commit_hash:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  pull_request:
                    type: integer
                    description: ''
                    default: 0
                    nullable: true
                  committers:
                    type: array
                    items:
                      type: string
                      description: ''
                      default: ''
                    description: ''
                  html_url:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  api_url:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  workspace:
                    type: string
                    description: ''
                    default: ''
                  repo:
                    type: string
                    description: ''
                    default: ''
                  html_report_url:
                    type: string
                    description: ''
                    default: ''
                  integration_type:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  integration_repo_url:
                    type: string
                    description: ''
                    default: ''
                  integration_branch_url:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  integration_commit_url:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  integration_pull_request_url:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  scan_type:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  scan_state:
                    type: string
                    enum:
                    - pending
                    - precrawl
                    - resolve
                    - scan
                    description: The current processing status of the SBOM
                    default: pending
                    nullable: true
                  unmatchedFiles:
                    type: array
                    items:
                      type: string
                      description: ''
                      default: ''
                    description: ''
                description: ''
          description: The details of the created full scan.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /orgs/{org_slug}/full-scans/{full_scan_id}:
    get:
      tags:
      - full-scans
      summary: Stream full scan
      operationId: getOrgFullScan
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: full_scan_id
        in: path
        required: true
        description: The ID of the full scan
        schema:
          type: string
      - name: include_alert_priority_details
        in: query
        required: false
        description: Control which alert priority fields to include in the response. Set to "true" to include all fields, "false" to exclude all fields, or specify individual fields like "components,formula" to include only those fields.
        schema:
          oneOf:
          - type: boolean
            default: false
          - type: array
            items:
              type: string
              enum:
              - component
              - formula
          default: false
      - name: include_scores
        in: query
        required: true
        description: Include scores event in the response. include_scores_details implies this flag
        schema:
          type: boolean
          default: false
      - name: include_scores_details
        in: query
        required: false
        description: Control which score detail fields to include in the scores event. Set to "true" to include all fields, "false" to exclude all fields, or specify individual fields like "components,formula" to include only those fields.
        schema:
          oneOf:
          - type: boolean
            default: false
          - type: array
            items:
              type: string
              enum:
              - components
              - formula
          default: false
      - name: include_license_details
        in: query
        required: true
        description: Include license details in the response. This can increase the response size significantly.
        schema:
          type: boolean
          default: false
      - name: cached
        in: query
        required: false
        description: Return cached immutable scan results. When enabled and results are cached, returns the pre-computed scan. When results are not yet cached, returns 202 Accepted and enqueues a background job.
        schema:
          type: boolean
          default: false
      security:
      - bearerAuth:
        - full-scans:list
      - basicAuth:
        - full-scans:list
      description: 'Stream all SBOM artifacts for a full scan.


        This endpoint returns the latest, available alert data for artifacts in the full scan (stale while revalidate).

        Actively running analysis will be returned when available on subsequent runs.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - full-scans:list'
      responses:
        '200':
          content:
            application/x-ndjson:
              schema:
                anyOf:
                - $ref: '#/components/schemas/SocketArtifact'
                - type: object
                  additionalProperties: false
                  properties:
                    _type:
                      type: string
                      enum:
                      - scores
                    value:
                      $ref: '#/components/schemas/SocketSBOMScore'
                  required:
                  - _type
                  - value
          description: Socket issue lists and scores for all packages, followed by a final scores event
        '202':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  status:
                    type: string
                    description: ''
                    default: processing
                  id:
                    type: string
                    description: ''
                    default: ''
                required:
                - id
                - status
          description: Scan is being processed. Poll again later to retrieve results.
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
    delete:
      tags:
      - full-scans
      summary: Delete full scan
      operationId: deleteOrgFullScan
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: full_scan_id
        in: path
        required: true
        description: The ID of the full scan
        schema:
          type: string
      security:
      - bearerAuth:
        - full-scans:delete
      - basicAuth:
        - full-scans:delete
      description: 'Delete an existing full scan.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - full-scans:delete'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  status:
                    type: string
                    description: ''
                    default: ok
                required:
                - status
          description: Success
        '400':
          $ref: '#/components/responses/SocketBadRequest'
        '401':
          $ref: '#/components/responses/SocketUnauthorized'
        '403':
          $ref: '#/components/responses/SocketForbidden'
        '404':
          $ref: '#/components/responses/SocketNotFoundResponse'
        '429':
          $ref: '#/components/responses/SocketTooManyRequestsResponse'
      x-readme: {}
  /orgs/{org_slug}/full-scans/{full_scan_id}/metadata:
    get:
      tags:
      - full-scans
      summary: Get full scan metadata
      operationId: getOrgFullScanMetadata
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: full_scan_id
        in: path
        required: true
        description: The ID of the full scan
        schema:
          type: string
      security:
      - bearerAuth:
        - full-scans:list
      - basicAuth:
        - full-scans:list
      description: 'Get metadata for a single full scan


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - full-scans:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  id:
                    type: string
                    description: ''
                    default: ''
                  created_at:
                    type: string
                    description: ''
                    default: ''
                  updated_at:
                    type: string
                    description: ''
                    default: ''
                  organization_id:
                    type: string
                    description: ''
                    default: ''
                  organization_slug:
                    type: string
                    description: ''
                    default: ''
                  repository_id:
                    type: string
                    description: ''
                    default: ''
                  repository_slug:
                    type: string
                    description: ''
                    default: ''
                  branch:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
  

# --- truncated at 32 KB (121 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-dev-full-scans-api-openapi.yml