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

# Create a lawsuit find

> Creates a real find request, debits credits and enqueues async processing. Returns request_id, status pending and cost.



## OpenAPI

````yaml openapi/miner.yaml POST /requests/create
openapi: 3.0.3
info:
  title: Judit Miner API — Requests, responses & tribunals
  description: >
    OpenAPI description for miner API routes that manage lawsuit search
    **requests**

    (count, create, status), paginated **responses** (lawsuit results), and the

    **tribunals** reference list (ids used in request filters).


    - `company_id` and `user_id` are **not** sent by the client on `POST
    /requests/create`;
      the server fills them from the authenticated session.
    - On `POST /requests/count`, the server merges `company_id` and `user_id`
    from context
      first; clients should send only filter fields (see request body schema).
    - Request and response bodies use **JSON**. Date-time fields are ISO 8601
    strings.

    - Count/create bodies are validated with a **strict** object (unknown keys
    are rejected).


    Authentication and `miner_enabled` behavior are enforced by
    `@judit-io/server`

    (e.g. JWT / gateway); this spec requires an API key provided in the
    `api-key` header.
  version: 1.0.0
servers:
  - url: https://miner.production.judit.io
    description: Production server
security:
  - ApiKeyAuth: []
tags:
  - name: Requests
    description: Create and inspect lawsuit search requests
  - name: Responses
    description: Paginated lawsuit results for a completed find request
  - name: Tribunals
    description: Reference data for tribunal identifiers used in filters
paths:
  /requests/create:
    post:
      tags:
        - Requests
      summary: Create a find request and enqueue processing
      description: >
        Validates billing (credits vs. priced tiers), creates a **find**-type
        request

        in **pending** status, persists filters, publishes chunk events for
        async work,

        and returns `request_id`, `status`, and computed **`cost`** (credits
        charged).


        Returns **201 Created** on success. May return **403** if credits or
        plan

        configuration are missing or insufficient.
      operationId: postRequestsCreate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RequestLawsuitsFiltersBody'
            examples:
              withLimit:
                summary: Find with responses cap
                value:
                  kind: sentence-execution
                  tribunals:
                    - 1
                  tags:
                    - possible_precatory
                  responses_limit: 500
      responses:
        '201':
          description: Request accepted; async processing started.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRequestSuccess'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: |
            Billing or plan guard. Non-exhaustive machine codes used by the API:
            `MISSING_CREDITS`, `MISSING_CONFIGURATIONS`, `INSUFFICIENT_CREDITS`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorPayload'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    RequestLawsuitsFiltersBody:
      type: object
      additionalProperties: false
      required:
        - kind
      properties:
        kind:
          $ref: '#/components/schemas/LawsuitKind'
        amount_min:
          type: number
          description: >-
            Minimum lawsuit amount filter (cannot be combined with
            `amount_tier`)
        amount_max:
          type: number
          description: >-
            Maximum lawsuit amount filter (cannot be combined with
            `amount_tier`)
        amount_tier:
          $ref: '#/components/schemas/AmountTier'
        tribunals:
          type: array
          items:
            type: integer
        budget_years:
          type: array
          items:
            type: integer
          description: Only when `kind` is `judgement-bond`
        natures:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitNature'
          description: Only when `kind` is `judgement-bond`
        tags:
          type: array
          items:
            $ref: '#/components/schemas/LawsuitTag'
          description: Only when `kind` is `sentence-execution`
        responses_limit:
          type: integer
          minimum: 1
          description: >
            Caps how many lawsuits are included in a **find** request
            (`/requests/create` only).
      description: >
        Mirrors `requestLawsuitsInputSchema` in `@judit-io/miner-shared` (strict
        object).


        Cross-field rules (enforced server-side):

        - If both `amount_min` and `amount_max` are set, `amount_min` ≤
        `amount_max`.

        - For `sentence-execution`: `budget_years` and `natures` must be absent.

        - For `judgement-bond`: `tags` must be absent.

        - `amount_tier` cannot be used together with `amount_min` or
        `amount_max`.
    CreateRequestSuccess:
      type: object
      required:
        - request_id
        - status
        - cost
      properties:
        request_id:
          type: integer
          format: int64
        status:
          $ref: '#/components/schemas/RequestStatus'
        cost:
          type: number
          description: Total credits charged for this request (sum of tier prices × counts)
    ErrorPayload:
      type: object
      description: >
        Shape depends on `@judit-io/server` error serialization; typically
        includes

        machine-readable codes or message lists. Treat as opaque unless you
        confirm

        against your gateway.
      additionalProperties: true
      properties:
        errors:
          type: array
          items:
            type: string
    LawsuitKind:
      type: string
      enum:
        - judgement-bond
        - sentence-execution
    AmountTier:
      type: string
      enum:
        - 0-100k
        - 100k-250k
        - 250k-500k
        - 500k-750k
        - 750k-1.5M
        - 1.5M+
    LawsuitNature:
      type: string
      enum:
        - alimentary
        - common
    LawsuitTag:
      type: string
      enum:
        - precatory_dispatched
        - possible_precatory
        - possible_approved_calculation
    RequestStatus:
      type: string
      enum:
        - pending
        - completed
        - failed
  responses:
    BadRequest:
      description: Validation failed (Zod); `errors` is a list of human-readable messages.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
    InternalServerError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorPayload'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Replace with the actual API key requirement for your Miner API
        deployment.

````