openapi: "3.1.0"
info:
  title: "Learnrithm AI Best AI Learning Platform AI Exam Preparation AI Study Tool AI Tutor AI for Students — Bilarna Provider API"
  version: "1.0.0"
  description: |
    Machine-readable API for interacting with Learnrithm AI Best AI Learning Platform AI Exam Preparation AI Study Tool AI Tutor AI for Students on the Bilarna B2B network.
    Learnrithm AI is the most advanced AI learning platform for students, teachers, and schools. Instantly access AI-powered exam preparation, personalized study tools, smart tutoring, homework help, and adaptive learning for K-12, college, and professional exams. Trusted by thousands for AI test prep, revision, and academ
    Services offered: AI Learning Platforms, AI Test Prep & Tools.
  contact:
    name: "Learnrithm AI Best AI Learning Platform AI Exam Preparation AI Study Tool AI Tutor AI for Students"
    url: "https://bilarna.com/provider/learnrithm"
  x-provider:
    slug: "learnrithm"
    verified: true
    accepts_meetings: false
    logo: "https://learnrithm.com/assets/images/univeristies/imgs.jpg"


servers:
  - url: "https://api.bilarna.com/api"
    description: Bilarna API

paths:
  /agent/match:
    post:
      operationId: bilarna_match
      summary: Find matching providers by service need
      description: |
        Returns a ranked list of providers (business_id, score, description).
        Use the returned business_id with /agent/request to submit a
        service request to Learnrithm AI Best AI Learning Platform AI Exam Preparation AI Study Tool AI Tutor AI for Students (business_id from match results).
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: "1.0"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [need]
              properties:
                need:
                  type: string
                  description: Free-text service description
                  example: "AI Learning Platforms"
      responses:
        "200":
          description: Matched providers
          content:
            application/json:
              schema:
                type: object
                properties:
                  matchRequestId:
                    type: integer
                  candidates:
                    type: array
                    items:
                      type: object
                      properties:
                        business_id:
                          type: integer
                        score:
                          type: number
                        description:
                          type: string

  /agent/request:
    post:
      operationId: bilarna_request
      summary: Submit a service request to a provider
      description: |
        Sends a service request. When business_id is provided the request
        goes directly to that provider; otherwise Bilarna matches the
        request to relevant providers automatically.
      parameters:
        - name: api-version
          in: query
          required: true
          schema:
            type: string
            default: "1.0"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [need, contact_name, email]
              properties:
                business_id:
                  type: integer
                  description: Target provider ID (from bilarna_match)
                  nullable: true
                need:
                  type: string
                  description: Free-text description of the service need
                contact_name:
                  type: string
                  description: Full name of the decision-maker
                email:
                  type: string
                  format: email
                  description: Business email for lead routing
                phone:
                  type: string
                  description: Business phone number (optional)
                category:
                  type: string
                  description: Service category
                country:
                  type: string
                  description: Provider country preference
                budget_max:
                  type: number
                  description: Maximum project budget in USD
      responses:
        "200":
          description: Request created
          content:
            application/json:
              schema:
                type: object
                properties:
                  matchRequestId:
                    type: integer
                  business_id:
                    type: integer
                  lead:
                    type: object
                    properties:
                      contactName:
                        type: string
                      email:
                        type: string
                      phone:
                        type: string