socket-triage-api-openapi.yml

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