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.

    ### API Versioning & Lifecycle Policy
    - **Versioning Strategy**: URI path-based versioning (`/api/v1/...`). Minor backwards-compatible additions do not alter the major version number.
    - **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.
    - **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, 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.
      operationId: submitInquiry
      tags: [Inquiries]
      requestBody:
        required: true
        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
        title:
          type: string
        languages:
          type: array
          items:
            type: string
        profiles:
          type: array
          items:
            type: string
    LocationInfo:
      type: object
      required: [city, state, country]
      properties:
        city:
          type: string
        state:
          type: string
        country:
          type: string
    ContactChannels:
      type: object
      required: [whatsapp, phone, schedule_online]
      properties:
        whatsapp:
          type: string
        phone:
          type: string
        schedule_online:
          type: string
    ReviewSummary:
      type: object
      required: [rating, count]
      properties:
        rating:
          type: number
        count:
          type: integer
        profile_url:
          type: string
    PracticeInfo:
      type: object
      required: [name, legal_name, description, therapist, location, service_delivery, licensed_telehealth_states, booking_url, contact, reviews]
      properties:
        name:
          type: string
        legal_name:
          type: string
        description:
          type: string
        therapist:
          $ref: '#/components/schemas/TherapistProfile'
        location:
          $ref: '#/components/schemas/LocationInfo'
        service_delivery:
          type: string
        licensed_telehealth_states:
          type: array
          items:
            type: string
        booking_url:
          type: string
        contact:
          $ref: '#/components/schemas/ContactChannels'
        reviews:
          $ref: '#/components/schemas/ReviewSummary'
        links:
          type: object
    ServiceItem:
      type: object
      required: [id, category, name, description, languages, url]
      properties:
        id:
          type: string
        category:
          type: string
        name:
          type: string
        description:
          type: string
        languages:
          type: array
          items:
            type: string
        url:
          type: string
        url_es:
          type: string
        target_concerns:
          type: array
          items:
            type: string
        form_type:
          type: string
    ServiceCatalog:
      type: object
      required: [provider, modality, languages_supported, service_states, services]
      properties:
        provider:
          type: string
        modality:
          type: string
        languages_supported:
          type: array
          items:
            type: string
        service_states:
          type: array
          items:
            type: string
        services:
          type: array
          items:
            $ref: '#/components/schemas/ServiceItem'
    TurnaroundOption:
      type: object
      required: [business_days, description]
      properties:
        business_days:
          type: integer
        description:
          type: string
    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
        form_number:
          type: string
        key_components:
          type: array
          items:
            type: string
    AttorneyCollaboration:
      type: object
      required: [records_review, attorney_consultation]
      properties:
        records_review:
          type: string
        attorney_consultation:
          type: string
    EvaluationBooking:
      type: object
      required: [url, whatsapp]
      properties:
        url:
          type: string
        whatsapp:
          type: string
        consultation:
          type: string
    EvaluationDetails:
      type: object
      required: [provider, evaluator, purpose, admissibility, telehealth_jurisdiction, turnaround_times, evaluation_types, attorney_collaboration, booking]
      properties:
        provider:
          type: string
        evaluator:
          $ref: '#/components/schemas/TherapistProfile'
        purpose:
          type: string
        admissibility:
          type: string
        telehealth_jurisdiction:
          type: array
          items:
            type: string
        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
        contact:
          type: string
        preferred_language:
          type: string
          enum: [en, es]
        service_type:
          type: string
        state:
          type: string
        notes:
          type: string
    InquiryResponse:
      type: object
      required: [status, inquiry_id, message, booking_url]
      properties:
        status:
          type: string
        inquiry_id:
          type: string
        message:
          type: string
        booking_url:
          type: string
        whatsapp:
          type: string
    ErrorDetail:
      type: object
      required: [field, issue]
      properties:
        field:
          type: string
        issue:
          type: string
    ErrorResponse:
      type: object
      required: [error]
      properties:
        type:
          type: string
        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
        RateLimit-Limit:
          schema:
            type: integer
        RateLimit-Remaining:
          schema:
            type: integer
        RateLimit-Reset:
          schema:
            type: integer
      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'