Socket
Socket Triage API

Triage workflow for alerts — list and update the disposition (ignore, acknowledge, escalate, allow) of any alert in an organization. Comments and decision history are recorded for audit. Triage is the human-in-the-loop counterpart to Socket's automated security gates.
Socket Triage 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 Triage, Alerts, Workflow, and Governance. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 1 Naftiko capability spec.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  description: Socket triage API endpoints.
  title: Socket Triage API
  version: '0'
servers:
- url: https://api.socket.dev/v0
paths:
  /orgs/{org_slug}/triage/alerts:
    get:
      tags:
      - triage
      summary: List Org Alert Triage
      operationId: getOrgTriage
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: sort
        in: query
        required: false
        description: 'Field to sort by. One of: created_at, updated_at.'
        schema:
          type: string
          default: created_at
      - name: direction
        in: query
        required: false
        description: 'Sort direction. One of: asc, desc.'
        schema:
          type: string
          default: desc
      - name: per_page
        in: query
        required: false
        description: Number of results per page (1–100, default 30).
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
      - name: page
        in: query
        required: false
        description: Page number (1-based).
        schema:
          type: integer
          minimum: 1
          default: 1
      security:
      - bearerAuth:
        - triage:alerts-list
      - basicAuth:
        - triage:alerts-list
      description: 'List triage actions for an organization. Results are paginated and can be sorted by created_at or updated_at.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - triage:alerts-list'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      additionalProperties: false
                      properties:
                        uuid:
                          type: string
                          description: The uuid of the triage action
                          default: ''
                          nullable: true
                        package_type:
                          type: string
                          description: The package type associated with the triage state
                          default: ''
                          nullable: true
                        package_namespace:
                          type: string
                          description: The package namespace associated with the triage state
                          default: ''
                          nullable: true
                        package_name:
                          type: string
                          description: The package name associated with the triage state
                          default: ''
                          nullable: true
                        package_version:
                          type: string
                          description: The package version associated with the triage state, it can contain a * suffix for wildcard matching
                          default: ''
                          nullable: true
                        alert_key:
                          type: string
                          description: The alert_key associated with the triage state
                          default: ''
                          nullable: true
                        alert_type:
                          type: string
                          description: The alert type (e.g., criticalCVE, highCVE) associated with the triage state
                          default: ''
                          nullable: true
                        fix_available:
                          type: string
                          enum:
                          - available
                          - unavailable
                          - '*'
                          description: Whether a fix must be available, unavailable, or * for any
                          default: '*'
                          nullable: true
                        patch_available:
                          type: string
                          enum:
                          - available
                          - unavailable
                          - '*'
                          description: Whether a patch must be available, unavailable, or * for any
                          default: '*'
                          nullable: true
                        cvss_score_cmp:
                          type: string
                          description: CVSS score comparison (e.g., >=7.5, >5.0, ==8.0)
                          default: ''
                          nullable: true
                        created_at:
                          type: string
                          description: The creation date of the triage action
                          default: ''
                        updated_at:
                          type: string
                          description: The last update date of the triage action
                          default: ''
                        note:
                          type: string
                          description: The note associated with the triage action
                          default: ''
                        organization_id:
                          type: string
                          description: The organization id associated with the triage action
                          default: ''
                        state:
                          type: string
                          enum:
                          - block
                          - ignore
                          - inherit
                          - monitor
                          - warn
                          description: The triage state of the alert
                          default: inherit
                        cve_or_ghsa_id:
                          type: string
                          description: CVE or GHSA ID associated with the triage state
                          default: ''
                          nullable: true
                        reachability:
                          type: string
                          enum:
                          - reachable
                          - unreachable
                          - other
                          - '*'
                          description: The reachability of the alert, can be reachable, unreachable, other, or * for any
                          default: '*'
                          nullable: true
                        kevs:
                          type: string
                          enum:
                          - exist
                          - none
                          - '*'
                          description: Whether the alert has a CISA KEV (Known Exploited Vulnerability), can be exist, none, or * for any
                          default: '*'
                          nullable: true
                      description: ''
                    description: ''
                  nextPage:
                    type: integer
                    description: ''
                    default: 0
                    nullable: true
                required:
                - nextPage
                - results
          description: Lists triage actions 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: {}
    post:
      tags:
      - triage
      summary: Create/Update Org Alert Triage
      operationId: updateOrgAlertTriage
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: force
        in: query
        required: false
        description: Set to true to force broad triage updates, these are triages lacking a specific alertKey or granular artifact information which may have limited introspection to see what they apply
          to.
        schema:
          type: string
          default: 'false'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              description: ''
              properties:
                alertTriage:
                  type: array
                  items:
                    type: object
                    additionalProperties: false
                    properties:
                      uuid:
                        type: string
                        description: The UUID of the triage entry. Omit to create a new entry; provide to update an existing one.
                        default: ''
                        nullable: true
                      packageType:
                        type: string
                        description: The package ecosystem type (e.g., npm, pypi). Use null or "*" for wildcard.
                        default: ''
                        nullable: true
                      packageNamespace:
                        type: string
                        description: The package namespace or scope. Use null or "*" for wildcard.
                        default: ''
                        nullable: true
                      packageName:
                        type: string
                        description: The package name. Use null or "*" for wildcard.
                        default: ''
                        nullable: true
                      packageVersion:
                        type: string
                        description: The package version. Supports a "*" suffix for wildcard prefix matching. Use null for any version.
                        default: ''
                        nullable: true
                      alertKey:
                        type: string
                        description: The specific alert key to target.
                        default: ''
                        nullable: true
                      alertType:
                        type: string
                        description: The alert type (e.g., criticalCVE, highCVE).
                        default: ''
                        nullable: true
                      fixAvailable:
                        type: string
                        enum:
                        - available
                        - unavailable
                        - '*'
                        description: Whether a fix is available, unavailable, or * for any
                      patchAvailable:
                        type: string
                        enum:
                        - available
                        - unavailable
                        - '*'
                        description: Whether a patch is available, unavailable, or * for any
                      kevs:
                        type: string
                        enum:
                        - exist
                        - none
                        - '*'
                        description: Whether the alert has a CISA KEV, can be exist, none, or * for any
                      cveOrGhsaId:
                        type: string
                        description: CVE or GHSA ID to match against.
                        default: ''
                        nullable: true
                      reachability:
                        type: string
                        enum:
                        - reachable
                        - unreachable
                        - other
                        - '*'
                        description: The reachability of the alert, can be reachable, unreachable, other, or * for any
                      cvssScoreCmp:
                        type: string
                        description: CVSS score comparison operator and value (e.g., >=7.5, >5.0, ==8.0).
                        default: ''
                        nullable: true
                      note:
                        type: string
                        description: A note or comment for the triage action.
                        default: ''
                      state:
                        type: string
                        enum:
                        - block
                        - ignore
                        - inherit
                        - monitor
                        - warn
                        description: The triage state of the alert
                    description: ''
                  description: ''
              required:
              - alertTriage
        required: false
      security:
      - bearerAuth:
        - triage:alerts-update
      - basicAuth:
        - triage:alerts-update
      description: 'Create or update triage actions on organization alerts. Accepts a batch of triage entries. Omit `uuid` to create a new entry; provide an existing `uuid` to update it. Use `?force=true`
        for broad triages that lack a specific `alertKey` or granular package information.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - triage:alerts-update'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  result:
                    type: string
                    description: ''
                    default: ''
                required:
                - result
          description: Updated Alert Triage
        '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}/triage/alerts/{uuid}:
    delete:
      tags:
      - triage
      summary: Delete Org Alert Triage
      operationId: deleteOrgAlertTriage
      parameters:
      - name: org_slug
        in: path
        required: true
        description: The slug of the organization
        schema:
          type: string
      - name: uuid
        in: path
        required: true
        description: The UUID of the alert triage entry to delete
        schema:
          type: string
      security:
      - bearerAuth:
        - triage:alerts-update
      - basicAuth:
        - triage:alerts-update
      description: 'Delete a specific triage rule by UUID.


        This endpoint consumes 1 unit of your quota.


        This endpoint requires the following org token scopes:

        - triage:alerts-update'
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  result:
                    type: string
                    description: ''
                    default: ''
                required:
                - result
          description: Deleted Alert Triage
        '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: {}
