Socket

Socket Diff Scans API

Compute and inspect diff scans between two full scans — the engine that powers Socket's pull-request comments. Identifies added, removed, and modified dependencies with their security implications. Returns added/removed alerts in JSON or GFM markdown. Diff scans can be created from full-scan IDs or from a target repo branch.

Socket Diff Scans API is one of 15 APIs that Socket publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 1 machine-runnable capability that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.

Tagged areas include Diff Scans, Supply Chain Security, Pull Request, and Change Detection. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.

GitHub OpenAPI

Documentation

📖
Documentation
https://docs.socket.dev/reference/createorgdiffscanfromids

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/openapi/socket-diff-scans-api-openapi.yml

Other Resources

🔗
NaftikoCapability
https://raw.githubusercontent.com/api-evangelist/socket-dev/refs/heads/main/capabilities/diff-scans-diff-scans.yaml

OpenAPI Specification

socket-diff-scans-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  description: Socket diff scans API endpoints.
  title: Socket Diff Scans API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /orgs/{org_slug}/diff-scans:
    get:
      tags:
      - diff-scans
      summary: List diff scans
      operationId: listOrgDiffScans
      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 field.
        schema:
          type: string
          enum:
          - created_at
          - updated_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: 20
      - name: cursor
        in: query
        required: false
        description: Cursor for pagination. Use the next_cursor or prev_cursor from previous responses.
        schema:
          type: string
      - name: repository_id
        in: query
        required: false
        description: Filter by repository ID.
        schema:
          type: string
      - name: before_full_scan_id
        in: query
        required: false
        description: Filter by before full scan ID.
        schema:
          type: string
      - name: after_full_scan_id
        in: query
        required: false
        description: Filter by after full scan ID.
        schema:
          type: string
      security:
      - bearerAuth:
        - diff-scans:list
      - basicAuth:
        - diff-scans:list
      description: 'Returns a paginated list of all diff scans in an organization.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - diff-scans:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      description: ''
                      properties:
                        id:
                          type: string
                          description: ''
                          default: ''
                        organization_id:
                          type: string
                          description: ''
                          default: ''
                        repository_id:
                          type: string
                          description: ''
                          default: ''
                        created_at:
                          type: string
                          description: ''
                          default: ''
                        updated_at:
                          type: string
                          description: ''
                          default: ''
                        before_full_scan_id:
                          type: string
                          description: ''
                          default: ''
                        after_full_scan_id:
                          type: string
                          description: ''
                          default: ''
                        description:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        external_href:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        merge:
                          type: boolean
                          default: false
                          description: ''
                        html_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                        api_url:
                          type: string
                          description: ''
                          default: ''
                          nullable: true
                      required:
                      - after_full_scan_id
                      - api_url
                      - before_full_scan_id
                      - created_at
                      - description
                      - external_href
                      - html_url
                      - id
                      - merge
                      - organization_id
                      - repository_id
                      - updated_at
                    description: ''
                  next_page_href:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                  next_cursor:
                    type: string
                    description: ''
                    default: ''
                    nullable: true
                required:
                - next_cursor
                - next_page_href
                - results
          description: Lists diff scans for the specified 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: {}
  /orgs/{org_slug}/diff-scans/{diff_scan_id}:
    get:
      tags:
      - diff-scans
      summary: Get diff scan
      operationId: getDiffScanById
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: diff_scan_id
        in: path
        required: true
        description: The ID of the diff scan
        schema:
          type: string
          format: uuid
      - name: omit_license_details
        in: query
        required: false
        description: Omit license details in the response. This can reduce the size of the response significantly, but will not include license information for the artifacts.
        schema:
          type: boolean
          default: false
      - name: omit_unchanged
        in: query
        required: false
        description: Omit unchanged artifacts from the response. When set to true, the unchanged field will be set to null.
        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. Note: When cached=true, the omit_license_details parameter is ignored as cached results always includes license details.'
        schema:
          type: boolean
          default: false
      security:
      - bearerAuth:
        - diff-scans:list
      - basicAuth:
        - diff-scans:list
      description: 'Get the difference between two full scans from an existing diff scan resource.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - diff-scans:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  diff_scan:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      id:
                        type: string
                        description: ''
                        default: ''
                      organization_id:
                        type: string
                        description: ''
                        default: ''
                      repository_id:
                        type: string
                        description: ''
                        default: ''
                      created_at:
                        type: string
                        description: ''
                        default: ''
                      updated_at:
                        type: string
                        description: ''
                        default: ''
                      before_full_scan:
                        type: object
                        additionalProperties: false
                        description: ''
                        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
                        required:
                        - api_url
                        - branch
                        - commit_hash
                        - commit_message
                        - committers
                        - created_at
                        - html_url
                        - id
                        - organization_id
                        - organization_slug
                        - pull_request
                        - repository_id
                        - repository_slug
                        - updated_at
                      after_full_scan:
                        type: object
                        additionalProperties: false
                        description: ''
                        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
                        required:
                        - api_url
                        - branch
                        - commit_hash
                        - commit_message
                        - committers
                        - created_at
                        - html_url
                        - id
                        - organization_id
                        - organization_slug
                        - pull_request
                        - repository_id
                        - repository_slug
                        - updated_at
                      description:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      external_href:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      merge:
                        type: boolean
                        default: false
                        description: ''
                      html_url:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      api_url:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      artifacts:
                        type: object
                        additionalProperties: false
                        description: ''
                        properties:
                          added:
                            type: array
                            items:
                              $ref: '#/components/schemas/SocketDiffArtifact'
                            description: ''
                          removed:
                            type: array
                            items:
                              $ref: '#/components/schemas/SocketDiffArtifact'
                            description: ''
                          unchanged:
                            type: array
                            items:
                              $ref: '#/components/schemas/SocketDiffArtifact'
                            description: ''
                            nullable: true
                          replaced:
                            type: array
                            items:
                              $ref: '#/components/schemas/SocketDiffArtifact'
                            description: ''
                          updated:
                            type: array
                            items:
                              $ref: '#/components/schemas/SocketDiffArtifact'
                            description: ''
                        required:
                        - added
                        - removed
                        - replaced
                        - unchanged
                        - updated
                    required:
                    - after_full_scan
                    - api_url
                    - artifacts
                    - before_full_scan
                    - created_at
                    - description
                    - external_href
                    - html_url
                    - id
                    - merge
                    - organization_id
                    - repository_id
                    - updated_at
                required:
                - diff_scan
          description: The difference between the two Full Scans in the diff scan.
        '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:
      - diff-scans
      summary: Delete diff scan
      operationId: deleteOrgDiffScan
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: diff_scan_id
        in: path
        required: true
        description: The ID of the diff scan
        schema:
          type: string
          format: uuid
      security:
      - bearerAuth:
        - diff-scans:delete
      - basicAuth:
        - diff-scans:delete
      description: 'Delete an existing diff scan.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - diff-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}/diff-scans/{diff_scan_id}/gfm:
    get:
      tags:
      - diff-scans
      summary: SCM Comment for Diff Scan
      operationId: GetDiffScanGfm
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: diff_scan_id
        in: path
        required: true
        description: The ID of the diff scan
        schema:
          type: string
          format: uuid
      - name: github_installation_id
        in: query
        required: false
        description: The ID of the GitHub installation. This will be used to get the GitHub installation settings. If not provided, the default GitHub installation settings will be used.
        schema:
          type: string
      security:
      - bearerAuth:
        - diff-scans:list
      - basicAuth:
        - diff-scans:list
      description: 'Get the dependency overview and dependency alert comments in GitHub flavored markdown for an existing diff scan.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - diff-scans:list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  diff_scan:
                    type: object
                    additionalProperties: false
                    description: ''
                    properties:
                      id:
                        type: string
                        description: ''
                        default: ''
                      organization_id:
                        type: string
                        description: ''
                        default: ''
                      repository_id:
                        type: string
                        description: ''
                        default: ''
                      created_at:
                        type: string
                        description: ''
                        default: ''
                      updated_at:
                        type: string
                        description: ''
                        default: ''
                      before_full_scan:
                        type: object
                        additionalProperties: false
                        description: ''
                        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
                        required:
                        - api_url
                        - branch
                        - commit_hash
                        - commit_message
                        - committers
                        - created_at
                        - html_url
                        - id
                        - organization_id
                        - organization_slug
                        - pull_request
                        - repository_id
                        - repository_slug
                        - updated_at
                      after_full_scan:
                        type: object
                        additionalProperties: false
                        description: ''
                        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
                        required:
                        - api_url
                        - branch
                        - commit_hash
                        - commit_message
                        - committers
                        - created_at
                        - html_url
                        - id
                        - organization_id
                        - organization_slug
                        - pull_request
                        - repository_id
                        - repository_slug
                        - updated_at
                      description:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      external_href:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      merge:
                        type: boolean
                        default: false
                        description: ''
                      html_url:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      api_url:
                        type: string
                        description: ''
                        default: ''
                        nullable: true
                      gfm:
                        type: object
                        additionalProperties: false
                        description: ''
                        properties:
                          overview:
                            type: string
                            description: ''
                            default: ''
                          alerts:
                            type: string
                            description: ''
                            default: ''
                        required:
                        - alerts
                        - overview
                    required:
                    - after_full_scan
                    - api_url
                    - before_full_scan
                    - created_at
                    - desc

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