openapi: 3.2.0
info:
  title: CallidusAI Courts API
  description: Callidus AI backend API
  version: 0.1.0
tags:
- name: courts
paths:
  /courts/find:
    post:
      tags:
      - courts
      summary: Find Court
      description: 'Fetch court information by court_id, including current judges.

        Caches results in the courtscache table.'
      operationId: find_court_courts_find_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CourtRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                additionalProperties: true
                type: object
                title: Response Find Court Courts Find Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /courts/{court_id}/info:
    get:
      tags:
      - courts
      summary: Get Court Info
      description: 'Retrieve court information from the CourtListener database.


        Args:

        court_id: The court ID to fetch information for


        Returns:

        Dictionary containing all court information from search_court table


        Raises:

        HTTPException: If the database engine is unavailable, court not found, or query fails'
      operationId: get_court_info_courts__court_id__info_get
      parameters:
      - name: court_id
        in: path
        required: true
        schema:
          type: string
          title: Court Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Court Info Courts  Court Id  Info Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /courts/{court_id}/judges:
    get:
      tags:
      - courts
      summary: Get Active Judges
      description: 'Retrieve active judges for a court from the CourtListener database.


        Args:

        court_id: The court ID to fetch judges for


        Returns:

        Dictionary containing court_id and list of active judges with essential information


        Raises:

        HTTPException: If the database engine is unavailable or query fails'
      operationId: get_active_judges_courts__court_id__judges_get
      parameters:
      - name: court_id
        in: path
        required: true
        schema:
          type: string
          title: Court Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Active Judges Courts  Court Id  Judges Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /courts/{court_id}/relevant-cases:
    get:
      tags:
      - courts
      summary: Get Relevant Cases
      description: 'Retrieve relevant cases for a given court from the db_caselaw database.


        Args:

        court_id: The court ID to fetch cases for

        limit: Maximum number of cases to return (default: 3, range: 1-100)

        type: Type of cases to return - ''latest'' for most recent, ''landmark'' for most cited


        Returns:

        Dictionary containing court_id, type, limit, and list of relevant cases


        Raises:

        HTTPException: If the database engine is unavailable, invalid type parameter,

        no cases found, or query fails'
      operationId: get_relevant_cases_courts__court_id__relevant_cases_get
      parameters:
      - name: court_id
        in: path
        required: true
        schema:
          type: string
          title: Court Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Maximum number of cases to return
          default: 3
          title: Limit
        description: Maximum number of cases to return
      - name: type
        in: query
        required: false
        schema:
          type: string
          description: 'Type of cases to return: ''latest'' or ''landmark'''
          default: latest
          title: Type
        description: 'Type of cases to return: ''latest'' or ''landmark'''
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Relevant Cases Courts  Court Id  Relevant Cases Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    CourtRequest:
      properties:
        court_id:
          type: string
          title: Court Id
      type: object
      required:
      - court_id
      title: CourtRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError