openapi: 3.1.0
info:
  title: Mandate Law counsel API
  version: 0.1.0
  description: >
    REST mirror of the MCP tools at /mcp. Free endpoints give legal information only.
    No attorney-client relationship exists until a human principal signs the engagement letter.
    See /llms.txt for the rules agents must follow.
servers:
  - url: https://mandatelaw.ai/api
paths:
  /services.json:
    get: {summary: Service catalog, responses: {"200": {description: OK}}}
  /counsel-triggers.json:
    get: {summary: Changes that need legal review before shipping, responses: {"200": {description: OK}}}
  /scope:
    post:
      summary: Check whether a request is in scope, and get the fixed fee for the services that fit (free)
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [request], properties: {request: {type: string, maxLength: 1000}, service_id: {enum: [launch-review, ai-feature-review, agent-product-review, feature-check, counsel-on-commit], description: "Optional: also quote this service's fee."}}}}}}
      responses: {"201": {description: "Scope result, with suggested_services and a fees array (fixed fee and payment terms for each)."}}
  /conflict-checks:
    post:
      summary: Start a conflict check (names only, free)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client_name, contact_name]
              properties:
                client_name: {type: string}
                contact_name: {type: string}
                other_people: {type: array, items: {type: string}}
                adverse_or_related_parties: {type: array, items: {type: string}}
      responses: {"201": {description: Pending attorney review}}
  /engagements:
    post:
      summary: Ask the firm to take a matter
      description: >-
        Send a short, public-level matter summary. The attorney uses it only to decide whether the firm can and will
        take the matter, and keeps it confidential. No code, secrets, user data, or confidential business plans. The
        attorney may ask scoping questions (see GET /matters/{matter_id}), then accepts (possibly under a different
        service) or declines. If accepted, the engagement letter goes to principal_email.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [conflict_check_id, service_id, principal_email, matter_summary]
              properties:
                conflict_check_id: {type: string}
                service_id: {enum: [launch-review, ai-feature-review, agent-product-review, feature-check, counsel-on-commit], description: Your best guess; the attorney may change it.}
                principal_email: {type: string, format: email}
                matter_summary:
                  type: object
                  required: [what_it_does, stage, users, features_in_play, questions_for_counsel, active_dispute_or_regulator_contact]
                  properties:
                    product_name: {type: string, maxLength: 120}
                    what_it_does: {type: string, maxLength: 600, description: One to three sentences, as you would describe it publicly.}
                    stage: {enum: [idea, building, beta, live]}
                    target_launch_date: {type: string}
                    users: {enum: [consumers, businesses, both]}
                    user_scale: {enum: [pre_launch, under_10k, 10k_to_1m, over_1m]}
                    where_users_are: {type: array, items: {type: string}, description: "Countries or US states, e.g. US, CA, WA, EU, UK."}
                    features_in_play:
                      type: array
                      minItems: 1
                      items: {enum: [ai_generated_output, sends_user_data_to_llm, trains_on_user_data, agent_takes_actions, agent_payments, agent_uses_third_party_sites, agent_holds_user_credentials, health_data, financial_data, children_or_teens, precise_location, biometrics, session_replay_or_ad_tracking, regulated_advice, none_of_these]}
                    questions_for_counsel: {type: string, maxLength: 1000, description: What you want answered, in general terms.}
                    deadline: {type: string, maxLength: 200}
                    active_dispute_or_regulator_contact: {type: boolean, description: "True if there is a complaint, demand letter, lawsuit, or regulator inquiry. Do not describe it here."}
      responses: {"201": {description: "Matter created with status awaiting_attorney_review. Returns matter_id and a secret matter_token (shown once) to use as the Bearer token on matter endpoints."}}
  /matters/{matter_id}:
    get:
      summary: Matter status, open questions, deliverables
      security: [{matterToken: []}]
      parameters: [{name: matter_id, in: path, required: true, schema: {type: string}}]
      responses: {"200": {description: OK}}
  /matters/{matter_id}/intake:
    post:
      summary: Submit product facts (after signature)
      security: [{matterToken: []}]
      parameters: [{name: matter_id, in: path, required: true, schema: {type: string}}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: "https://mandatelaw.ai/api/intake-schema.json"}}}}
      responses: {"202": {description: In review}, "409": {description: Engagement not signed}}
  /matters/{matter_id}/questions/{question_id}/answer:
    post:
      summary: Answer one of counsel's open questions with an evidence-backed fact (scoping questions can be answered before signature; keep those general)
      security: [{matterToken: []}]
      parameters:
        - {name: matter_id, in: path, required: true, schema: {type: string}}
        - {name: question_id, in: path, required: true, schema: {type: string}}
      requestBody: {required: true, content: {application/json: {schema: {$ref: "https://mandatelaw.ai/api/intake-schema.json#/$defs/fact"}}}}
      responses: {"200": {description: Answer recorded}, "422": {description: Verified answer without evidence}}
  /matters/{matter_id}/feature-checks:
    post:
      summary: Ask for review of a planned change that matches a counsel trigger
      security: [{matterToken: []}]
      parameters: [{name: matter_id, in: path, required: true, schema: {type: string}}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: "https://mandatelaw.ai/api/intake-schema.json#/$defs/feature_change"}}}}
      responses: {"202": {description: In review; do not ship until counsel responds}}
components:
  securitySchemes:
    matterToken: {type: http, scheme: bearer, description: Issued to the client after the engagement letter is signed.}