> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zdlake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search weaknesses

> Search normalized weakness records.

Search weakness records with text, identifiers, recursive conditions, sorting, and cursor pagination. The resource path fixes the entity type, so do not add an `entity` condition.

Common weakness conditions include `id`, `alias`, `record_state`, `published_at`, and `updated_at`. See [Query builder](https://docs.zdlake.com/api/query-builder.md) for their operators.


## OpenAPI

````yaml POST /weaknesses
openapi: 3.1.0
info:
  title: Zero API
  version: 0.0.0
  description: Normalized public vulnerability intelligence.
servers:
  - url: https://api.zdlake.com
    description: Production API
security:
  - BearerAuth: []
  - ApiKeyAuth: []
paths:
  /weaknesses:
    post:
      tags:
        - Entities
      summary: Search weakness records
      description: >-
        A recurring class of design or implementation error that may cause
        multiple vulnerabilities. CWE is the preferred public taxonomy.
      operationId: search_weaknesses
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - name: cursor
          in: query
          required: false
          description: >-
            Opaque cursor carried by _meta.next.url. Reuse the previous request
            body unchanged.
          schema:
            type: string
            minLength: 1
            maxLength: 4096
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              basic:
                summary: Basic search
                value:
                  q: log4j
                  limit: 20
              composed:
                summary: Composed query
                value:
                  where:
                    logical_operator: and
                    conditions:
                      - field: cvss
                        operator: gte
                        value: 9
                      - field: cisa_kev
                        operator: equals
                        value: true
                  sort:
                    - field: epss
                      order: desc
                    - field: cvss
                      order: desc
                  limit: 50
      responses:
        '200':
          description: A cursor-paginated collection of normalized records.
          headers:
            X-API-Version:
              description: API contract version used to process the request.
              schema:
                type: string
                example: '2026-08-19'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                data:
                  - entity: weakness
                    entity_id: 0198b4ba-d354-7eef-87e0-ff21496ea234
                    id: CWE-79
                    aliases: []
                    title: >-
                      Improper Neutralization of Input During Web Page
                      Generation
                    summary: >-
                      Untrusted input is not neutralized before it is written to
                      a web page.
                    published_at: '2006-07-19T00:00:00Z'
                    first_seen_at: '2026-08-01T05:12:43Z'
                    updated_at: '2026-08-18T04:20:11Z'
                    cvss: null
                    cvss_severity: null
                    epss: null
                    record_state: stable
                    exploitation:
                      status: unknown
                      exploited_as_zero_day: null
                      cisa_kev: false
                    weaknesses: []
                    ecosystems: []
                    software_kind: null
                    purls: []
                    cpes: []
                _meta:
                  total: 1
                  limit: 20
                  current:
                    cursor: null
                    url: https://api.zdlake.com/weaknesses
                  next: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    ApiVersion:
      name: X-API-Version
      in: header
      required: false
      description: >-
        API contract version. Omit to use the latest public version. Current
        supported value: 2026-08-19.
      schema:
        type: string
        enum:
          - '2026-08-19'
        default: '2026-08-19'
  schemas:
    SearchRequest:
      type: object
      additionalProperties: false
      oneOf:
        - properties:
            sort:
              type: string
              enum:
                - relevance
                - id
                - updated
                - first_seen
                - published
                - cvss
                - epss
                - record_state
                - exploitation
                - aliases
                - weaknesses
                - ecosystems
                - ecosystem
                - software_kind
                - purl
            order:
              type: string
              enum:
                - asc
                - desc
        - required:
            - sort
          properties:
            sort:
              type: array
              minItems: 1
              maxItems: 10
              items:
                $ref: '#/components/schemas/SortClause'
          not:
            required:
              - order
      properties:
        q:
          type: string
          description: >-
            Full-text query. Recognized security identifiers are treated as
            exact identifier lookups.
          example: log4j
        id:
          type: string
          description: >-
            A CVE is one possible public identifier for a vulnerability. It is
            not a severity or exploitation status.
          example: CVE-2021-44228
        entity:
          type: array
          description: Restrict mixed /search results to one or more entity types.
          items:
            type: string
            enum:
              - vulnerability
              - advisory
              - weakness
              - software
              - attack-pattern
        where:
          $ref: '#/components/schemas/QueryGroup'
        include:
          type: array
          description: Optional projections to include.
          items:
            type: string
            enum:
              - attributes
              - provenance
              - conflicts
              - relationships
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        sort:
          oneOf:
            - type: string
              enum:
                - relevance
                - id
                - updated
                - first_seen
                - published
                - cvss
                - epss
                - record_state
                - exploitation
                - aliases
                - weaknesses
                - ecosystems
                - ecosystem
                - software_kind
                - purl
            - type: array
              minItems: 1
              maxItems: 10
              items:
                $ref: '#/components/schemas/SortClause'
          description: >-
            An ordered array composes multiple sort fields. A single string
            remains supported for compatibility. relevance cannot be composed,
            and software_kind requires an effective software entity scope.
          example:
            - field: cvss
              order: desc
            - field: epss
              order: desc
        software_kind:
          type: array
          items:
            type: string
            enum:
              - package
              - application
              - operating_system
              - appliance
              - hardware
              - firmware
        software_kind_not:
          type: array
          items:
            type: string
            enum:
              - package
              - application
              - operating_system
              - appliance
              - hardware
              - firmware
        affected_software:
          type: array
          items:
            type: string
          example:
            - pkg:npm/react
            - cpe:2.3:o:linux:linux_kernel:*:*:*:*:*:*:*:*
        affected_software_not:
          type: array
          items:
            type: string
          example:
            - pkg:npm/react
        affected_software_contains:
          type: string
          example: npm/react
        affected_software_not_contains:
          type: string
          example: npm/react
        purl:
          type: array
          items:
            type: string
            example: pkg:npm/react
          example:
            - pkg:npm/react
        purl_not:
          type: array
          items:
            type: string
            example: pkg:npm/react
          example:
            - pkg:npm/react
        purl_contains:
          type: string
          example: npm/react
        purl_not_contains:
          type: string
          example: npm/react
        cpe:
          type: array
          items:
            type: string
            example: cpe:2.3:o:linux:linux_kernel:*:*:*:*:*:*:*:*
          example:
            - cpe:2.3:o:linux:linux_kernel:*:*:*:*:*:*:*:*
        cpe_not:
          type: array
          items:
            type: string
            example: cpe:2.3:o:linux:linux_kernel:*:*:*:*:*:*:*:*
          example:
            - cpe:2.3:o:linux:linux_kernel:*:*:*:*:*:*:*:*
        cpe_contains:
          type: string
          example: linux_kernel
        cpe_not_contains:
          type: string
          example: linux_kernel
        order:
          type: string
          enum:
            - asc
            - desc
          description: >-
            Legacy direction used only when sort is a single string. Ordered
            sort clauses include their own direction.
    SearchResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SearchResult'
        _meta:
          $ref: '#/components/schemas/PageMeta'
      required:
        - data
        - _meta
    SortClause:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          enum:
            - relevance
            - id
            - updated
            - first_seen
            - published
            - cvss
            - epss
            - record_state
            - exploitation
            - aliases
            - weaknesses
            - ecosystems
            - ecosystem
            - software_kind
            - purl
        order:
          type: string
          enum:
            - asc
            - desc
      required:
        - field
        - order
      example:
        field: cvss
        order: desc
    QueryGroup:
      type: object
      additionalProperties: false
      properties:
        logical_operator:
          type: string
          enum:
            - and
            - or
          description: Boolean operator used to combine child conditions.
        conditions:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Query'
          description: >-
            Nested conditions or groups. A request may contain at most 20
            condition leaves.
      required:
        - logical_operator
        - conditions
    SearchResult:
      type: object
      properties:
        entity:
          type: string
          enum:
            - vulnerability
            - advisory
            - weakness
            - software
            - attack-pattern
        entity_id:
          type: string
        id:
          type: string
        aliases:
          type: array
          items:
            type: string
        title:
          type: string
        summary:
          anyOf:
            - type: string
            - type: 'null'
        published_at:
          anyOf:
            - type: string
            - type: 'null'
        first_seen_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        cvss:
          anyOf:
            - type: number
            - type: 'null'
        cvss_severity:
          anyOf:
            - type: string
            - type: 'null'
        epss:
          anyOf:
            - type: number
            - type: 'null'
        record_state:
          anyOf:
            - type: string
            - type: 'null'
        exploitation:
          description: >-
            Exploitation evidence retains its source, time, confidence, and
            cited resources. Public proof of concept and active exploitation are
            separate claims.
          type: object
          properties:
            status:
              type: string
              enum:
                - confirmed
                - unknown
            exploited_as_zero_day:
              anyOf:
                - type: boolean
                - type: 'null'
            cisa_kev:
              type: boolean
          required:
            - status
            - exploited_as_zero_day
            - cisa_kev
        weaknesses:
          type: array
          items:
            type: string
        ecosystems:
          type: array
          items:
            type: string
        software_kind:
          anyOf:
            - type: string
              enum:
                - package
                - application
                - operating_system
                - appliance
                - hardware
                - firmware
            - type: 'null'
        purls:
          type: array
          items:
            type: string
        cpes:
          type: array
          items:
            type: string
        affected_software:
          type: array
          items:
            $ref: '#/components/schemas/SoftwareSummary'
      required:
        - entity
        - entity_id
        - id
        - aliases
        - title
        - summary
        - published_at
        - first_seen_at
        - updated_at
        - cvss
        - cvss_severity
        - epss
        - record_state
        - exploitation
        - weaknesses
        - ecosystems
        - software_kind
        - purls
        - cpes
    PageMeta:
      type: object
      properties:
        total:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
        current:
          type: object
          properties:
            cursor:
              anyOf:
                - type: string
                - type: 'null'
            url:
              type: string
              format: uri
          required:
            - cursor
            - url
        next:
          anyOf:
            - type: object
              properties:
                cursor:
                  type: string
                url:
                  type: string
                  format: uri
              required:
                - cursor
                - url
            - type: 'null'
      required:
        - total
        - limit
        - current
        - next
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          example: https://docs.zdlake.com/api/errors#bad-request
        title:
          type: string
          example: Bad Request
        status:
          type: integer
          minimum: 400
          maximum: 599
          example: 400
        detail:
          type: string
          example: Invalid request parameters
        code:
          type: string
          example: VALIDATION_ERROR
          enum:
            - UNAUTHORIZED
            - INVALID_API_KEY
            - EXPIRED_API_KEY
            - REVOKED_API_KEY
            - FORBIDDEN
            - RATE_LIMITED
            - VALIDATION_ERROR
            - BAD_REQUEST
            - NOT_FOUND
            - INTERNAL_ERROR
        request_id:
          type: string
          example: req_01J7Y8Z9ABCDEF0123456789AB
        errors:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
          example:
            limit:
              - Number must be less than or equal to 100
      required:
        - type
        - title
        - status
        - detail
        - code
        - request_id
    Query:
      description: >-
        Recursive query-builder node. Use a condition for one predicate or a
        group to combine nested predicates with AND/OR.
      example:
        logical_operator: and
        conditions:
          - field: cvss
            operator: gte
            value: 9
          - logical_operator: or
            conditions:
              - field: cisa_kev
                operator: equals
                value: true
              - field: exploited_as_zero_day
                operator: equals
                value: true
      oneOf:
        - $ref: '#/components/schemas/QueryCondition'
        - $ref: '#/components/schemas/QueryGroup'
    SoftwareSummary:
      type: object
      properties:
        entity:
          const: software
        entity_id:
          type: string
        id:
          type: string
        title:
          type: string
        software_kind:
          anyOf:
            - type: string
              enum:
                - package
                - application
                - operating_system
                - appliance
                - hardware
                - firmware
            - type: 'null'
        ecosystems:
          type: array
          items:
            type: string
      required:
        - entity
        - entity_id
        - id
        - title
        - software_kind
        - ecosystems
    JsonValue:
      oneOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/JsonValue'
        - type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonValue'
    QueryCondition:
      type: object
      additionalProperties: false
      properties:
        field:
          type: string
          enum:
            - id
            - entity
            - alias
            - record_state
            - published_at
            - updated_at
            - cvss
            - epss
            - exploitation_status
            - exploited_as_zero_day
            - cisa_kev
            - weakness
            - ecosystem
            - software_kind
            - affected_software
            - purl
            - cpe
          description: Queryable entity field.
          example: cvss
        operator:
          type: string
          enum:
            - equals
            - not_equals
            - contains
            - not_contains
            - gt
            - gte
            - lt
            - lte
            - in
            - not_in
            - array_has_any
            - array_has_all
            - not_array_has_any
            - exists
            - not_exists
          description: Comparison or array operator.
          example: gte
        value:
          $ref: '#/components/schemas/QueryValue'
          description: Comparison value. Omit for exists and not_exists operators.
      required:
        - field
        - operator
    QueryValue:
      oneOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          minItems: 1
          items:
            oneOf:
              - type: string
              - type: number
              - type: boolean
      example: 9
  responses:
    BadRequest:
      description: The request parameters are invalid.
      headers:
        X-API-Version:
          description: API contract version used to process the request.
          schema:
            type: string
            example: '2026-08-19'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://docs.zdlake.com/api/errors#bad-request
            title: Bad Request
            status: 400
            detail: Invalid request parameters
            code: VALIDATION_ERROR
            request_id: req_01J7Y8Z9ABCDEF0123456789AB
            errors:
              limit:
                - Number must be less than or equal to 100
    Unauthorized:
      description: The API key is missing, invalid, expired, or revoked.
      headers:
        X-API-Version:
          description: API contract version used to process the request.
          schema:
            type: string
            example: '2026-08-19'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://docs.zdlake.com/api/authentication
            title: Unauthorized
            status: 401
            detail: Invalid or missing API key
            code: UNAUTHORIZED
            request_id: req_01J7Y8Z9ABCDEF0123456789AB
    Forbidden:
      description: The API key lacks permission for this operation.
      headers:
        X-API-Version:
          description: API contract version used to process the request.
          schema:
            type: string
            example: '2026-08-19'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://docs.zdlake.com/api/authentication
            title: Forbidden
            status: 403
            detail: Access denied for this operation
            code: FORBIDDEN
            request_id: req_01J7Y8Z9ABCDEF0123456789AB
    RateLimited:
      description: The API key has exceeded its request quota.
      headers:
        X-API-Version:
          description: API contract version used to process the request.
          schema:
            type: string
            example: '2026-08-19'
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
            example: 30
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://docs.zdlake.com/api/rate-limits
            title: Too Many Requests
            status: 429
            detail: Rate limit exceeded
            code: RATE_LIMITED
            request_id: req_01J7Y8Z9ABCDEF0123456789AB
            errors:
              retry_after: 30
    InternalServerError:
      description: The API could not complete the request.
      headers:
        X-API-Version:
          description: API contract version used to process the request.
          schema:
            type: string
            example: '2026-08-19'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          example:
            type: https://docs.zdlake.com/api/errors#internal-server-error
            title: Internal Server Error
            status: 500
            detail: An internal error occurred
            code: INTERNAL_ERROR
            request_id: req_01J7Y8Z9ABCDEF0123456789AB
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Zero API key
      description: 'Send the API key as Authorization: Bearer <key>.'
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative API-key header for clients without bearer-token support.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.