openapi: 3.1.0
info:
  title: BGPT Scientific Paper Search API
  version: "1.0.0"
  description: Search scientific papers and return structured experimental data extracted from full-text studies.
  contact:
    email: contact@bgpt.pro
  license:
    name: MIT
    url: https://github.com/connerlambden/bgpt-mcp/blob/main/LICENSE
servers:
  - url: https://bgpt.pro
paths:
  /api/mcp-search:
    post:
      operationId: searchPapers
      summary: Search scientific papers
      description: Returns paper records with methods, results, sample sizes, limitations, conflicts of interest, quality scores, and other full-text-derived fields.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SearchRequest"
            examples:
              recentCrispr:
                summary: Recent CRISPR delivery papers
                value:
                  query: CRISPR delivery neurons
                  num_results: 5
                  days_back: 365
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    items:
                      $ref: "#/components/schemas/PaperResult"
        "400":
          description: Invalid request
        "402":
          description: Free tier exhausted or billing required
        "500":
          description: Server error
components:
  schemas:
    SearchRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          minLength: 1
          description: Natural-language scientific search query.
          examples:
            - semaglutide cardiovascular outcomes
        num_results:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Number of paper results to return.
        days_back:
          type: integer
          minimum: 1
          description: Restrict results to papers published within the last N days.
        api_key:
          type: string
          description: Optional paid-tier API key after the free result allowance is exhausted.
    PaperResult:
      type: object
      additionalProperties: true
      properties:
        doi:
          type: string
        title:
          type: string
        publication_date:
          type: string
        publication_name:
          type: string
        one_sentence_summary:
          type: string
        results_and_conclusions:
          type: string
        methods_and_experimental_techniques:
          type: string
        sample_size_and_population:
          type: string
        list_of_extracted_data:
          type: string
        problem_statement:
          type: string
        study_context:
          type: string
        how_to_falsify:
          type: string
        study_blindspots:
          type: string
        paper_limitations_and_biases:
          type: string
        conflict_of_interest:
          type: string
        data_availability_statements:
          type: string
        code_and_data_links:
          type: string
        software_and_tools_used:
          type: string
        funding_json:
          type: string
        citations_json:
          type: string
        reference_count:
          type: integer
        quality_scores:
          type: object
          additionalProperties: true