{
  "openapi": "3.1.0",
  "info": {
    "title": "Zicron public agent API",
    "version": "1.0.0",
    "summary": "Offer, quote, sample and request-a-chronology endpoints for AI assistants and agents.",
    "description": "Public, unauthenticated, rate-limited endpoints for Zicron AI's done-for-you medical chronology service (and SSDI pilot info). The same capabilities are available as MCP tools at https://claims.zicron.ai/mcp (Streamable HTTP). Do not send medical records, patient names, dates of birth or other health information through this API, MCP server, web form or email. After a request, a person at Zicron replies within one business day with a secure upload link to a private, encrypted workspace; records go only through that link. A Business Associate Agreement is signed first if the client needs one.",
    "contact": {
      "name": "Zicron AI",
      "email": "shain.codes@gmail.com",
      "url": "https://claims.zicron.ai"
    }
  },
  "servers": [
    {
      "url": "https://claims.zicron.ai"
    }
  ],
  "externalDocs": {
    "description": "llms.txt",
    "url": "https://claims.zicron.ai/llms.txt"
  },
  "paths": {
    "/api/public/v1/offer": {
      "get": {
        "operationId": "getOffer",
        "summary": "Get Zicron's medical chronology offer",
        "description": "Returns Zicron's done-for-you medical chronology service: what is delivered (case summary plus an all-provider timeline with a page citation on every entry), who it is for (plaintiff PI, med-mal and nursing-home firms, and legal nurse consultants), the published price per case and per page, first-case discount, 48-hour turnaround, scope limits (medical facts only; no standard-of-care, causation or damages opinions), security practices and how to start. Use this when a user asks what Zicron does, what a chronology from Zicron includes, or whether it fits their case. Read-only; no side effects.",
        "x-mcp-tool": "get_offer",
        "x-capability-version": "1",
        "x-side-effects": "none",
        "x-blast-radius": "low",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The body says what to fix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/quote": {
      "get": {
        "operationId": "quoteChronology",
        "summary": "Quote a medical chronology by page count",
        "description": "Computes the price of a Zicron medical chronology from the approximate page count of the record set, using the published list price, and returns the breakdown (base price, pages over the included amount, first-case discount, total) and the turnaround. Deterministic; read-only; no side effects and nothing is ordered. Use this when a user asks what a chronology for N pages would cost. The result is an estimate: Zicron confirms the page count and price in writing before any work starts.",
        "x-mcp-tool": "quote_chronology",
        "x-capability-version": "1",
        "x-side-effects": "none",
        "x-blast-radius": "low",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The body says what to fix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "pages",
            "in": "query",
            "required": true,
            "description": "Approximate total number of pages in the medical record set.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000
            }
          },
          {
            "name": "first_case",
            "in": "query",
            "required": false,
            "description": "True if this would be the requester's first case with Zicron (first case is half price).",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ]
      }
    },
    "/api/public/v1/chronology-requests": {
      "post": {
        "operationId": "requestChronology",
        "summary": "Request a medical chronology (contact request, no records)",
        "description": "Sends Zicron a request to prepare a medical chronology for a case, on behalf of the attorney, legal nurse consultant or paralegal you are helping. It creates a contact request only: nothing is ordered or charged, and a person at Zicron replies by email within one business day with a firm quote and a secure upload link for the records. NEVER include medical records, patient names, dates of birth, record numbers, diagnoses or any other patient information; describe the case only by type, rough page count and deadline. Requests that look like they contain patient information are rejected. Only call this after the user has asked for it and agreed that Zicron may email them, then set confirmed_by_user=true. Use dry_run=true to validate the fields and see the quote without sending anything. Retrying with the same details (or the same idempotency_key) returns the original request instead of creating a duplicate.",
        "x-mcp-tool": "request_chronology",
        "x-capability-version": "1",
        "x-side-effects": "creates_lead",
        "x-blast-radius": "medium",
        "responses": {
          "200": {
            "description": "Duplicate of an earlier request (same details or idempotency_key), or a dry run. Nothing new was created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "201": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The body says what to fix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "422": {
            "description": "Rejected because the text looks like it contains patient information or record content, or an idempotency_key was reused with different details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requester_name": {
                    "type": "string",
                    "maxLength": 120,
                    "description": "Name of the attorney, LNC or staff member Zicron should reply to. Not the patient."
                  },
                  "requester_email": {
                    "type": "string",
                    "format": "email",
                    "maxLength": 254,
                    "description": "Email address Zicron should reply to with the quote and secure upload link."
                  },
                  "requester_role": {
                    "type": "string",
                    "enum": [
                      "legal_nurse_consultant",
                      "lnc_firm",
                      "pi_attorney",
                      "medmal_attorney",
                      "nursing_home_attorney",
                      "paralegal",
                      "other"
                    ],
                    "description": "The requester's role."
                  },
                  "firm_name": {
                    "type": "string",
                    "maxLength": 160,
                    "description": "Law firm or LNC business name (optional)."
                  },
                  "phone": {
                    "type": "string",
                    "maxLength": 40,
                    "description": "Requester's phone number (optional)."
                  },
                  "case_type": {
                    "type": "string",
                    "enum": [
                      "personal_injury",
                      "medical_malpractice",
                      "nursing_home",
                      "workers_comp",
                      "other"
                    ],
                    "description": "Type of case the chronology is for."
                  },
                  "estimated_pages": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100000,
                    "description": "Approximate total page count of the records (optional; used for the estimate)."
                  },
                  "deadline": {
                    "type": "string",
                    "format": "date",
                    "description": "When the chronology is needed back, YYYY-MM-DD (optional)."
                  },
                  "is_first_case": {
                    "type": "boolean",
                    "default": true,
                    "description": "Whether this is the requester's first case with Zicron (half price). Defaults to true."
                  },
                  "notes": {
                    "type": "string",
                    "maxLength": 500,
                    "description": "Optional short note about the case in general terms (e.g. \"two hospitals and a rehab facility, need it before a mediation\"). Max 500 characters. No patient names, dates of birth, diagnoses or record content."
                  },
                  "agent_name": {
                    "type": "string",
                    "maxLength": 80,
                    "description": "Name of the AI assistant or agent making this request (e.g. \"Claude\", \"ChatGPT\"). Optional."
                  },
                  "confirmed_by_user": {
                    "type": "boolean",
                    "description": "Must be true: set only after the person you act for has asked for this and agreed Zicron may email them. Not required when dry_run is true."
                  },
                  "dry_run": {
                    "type": "boolean",
                    "default": false,
                    "description": "If true, validate and return the estimate without sending the request."
                  },
                  "idempotency_key": {
                    "type": "string",
                    "maxLength": 100,
                    "description": "Optional key; repeating a call with the same key and details returns the original request."
                  }
                },
                "required": [
                  "requester_name",
                  "requester_email",
                  "requester_role",
                  "case_type",
                  "confirmed_by_user"
                ],
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/public/v1/sample": {
      "get": {
        "operationId": "getSampleChronology",
        "summary": "Get a sample Zicron medical chronology",
        "description": "Returns links to a sample Zicron medical chronology built from a fictional case (no real patient data): a page for humans and a direct PDF link, plus the sections it contains. Use this when a user wants to see what the deliverable looks like before sending a case. Read-only; no side effects.",
        "x-mcp-tool": "get_sample_chronology",
        "x-capability-version": "1",
        "x-side-effects": "none",
        "x-blast-radius": "low",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The body says what to fix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/ssdi-pilot": {
      "get": {
        "operationId": "getSsdiPilotInfo",
        "summary": "Get Zicron's SSDI intake-scoring pilot for firms",
        "description": "Returns Zicron's 30-day SSDI intake-scoring pilot for SSDI representation and intake firms: what it does (rule-based scoring of leads against SSA's five-step evaluation with page-cited findings), price, what is included, limits, and how to request it. Use this only for law firms or intake operations handling SSDI claims. It is not for individual claimants seeking help with their own claim; Zicron does not represent claimants. Read-only; no side effects.",
        "x-mcp-tool": "get_ssdi_pilot_info",
        "x-capability-version": "1",
        "x-side-effects": "none",
        "x-blast-radius": "low",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "400": {
            "description": "Invalid input. The body says what to fix.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Denial"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Denial": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "outcome": {
                "type": "string",
                "enum": [
                  "denied",
                  "failed"
                ]
              },
              "reason": {
                "type": "string",
                "enum": [
                  "input_invalid",
                  "phi_rejected",
                  "rate_limited",
                  "idempotency_key_reused",
                  "unavailable"
                ]
              },
              "why": {
                "type": "string"
              },
              "whatToDo": {
                "type": "string"
              },
              "useInstead": {
                "type": "string"
              },
              "errors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "reason": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "required": [
              "outcome",
              "reason",
              "why",
              "whatToDo"
            ]
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}