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

# Search Cases

> Boolean / phrase / fuzzy search across the Hong Kong case-law corpus. The `q` parameter accepts plain words, exact phrases (wrap in `"..."`), or boolean queries (use `AND` / `OR` / `NOT`). See the [search syntax guide](https://docs.casebyte.ai/guides/search-syntax) for details.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/cases/search
openapi: 3.1.0
info:
  title: Casebyte API
  description: >-
    REST API for searching and retrieving Hong Kong case law. See the guides at
    https://docs.casebyte.ai for tutorials and conceptual overviews.
  version: 1.1.0
  contact:
    name: Casebyte support
    email: support@casebyte.ai
    url: https://casebyte.ai
  license:
    name: Proprietary
servers:
  - url: https://api.casebyte.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Cases
    description: Search and retrieve Hong Kong case law.
  - name: Health
    description: Service health checks.
  - name: Daily
    description: Completed case summaries within the active seven Hong Kong calendar days.
paths:
  /v1/cases/search:
    get:
      tags:
        - Cases
      summary: Search Cases
      description: >-
        Boolean / phrase / fuzzy search across the Hong Kong case-law corpus.
        The `q` parameter accepts plain words, exact phrases (wrap in `"..."`),
        or boolean queries (use `AND` / `OR` / `NOT`). See the [search syntax
        guide](https://docs.casebyte.ai/guides/search-syntax) for details.
      parameters:
        - name: q
          in: query
          required: true
          description: >-
            Search query. Supports plain words, `"phrases"`, and
            `AND`/`OR`/`NOT` booleans.
          schema:
            type: string
            minLength: 1
          examples:
            plain:
              value: negligence
              summary: Plain word match
            phrase:
              value: '"strict liability"'
              summary: Exact phrase
            boolean:
              value: wednesbury AND ("judicial review" OR "public law") NOT tax
              summary: Boolean query
        - name: scope
          in: query
          description: Which fields to search.
          schema:
            type: string
            enum:
              - all
              - case_name
              - judgment
            default: all
        - name: court
          in: query
          description: >-
            Comma-separated list of HK court codes to filter by (e.g.
            `HKCFA,HKCA`). Case-insensitive on input. Unknown codes return `400
            invalid_court`.
          schema:
            type: string
            pattern: >-
              ^(HKCFA|HKCA|HKCFI|HKDC|HKMAGC|HKFC|HKLDT|HKLAT|HKSCT|HKOAT|HKCT|HKCRC)(,(HKCFA|HKCA|HKCFI|HKDC|HKMAGC|HKFC|HKLDT|HKLAT|HKSCT|HKOAT|HKCT|HKCRC))*$
          example: HKCFA,HKCA
        - name: start
          in: query
          description: Inclusive lower bound for `publish_date`. Must be `YYYY-MM-DD`.
          schema:
            type: string
            format: date
          example: '2020-01-01'
        - name: end
          in: query
          description: >-
            Inclusive upper bound for `publish_date`. Must be `YYYY-MM-DD`. Must
            be on or after `start`.
          schema:
            type: string
            format: date
          example: '2023-12-31'
        - name: order
          in: query
          description: Sort order for `publish_date`.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - name: limit
          in: query
          description: Page size.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          description: Number of results to skip. `offset + limit` must be ≤ 10,000.
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
      responses:
        '200':
          description: Search results.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              example:
                total: 47
                limit: 5
                offset: 0
                results:
                  - case_id: HKCFA_2021_12
                    case_name: Kwok Cheuk Kin v Director of Lands
                    court: HKCFA
                    neutral_citation: '[2021] HKCFA 12'
                    action_number:
                      - FACV 4/2020
                    publish_date: '2021-04-21'
                    score: 14.82
                    highlights:
                      doc_text:
                        - >-
                          ...the test of <em>Wednesbury</em>
                          <em>unreasonable</em>ness applied...
                      case_name: []
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RateLimitLimit:
      description: Per-window quota for this API key.
      schema:
        type: integer
      example: 10
    RateLimitRemaining:
      description: Requests remaining in the current window.
      schema:
        type: integer
      example: 9
  schemas:
    SearchResponse:
      type: object
      required:
        - total
        - limit
        - offset
        - results
      properties:
        total:
          type: integer
          description: >-
            Total number of cases matching the query (the corpus-wide count, not
            the page size).
        limit:
          type: integer
          description: Echo of the `limit` parameter actually applied.
        offset:
          type: integer
          description: Echo of the `offset` parameter actually applied.
        results:
          type: array
          items:
            $ref: '#/components/schemas/SearchHit'
    SearchHit:
      type: object
      required:
        - case_id
        - highlights
      properties:
        case_id:
          type: string
          description: >-
            Canonical case ID (e.g. `HKCFA_2023_5`). Use this for subsequent
            calls to `/v1/cases/{id}`.
          example: HKCFA_2021_12
        case_name:
          type:
            - string
            - 'null'
          example: Kwok Cheuk Kin v Director of Lands
        court:
          type:
            - string
            - 'null'
          description: Court code, e.g. `HKCFA`, `HKCA`, `HKCFI`.
          example: HKCFA
        neutral_citation:
          type:
            - string
            - 'null'
          example: '[2021] HKCFA 12'
        action_number:
          description: >-
            Court-assigned action number(s). May be a single string or an array
            depending on the underlying record.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
            - type: 'null'
          example:
            - FACV 4/2020
        publish_date:
          type:
            - string
            - 'null'
          format: date
          example: '2021-04-21'
        score:
          type:
            - number
            - 'null'
          description: >-
            Relevance score. Higher is more relevant. Only meaningful when
            comparing hits within a single search response — scores are not
            comparable across requests.
          example: 14.82
        highlights:
          type: object
          description: Matched snippets, with matched terms wrapped in `<em>...</em>`.
          properties:
            doc_text:
              type: array
              items:
                type: string
              description: Up to 3 fragments of ~300 chars each from the judgment body.
            case_name:
              type: array
              items:
                type: string
              description: Up to 1 fragment from the case name.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: >-
                Stable, machine-readable error code. Branch on this in your
                code.
            message:
              type: string
              description: >-
                Human-readable summary. May change between versions; do not
                branch on this.
            details:
              description: Optional, endpoint-specific extra context.
              nullable: true
  responses:
    BadRequest:
      description: >-
        The request was malformed or missing required parameters. The
        `error.code` distinguishes the specific cause; common values include
        `invalid_date`, `missing_query`, `query_too_long`, `invalid_scope`,
        `invalid_order`, `invalid_int`, `invalid_range`, `invalid_court`,
        `invalid_date_range`, `pagination_too_deep`, `missing_identifier`, and
        `invalid_identifier`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingQuery:
              summary: Missing `q` parameter
              value:
                error:
                  code: missing_query
                  message: Query parameter `q` is required.
            invalidScope:
              summary: Invalid `scope` value
              value:
                error:
                  code: invalid_scope
                  message: '`scope` must be one of: all, case_name, judgment.'
                  details:
                    field: scope
                    value: case
                    allowed:
                      - all
                      - case_name
                      - judgment
            invalidCourt:
              summary: Unknown court code
              value:
                error:
                  code: invalid_court
                  message: >-
                    Unknown court code: HKMC. Valid codes: HKCFA, HKCA, HKCFI,
                    HKDC, HKMAGC, HKFC, HKLDT, HKLAT, HKSCT, HKOAT, HKCT, HKCRC.
                  details:
                    invalid:
                      - HKMC
                    valid:
                      - HKCFA
                      - HKCA
                      - HKCFI
                      - HKDC
                      - HKMAGC
                      - HKFC
                      - HKLDT
                      - HKLAT
                      - HKSCT
                      - HKOAT
                      - HKCT
                      - HKCRC
            invalidDate:
              summary: Malformed date
              value:
                error:
                  code: invalid_date
                  message: '`start` must be an ISO date in YYYY-MM-DD format.'
                  details:
                    field: start
                    value: '2023'
            invalidRange:
              summary: Out-of-range integer
              value:
                error:
                  code: invalid_range
                  message: '`limit` must be between 1 and 100.'
                  details:
                    field: limit
                    value: 500
                    min: 1
                    max: 100
            paginationTooDeep:
              summary: '`offset + limit` exceeds the result-window cap'
              value:
                error:
                  code: pagination_too_deep
                  message: >-
                    `offset` + `limit` must be at most 10000. Use court / date
                    filters to narrow the result set instead of paginating
                    deeper.
                  details:
                    offset: 9999
                    limit: 100
                    max: 10000
    Unauthorized:
      description: Missing, malformed, or revoked credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No Authorization header
              value:
                error:
                  code: missing_credentials
                  message: Authorization header with a Bearer token is required.
            invalid:
              summary: Unrecognised key
              value:
                error:
                  code: invalid_credentials
                  message: API key not recognised.
            revoked:
              summary: Revoked key
              value:
                error:
                  code: revoked_credentials
                  message: API key has been revoked.
    RateLimited:
      description: >-
        You exceeded your per-minute quota. Back off with exponential delay and
        jitter — `Retry-After` is intentionally not returned.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded.
    InternalError:
      description: Something went wrong on our side. Retry with exponential backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: Internal server error.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cb_live_*
      description: >-
        Casebyte API key, prefixed with `cb_live_`. Generate one from your
        [casebyte.ai dashboard](https://casebyte.ai/dashboard).

````

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