openapi: 3.1.0
info:
  title: BioContext7 API
  description: |
    Bioinformatics registry aggregator and self-healing pipeline generator.

    Search 47,000+ tools from bio.tools, Bioconda, nf-core, and WorkflowHub.
    Generate production-ready pipelines in Nextflow, Snakemake, WDL, or CWL.
  version: 0.1.0
  contact:
    name: BioContext7
    url: https://github.com/Hordago-Labs/biocontext7
    email: jeff@lamiak.works
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://mcp.biocontext7.com
    description: Production (hosted)
  - url: http://localhost:8000
    description: Local development

security:
  - BearerAuth: []
  - {}

tags:
  - name: Tools
    description: Search and retrieve bioinformatics tool metadata
  - name: Pipelines
    description: Generate and validate bioinformatics pipelines
  - name: Registries
    description: Query registry status and statistics
  - name: Admin
    description: Administrative endpoints (requires admin scope)

paths:
  /api/v2/tools/search:
    get:
      operationId: searchTools
      tags: [Tools]
      summary: Search for bioinformatics tools
      description: |
        Search across all registries with keyword or EDAM term filtering.
        Returns paginated results sorted by relevance.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
          description: Search query (keyword or natural language)
          example: alignment
        - name: registry
          in: query
          schema:
            type: string
            enum: [biotools, bioconda, nfcore, workflowhub]
          description: Filter by registry
        - name: edam_operation
          in: query
          schema:
            type: string
          description: Filter by EDAM operation URI
          example: operation_0292
        - name: edam_topic
          in: query
          schema:
            type: string
          description: Filter by EDAM topic URI
          example: topic_0622
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number
        - name: per_page
          in: query
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
          description: Results per page
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ToolSearchResponse"
          headers:
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /api/v2/tools/{tool_id}:
    get:
      operationId: getTool
      tags: [Tools]
      summary: Get tool details
      description: Retrieve detailed metadata for a specific tool by ID.
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
          description: Tool identifier
          example: bowtie2
      responses:
        "200":
          description: Tool details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Tool"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v2/tools/{tool_id}/resolve:
    get:
      operationId: resolveTool
      tags: [Tools]
      summary: Resolve tool to container and version
      description: |
        Resolve a tool to its container image, latest version,
        and installation instructions.
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
          example: star
      responses:
        "200":
          description: Resolved tool information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResolvedTool"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v2/tools/submit:
    post:
      operationId: submitTool
      tags: [Tools, Admin]
      summary: Submit a new tool
      description: Submit a bioinformatics tool for inclusion in BioContext7.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ToolSubmission"
      responses:
        "201":
          description: Tool submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  status:
                    type: string
                    enum: [pending_review, auto_approved]
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v2/pipelines/generate:
    post:
      operationId: generatePipeline
      tags: [Pipelines]
      summary: Generate a pipeline
      description: |
        Generate a bioinformatics pipeline from a natural language intent.
        Requires authentication.
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PipelineRequest"
      responses:
        "200":
          description: Generated pipeline
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pipeline"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /api/v2/pipelines/validate:
    post:
      operationId: validatePipeline
      tags: [Pipelines]
      summary: Validate a pipeline
      description: |
        Validate an existing pipeline for correctness and optionally
        auto-fix detected errors.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ValidationRequest"
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ValidationResult"

  /api/v2/pipelines/targets:
    get:
      operationId: listPipelineTargets
      tags: [Pipelines]
      summary: List compilation targets
      description: List all supported pipeline compilation targets.
      responses:
        "200":
          description: Available targets
          content:
            application/json:
              schema:
                type: object
                properties:
                  targets:
                    type: array
                    items:
                      $ref: "#/components/schemas/PipelineTarget"

  /api/v2/registries:
    get:
      operationId: listRegistries
      tags: [Registries]
      summary: List registries
      description: List all supported registries with current status.
      responses:
        "200":
          description: Registry list
          content:
            application/json:
              schema:
                type: object
                properties:
                  registries:
                    type: array
                    items:
                      $ref: "#/components/schemas/Registry"

  /api/v2/registries/{registry_id}/status:
    get:
      operationId: getRegistryStatus
      tags: [Registries]
      summary: Get registry status
      description: Get detailed status and statistics for a specific registry.
      parameters:
        - name: registry_id
          in: path
          required: true
          schema:
            type: string
          example: biotools
      responses:
        "200":
          description: Registry status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistryStatus"
        "404":
          $ref: "#/components/responses/NotFound"

  /health:
    get:
      operationId: healthCheck
      tags: [Admin]
      summary: Health check
      description: Returns service health status.
      security: []
      responses:
        "200":
          description: Healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: healthy
                  version:
                    type: string
                    example: 0.1.0

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key authentication. Pass your API key as a Bearer token.
        Keys are created at https://biocontext7.com/dashboard.

  schemas:
    Tool:
      type: object
      required: [id, name, description, registry]
      properties:
        id:
          type: string
          example: bowtie2
        name:
          type: string
          example: Bowtie 2
        description:
          type: string
          example: Fast and sensitive read alignment
        registry:
          type: string
          enum: [biotools, bioconda, nfcore, workflowhub, tooluniverse, internal]
          example: biotools
        homepage:
          type: string
          format: uri
          example: https://bowtie-bio.sourceforge.net/bowtie2/
        edam_operations:
          type: array
          items:
            type: string
          example: [operation_0292]
        edam_topics:
          type: array
          items:
            type: string
          example: [topic_0622]
        inputs:
          type: array
          items:
            $ref: "#/components/schemas/DataPort"
        outputs:
          type: array
          items:
            $ref: "#/components/schemas/DataPort"
        container:
          type: string
          example: biocontainers/bowtie2:2.5.3--h3a4fef7_0
        license:
          type: string
          example: GPL-3.0
        verified:
          type: boolean
          example: true

    DataPort:
      type: object
      properties:
        format:
          type: string
          example: format_1930
        description:
          type: string
          example: FASTQ reads

    ToolSearchResponse:
      type: object
      required: [tools, total, page, per_page]
      properties:
        tools:
          type: array
          items:
            $ref: "#/components/schemas/Tool"
        total:
          type: integer
          example: 342
        page:
          type: integer
          example: 1
        per_page:
          type: integer
          example: 25

    ResolvedTool:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        version:
          type: string
          example: 2.5.3
        container:
          type: string
          example: biocontainers/bowtie2:2.5.3--h3a4fef7_0
        install_cmd:
          type: string
          example: conda install -c bioconda bowtie2=2.5.3

    ToolSubmission:
      type: object
      required: [name, description, homepage]
      properties:
        name:
          type: string
        description:
          type: string
        homepage:
          type: string
          format: uri
        edam_operations:
          type: array
          items:
            type: string
        edam_topics:
          type: array
          items:
            type: string
        inputs:
          type: array
          items:
            $ref: "#/components/schemas/DataPort"
        outputs:
          type: array
          items:
            $ref: "#/components/schemas/DataPort"
        container:
          type: string
        license:
          type: string

    PipelineRequest:
      type: object
      required: [intent, target]
      properties:
        intent:
          type: string
          description: Natural language pipeline description
          example: RNA-seq from FASTQ to differential expression
        target:
          type: string
          enum: [nextflow, snakemake, wdl, cwl]
          example: nextflow
        options:
          type: object
          properties:
            container_engine:
              type: string
              enum: [docker, singularity, podman]
              default: docker
            include_qc:
              type: boolean
              default: true

    Pipeline:
      type: object
      required: [pipeline_id, target, files, tools_used]
      properties:
        pipeline_id:
          type: string
          example: pipe_abc123
        target:
          type: string
          example: nextflow
        files:
          type: object
          additionalProperties:
            type: string
          example:
            main.nf: "#!/usr/bin/env nextflow\n..."
            nextflow.config: "..."
        tools_used:
          type: array
          items:
            type: string
          example: [fastp, star, featurecounts, deseq2]
        manifest:
          $ref: "#/components/schemas/Manifest"

    Manifest:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        tool_versions:
          type: object
          additionalProperties:
            type: string
        registry_sources:
          type: object
          additionalProperties:
            type: string

    ValidationRequest:
      type: object
      required: [files, target]
      properties:
        files:
          type: object
          additionalProperties:
            type: string
        target:
          type: string
          enum: [nextflow, snakemake, wdl, cwl]
        fix:
          type: boolean
          default: false

    ValidationResult:
      type: object
      properties:
        valid:
          type: boolean
        errors:
          type: array
          items:
            type: object
            properties:
              line:
                type: integer
              message:
                type: string
              severity:
                type: string
                enum: [error, warning, info]
        fixed_files:
          type: object
          additionalProperties:
            type: string

    PipelineTarget:
      type: object
      properties:
        id:
          type: string
          example: nextflow
        name:
          type: string
          example: Nextflow DSL2
        version:
          type: string
          example: ">=23.04"

    Registry:
      type: object
      properties:
        id:
          type: string
          example: biotools
        name:
          type: string
          example: bio.tools
        url:
          type: string
          format: uri
        tool_count:
          type: integer
        status:
          type: string
          enum: [active, degraded, offline]

    RegistryStatus:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
          enum: [active, degraded, offline]
        tool_count:
          type: integer
        last_sync:
          type: string
          format: date-time
        avg_response_ms:
          type: integer

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            retry_after:
              type: integer

  responses:
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: rate_limit_exceeded
              message: Rate limit exceeded. Retry after 60 seconds.
              retry_after: 60

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: not_found
              message: The requested resource was not found.

    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error:
              code: unauthorized
              message: Valid API key required. Create one at https://biocontext7.com/dashboard.