components:
  requestBodies: {}
  responses:
    SocketBadRequest:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Bad request
    SocketUnauthorized:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Unauthorized
    SocketForbidden:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Insufficient max_quota for API method
    SocketNotFoundResponse:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource not found
    SocketTooManyRequestsResponse:
      description: Insufficient quota for API route
      headers:
        Retry-After:
          description: 'Retry contacting the endpoint *at least* after seconds.

            See https://tools.ietf.org/html/rfc7231#section-7.1.3'
          schema:
            format: int32
            type: integer
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
    SocketInternalServerError:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Internal server error
    SocketConflict:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Resource already exists
    SocketGone:
      content:
        application/json:
          schema:
            type: object
            additionalProperties: false
            description: ''
            properties:
              error:
                type: object
                additionalProperties: false
                description: ''
                properties:
                  message:
                    type: string
                    description: ''
                    default: ''
                  details:
                    type: object
                    description: ''
                    default: null
                    nullable: true
                required:
                - details
                - message
            required:
            - error
      description: Gone
  schemas: {}
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Organization Tokens can be passed as a Bearer token
    basicAuth:
      type: http
      scheme: basic
      description: Organization Tokens can be passed as the user field in basic auth
Socket Triage API

Documentation

Specifications

Other Resources

OpenAPI Specification
