{
  "openapi": "3.1.0",
  "info": {
    "title": "Penuel Counseling Agent & Developer API",
    "version": "1.0.0",
    "description": "Public machine-readable REST API and tool definitions for Penuel Counseling. Provides real-time information on bilingual (English/Spanish) psychotherapy, EMDR, trauma care, and court-ready immigration psychological evaluations (Asylum, VAWA, U-Visa, Extreme Hardship Waivers) across Florida, Missouri, Kansas, and Virginia.\n\n### API Versioning & Lifecycle Policy\n- **Versioning Strategy**: URI path-based versioning (`/api/v1/...`). Minor backwards-compatible additions do not alter the major version number.\n- **Deprecation Policy**: In accordance with RFC 8594, any deprecated endpoint will signal retirement via the `Deprecation` header and `Sunset` header providing at least 180 days advance notice before decommissioning.\n- **Rate Limiting**: Conforms to IETF RateLimit standards. All endpoints return `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy: 120;w=60`. If throttled, HTTP 429 is returned with `Retry-After: 60`.",
    "contact": {
      "name": "Penuel Counseling Support",
      "url": "https://www.penuelcounseling.com/contact",
      "email": "contact@penuelcounseling.com"
    },
    "license": {
      "name": "CC BY-ND 4.0",
      "url": "https://creativecommons.org/licenses/by-nd/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://www.penuelcounseling.com",
      "description": "Production Server (HTTPS Canonical)"
    }
  ],
  "tags": [
    {
      "name": "Practice",
      "description": "Information regarding the practice, therapist credentials, locations, and direct contact options."
    },
    {
      "name": "Services",
      "description": "Catalog of available psychotherapy and mental health counseling services."
    },
    {
      "name": "Immigration",
      "description": "Psychological evaluations for immigration court proceedings and USCIS petitions."
    },
    {
      "name": "Inquiries",
      "description": "Programmatic submission of patient inquiries and attorney referrals."
    }
  ],
  "paths": {
    "/api/v1/practice": {
      "get": {
        "summary": "Get practice profile and credentials",
        "description": "Retrieves comprehensive information about Penuel Counseling, therapist licensing, authorized telehealth states, language proficiencies, and direct booking links.",
        "operationId": "getPracticeInfo",
        "tags": ["Practice"],
        "responses": {
          "200": {
            "description": "Practice profile successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PracticeInfo"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "405": { "$ref": "#/components/responses/MethodNotAllowedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "default": { "$ref": "#/components/responses/DefaultError" }
        }
      }
    },
    "/api/v1/services": {
      "get": {
        "summary": "List all mental health and evaluation services",
        "description": "Returns the complete catalog of individual therapy, EMDR trauma therapy, couples counseling, play therapy, ESA letters, and immigration evaluations with target concerns and URLs.",
        "operationId": "listServices",
        "tags": ["Services"],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter services by category: 'therapy' or 'immigration_evaluation'.",
            "schema": {
              "type": "string",
              "enum": ["therapy", "immigration_evaluation"]
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": false,
            "description": "Filter services by language support: 'en' or 'es'.",
            "schema": {
              "type": "string",
              "enum": ["en", "es"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Service catalog successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceCatalog"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "405": { "$ref": "#/components/responses/MethodNotAllowedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "default": { "$ref": "#/components/responses/DefaultError" }
        }
      }
    },
    "/api/v1/evaluations": {
      "get": {
        "summary": "Get immigration psychological evaluation details",
        "description": "Retrieves specifications for court-ready and USCIS-admissible psychological evaluations, including turnaround timelines, evaluation types (Asylum, VAWA, U-Visa, Hardship Waivers), and attorney collaboration workflows.",
        "operationId": "getEvaluationDetails",
        "tags": ["Immigration"],
        "responses": {
          "200": {
            "description": "Evaluation details successfully retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EvaluationDetails"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "405": { "$ref": "#/components/responses/MethodNotAllowedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "default": { "$ref": "#/components/responses/DefaultError" }
        }
      }
    },
    "/api/v1/inquiries": {
      "post": {
        "summary": "Submit a client inquiry or attorney referral",
        "description": "Allows AI agents or client systems to submit a patient intake inquiry or attorney referral. Validates submission fields and returns confirmation, next steps, and direct booking links.",
        "operationId": "submitInquiry",
        "tags": ["Inquiries"],
        "requestBody": {
          "required": true,
          "description": "Patient inquiry or case referral data.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InquiryRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Inquiry successfully received and queued.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InquiryResponse"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequestError" },
          "404": { "$ref": "#/components/responses/NotFoundError" },
          "405": { "$ref": "#/components/responses/MethodNotAllowedError" },
          "429": { "$ref": "#/components/responses/RateLimitError" },
          "500": { "$ref": "#/components/responses/InternalError" },
          "default": { "$ref": "#/components/responses/DefaultError" }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "TherapistProfile": {
        "type": "object",
        "required": ["name", "title", "languages"],
        "properties": {
          "name": { "type": "string", "example": "Daylin Rodriguez" },
          "title": { "type": "string", "example": "Licensed Psychotherapist" },
          "languages": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["English", "Spanish"]
          },
          "profiles": {
            "type": "array",
            "items": { "type": "string", "format": "uri" },
            "example": [
              "https://www.psychologytoday.com/us/therapists/daylin-rodriguez-cesar-kansas-city-ks/209637"
            ]
          }
        }
      },
      "LocationInfo": {
        "type": "object",
        "required": ["city", "state", "country"],
        "properties": {
          "city": { "type": "string", "example": "Miami" },
          "state": { "type": "string", "example": "FL" },
          "country": { "type": "string", "example": "US" }
        }
      },
      "ContactChannels": {
        "type": "object",
        "required": ["whatsapp", "phone", "schedule_online"],
        "properties": {
          "whatsapp": { "type": "string", "example": "+19138903876" },
          "phone": { "type": "string", "example": "+19138903876" },
          "schedule_online": { "type": "string", "format": "uri", "example": "https://penuelbilingualcounseling.clientsecure.me/" }
        }
      },
      "ReviewSummary": {
        "type": "object",
        "required": ["rating", "count"],
        "properties": {
          "rating": { "type": "number", "example": 5.0 },
          "count": { "type": "integer", "example": 27 },
          "profile_url": { "type": "string", "format": "uri", "example": "https://maps.app.goo.gl/qzmWV5xVokcWC8GJ7" }
        }
      },
      "PracticeInfo": {
        "type": "object",
        "required": [
          "name",
          "legal_name",
          "description",
          "therapist",
          "location",
          "service_delivery",
          "licensed_telehealth_states",
          "booking_url",
          "contact",
          "reviews"
        ],
        "properties": {
          "name": { "type": "string", "example": "Penuel Counseling" },
          "legal_name": { "type": "string", "example": "Penuel Counseling LLC" },
          "description": { "type": "string", "example": "Bilingual (English & Spanish) telehealth psychotherapy and court-ready immigration evaluations." },
          "therapist": { "$ref": "#/components/schemas/TherapistProfile" },
          "location": { "$ref": "#/components/schemas/LocationInfo" },
          "service_delivery": { "type": "string", "example": "Telehealth (100% online video sessions)" },
          "licensed_telehealth_states": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Florida", "Missouri", "Kansas", "Virginia"]
          },
          "booking_url": { "type": "string", "format": "uri", "example": "https://penuelbilingualcounseling.clientsecure.me/" },
          "contact": { "$ref": "#/components/schemas/ContactChannels" },
          "reviews": { "$ref": "#/components/schemas/ReviewSummary" },
          "links": {
            "type": "object",
            "required": ["website", "documentation", "openapi", "llms_txt"],
            "properties": {
              "website": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com" },
              "documentation": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/docs" },
              "openapi": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/openapi.json" },
              "llms_txt": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/llms.txt" }
            }
          }
        }
      },
      "ServiceItem": {
        "type": "object",
        "required": ["id", "category", "name", "description", "languages", "url"],
        "properties": {
          "id": { "type": "string", "example": "emdr-therapy" },
          "category": { "type": "string", "enum": ["therapy", "immigration_evaluation"] },
          "name": { "type": "string", "example": "EMDR Therapy" },
          "description": { "type": "string", "example": "Evidence-based therapy for trauma and PTSD." },
          "languages": { "type": "array", "items": { "type": "string" }, "example": ["English", "Spanish"] },
          "url": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/emdr-therapy" },
          "url_es": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/es/terapia-emdr" },
          "target_concerns": { "type": "array", "items": { "type": "string" }, "example": ["PTSD", "Trauma", "Anxiety"] },
          "form_type": { "type": "string", "example": "I-589" }
        }
      },
      "ServiceCatalog": {
        "type": "object",
        "required": ["provider", "modality", "languages_supported", "service_states", "services"],
        "properties": {
          "provider": { "type": "string", "example": "Penuel Counseling" },
          "modality": { "type": "string", "example": "Telehealth / Online Video Sessions" },
          "languages_supported": { "type": "array", "items": { "type": "string" }, "example": ["English", "Spanish"] },
          "service_states": { "type": "array", "items": { "type": "string" }, "example": ["Florida", "Missouri", "Kansas", "Virginia"] },
          "services": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ServiceItem" }
          }
        }
      },
      "TurnaroundOption": {
        "type": "object",
        "required": ["business_days", "description"],
        "properties": {
          "business_days": { "type": "integer", "example": 15 },
          "description": { "type": "string", "example": "Includes initial clinical intake, diagnostic testing, and USCIS-ready report." }
        }
      },
      "TurnaroundTimes": {
        "type": "object",
        "required": ["standard_service", "express_expedited"],
        "properties": {
          "standard_service": { "$ref": "#/components/schemas/TurnaroundOption" },
          "express_expedited": { "$ref": "#/components/schemas/TurnaroundOption" }
        }
      },
      "EvaluationTypeItem": {
        "type": "object",
        "required": ["type", "key_components"],
        "properties": {
          "type": { "type": "string", "example": "Asylum (Form I-589)" },
          "form_number": { "type": "string", "example": "I-589" },
          "key_components": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Trauma history", "PTSD assessment", "Fear of return"]
          }
        }
      },
      "AttorneyCollaboration": {
        "type": "object",
        "required": ["records_review", "attorney_consultation"],
        "properties": {
          "records_review": { "type": "string", "example": "Accepts medical records, police reports, and affidavits." },
          "attorney_consultation": { "type": "string", "example": "Direct coordination with legal counsel on court deadlines." }
        }
      },
      "EvaluationBooking": {
        "type": "object",
        "required": ["url", "whatsapp"],
        "properties": {
          "url": { "type": "string", "format": "uri", "example": "https://penuelbilingualcounseling.clientsecure.me/" },
          "whatsapp": { "type": "string", "example": "+19138903876" },
          "consultation": { "type": "string", "example": "Free initial consultation to confirm case suitability." }
        }
      },
      "EvaluationDetails": {
        "type": "object",
        "required": [
          "provider",
          "evaluator",
          "purpose",
          "admissibility",
          "telehealth_jurisdiction",
          "turnaround_times",
          "evaluation_types",
          "attorney_collaboration",
          "booking"
        ],
        "properties": {
          "provider": { "type": "string", "example": "Penuel Counseling" },
          "evaluator": { "$ref": "#/components/schemas/TherapistProfile" },
          "purpose": { "type": "string", "example": "Independent clinical evaluations for immigration proceedings." },
          "admissibility": { "type": "string", "example": "Evaluations follow DSM-5-TR diagnostic criteria for USCIS and immigration courts." },
          "telehealth_jurisdiction": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Florida", "Missouri", "Kansas", "Virginia"]
          },
          "turnaround_times": { "$ref": "#/components/schemas/TurnaroundTimes" },
          "evaluation_types": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/EvaluationTypeItem" }
          },
          "attorney_collaboration": { "$ref": "#/components/schemas/AttorneyCollaboration" },
          "booking": { "$ref": "#/components/schemas/EvaluationBooking" }
        }
      },
      "InquiryRequest": {
        "type": "object",
        "required": ["name", "contact", "service_type", "state"],
        "properties": {
          "name": { "type": "string", "description": "Full name of patient or referral contact.", "example": "Maria Gomez" },
          "contact": { "type": "string", "description": "Phone number or email address.", "example": "maria@example.com" },
          "preferred_language": { "type": "string", "enum": ["en", "es"], "default": "en", "example": "es" },
          "service_type": {
            "type": "string",
            "enum": [
              "emdr-therapy",
              "trauma-therapy",
              "individual-therapy",
              "couples-counseling",
              "play-therapy",
              "esa-letter",
              "asylum-evaluation",
              "vawa-evaluation",
              "u-visa-evaluation",
              "hardship-waiver-evaluation",
              "general-inquiry"
            ],
            "example": "emdr-therapy"
          },
          "state": {
            "type": "string",
            "description": "US state where client resides.",
            "example": "FL"
          },
          "notes": {
            "type": "string",
            "description": "Optional background notes or attorney court deadlines.",
            "example": "Interested in virtual EMDR for past trauma."
          }
        }
      },
      "InquiryResponse": {
        "type": "object",
        "required": ["status", "inquiry_id", "message", "booking_url"],
        "properties": {
          "status": { "type": "string", "example": "success" },
          "inquiry_id": { "type": "string", "example": "inq_9841f92a" },
          "message": { "type": "string", "example": "Inquiry received. A licensed team member will follow up within 1-2 business days." },
          "booking_url": { "type": "string", "format": "uri", "example": "https://penuelbilingualcounseling.clientsecure.me/" },
          "whatsapp": { "type": "string", "example": "+19138903876" }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": ["field", "issue"],
        "properties": {
          "field": { "type": "string", "example": "state" },
          "issue": { "type": "string", "example": "Must provide client location state (e.g., FL, MO, KS, VA)." }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["type", "title", "status", "detail", "code", "message"],
        "properties": {
          "type": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/docs/errors#invalid-request" },
          "title": { "type": "string", "example": "Invalid Request" },
          "status": { "type": "integer", "example": 400 },
          "detail": { "type": "string", "example": "Validation failed for inquiry submission." },
          "instance": { "type": "string", "example": "/api/v1/inquiries" },
          "code": { "type": "string", "example": "INVALID_REQUEST" },
          "message": { "type": "string", "example": "Validation failed for inquiry submission." },
          "hint": { "type": "string", "example": "Ensure required fields (name, contact, service_type, state) are supplied." },
          "documentation_url": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/docs" },
          "invalid_params": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/ErrorDetail" }
          },
          "error": {
            "type": "object",
            "required": ["code", "message", "status"],
            "properties": {
              "code": { "type": "string", "example": "INVALID_REQUEST" },
              "message": { "type": "string", "example": "Validation failed for inquiry submission." },
              "status": { "type": "integer", "example": 400 },
              "hint": { "type": "string", "example": "Ensure required fields are supplied." },
              "documentation_url": { "type": "string", "format": "uri", "example": "https://www.penuelcounseling.com/docs" },
              "details": {
                "type": "array",
                "items": { "$ref": "#/components/schemas/ErrorDetail" }
              }
            }
          }
        }
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Invalid parameters or malformed request payload.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "NotFoundError": {
        "description": "The requested endpoint or resource was not found.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "MethodNotAllowedError": {
        "description": "The requested HTTP method is not allowed for this route.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "RateLimitError": {
        "description": "Rate limit exceeded. Self-throttle requests based on Retry-After header.",
        "headers": {
          "Retry-After": {
            "schema": { "type": "integer" },
            "description": "Seconds to wait before retrying."
          },
          "RateLimit-Limit": {
            "schema": { "type": "integer" },
            "description": "Maximum allowed requests in current window."
          },
          "RateLimit-Remaining": {
            "schema": { "type": "integer" },
            "description": "Remaining request quota in current window."
          },
          "RateLimit-Reset": {
            "schema": { "type": "integer" },
            "description": "Seconds remaining until window reset."
          }
        },
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error encountered while processing the request.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      },
      "DefaultError": {
        "description": "Unexpected error response conforming to RFC 9457 Problem Details.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          },
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" }
          }
        }
      }
    }
  }
}