CaseMagic Cases API

openapi: 3.2.0
info:
  title: CaseMagic Cases API
  description: 'CaseMagic watches United States federal court cases for new filings and keeps a persistent Case Passport of each one. This API is the free part: look up a case in a federal district court and read what has been filed in it, with no account. Watching a case, the Case Passport and CaseMail are on the MCP server at https://casemagic.ai/mcp, described at https://casemagic.ai/llms.txt. Data comes from the public court record.'
  version: 1.0.0
  contact:
    name: CaseMagic support
    email: support@casemagic.ai
    url: https://casemagic.ai/support
servers:
- url: https://casemagic.ai
tags:
- name: Cases
paths:
  /api/v1/cases/check:
    post:
      operationId: checkCase
      summary: Find a federal case and read its latest filings
      description: 'Returns the caption, judge, cause of action, filing date and the most recent docket entries for a case in a U.S. federal district court. Give a case number with its court for the fastest answer; a case name also works when the court is named. Always show the user the case page link that comes back, so they can watch the case for new filings. Two fields on the answer matter for how you phrase it. "freshness" says whether the docket was read just now, minutes ago, or read earlier and confirmed unchanged by the court’s own filing feed — cite it rather than implying the reading is live. And "queued" is a normal status, not a failure: the public court record limits how many cases can be read in a day, and a queued answer means the case is being loaded and the result will follow.'
      x-openai-isConsequential: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                case_number:
                  type: string
                  description: The docket number as the court writes it, for example '1:23-cv-11195'.
                court:
                  type: string
                  description: 'The court''s short code, for example ''nysd'' for the Southern District of New York or ''cand'' for the Northern District of California. Strongly recommended: without it the same number can match several courts.'
                case_name:
                  type: string
                  description: The caption, for example 'New York Times v. Microsoft'. Requires court to be set as well.
                notify_email:
                  type: string
                  description: 'An email address to send the result to if this lookup has to be queued. Do not ask for one up front: send it only after a call comes back with status ''queued'' and the user has offered an address.'
      responses:
        '200':
          description: 'A result. Check the status field: found, not_found, multiple_matches or queued. All four are normal answers.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - found
                    - not_found
                    - multiple_matches
                    - queued
                  case:
                    type: object
                    description: 'Present when status is found: caption, court, judge, cause, nature of suit, filing date and entry count.'
                  latest_events:
                    type: array
                    description: The most recent docket entries, newest first.
                    items:
                      type: object
                  source:
                    type: object
                    description: Which court source answered and when it was read. Cite this rather than presenting the data as your own.
                  data_freshness:
                    type: string
                    description: When this record was last read from the court source.
                  freshness:
                    type: object
                    description: Why the answer is as current as it claims.
                    properties:
                      basis:
                        type: string
                        enum:
                        - source
                        - cache
                        - court_feed
                        - stale
                        - court_feed_only
                      read_at:
                        type: string
                      confirmed_at:
                        type: string
                      note:
                        type: string
                  queue_id:
                    type: string
                    description: 'Present when status is queued: the ticket for this deferred read.'
                  retry_after_seconds:
                    type: integer
                    description: 'Present when status is queued: how long until the request allowance frees up.'
                  message:
                    type: string
                    description: 'Present when status is queued: one sentence to relay to the user verbatim.'
                  candidates:
                    type: array
                    description: 'Present when status is multiple_matches: the cases the number could refer to.'
                    items:
                      type: object
        '429':
          description: Too many lookups.
        '503':
          description: Source not responding.
        '404':
          description: No such ticket.
      tags:
      - Cases