BuyAPI API

openapi: 3.1.0
info:
  title: BuyAPI API
  version: '2026-11-03'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-03: 5 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; BuyAPI has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 5
    pages-with-code: 0
    pages-read: 1
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-03'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://buyapi.ai/docs
paths:
  /api/evidence:
    get:
      operationId: get_api_evidence
      tags:
      - Api
      summary: GET /api/evidence ?subjectType=vendor&subjectId=/database/neon&limit=8 → {evidence} reviewed evidence rows with source URLs, stance,
        confidence, and observed dates
      x-source: https://buyapi.ai/docs
      parameters:
      - name: subjectType
        in: query
        required: true
        schema:
          type: string
        description: vendor · category · stack · comparison
      - name: subjectId
        in: query
        required: true
        schema:
          type: string
        description: Identifier such as /database/neon
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum evidence rows
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiEvidenceResponse'
      x-evidence:
        kind: documentation
  /api/recommend:
    post:
      operationId: post_api_recommend
      tags:
      - Api
      summary: 'POST /api/recommend body: { projectDescription, constraints?, workload?, stackContext? } → { stack, decisionMatrix, costEstimate,
        assumptions, unknowns, alternatives, sources, generatedAt }'
      x-source: https://buyapi.ai/docs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiRecommendRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiRecommendResponse'
      x-evidence:
        kind: documentation
  /api/stacks/similar:
    get:
      operationId: get_api_stacks_similar
      tags:
      - Api
      summary: GET /api/stacks/similar ?vendorId=/database/convex&limit=6 → {stacks} public stack profiles with tools, roles, stage, audience,
        and confidence
      x-source: https://buyapi.ai/docs
      parameters:
      - name: vendorId
        in: query
        required: false
        schema:
          type: string
        description: BuyAPI vendor ID
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: Maximum stack profiles
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiStacksSimilarResponse'
      x-evidence:
        kind: documentation
  /api/vendors:
    get:
      operationId: get_api_vendors
      tags:
      - Api
      summary: GET /api/vendors/[...slug] e.g., /api/vendors/database/neon → Full VendorProfile object
      x-source: https://buyapi.ai/docs
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiVendorsResponse'
      x-evidence:
        kind: documentation
  /api/vendors/search:
    get:
      operationId: get_api_vendors_search
      tags:
      - Api
      summary: GET /api/vendors/search ?query=...&category=... → { results, decisionMatrix? }
      x-source: https://buyapi.ai/docs
      parameters:
      - name: query
        in: query
        required: true
        schema:
          type: string
        description: The user's question or task
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: Optional category filter (e.g., database, auth, hosting, payments, email, ui-components)
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiVendorsSearchResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiEvidenceResponse:
      type: object
      properties:
        evidence:
          type: array
          description: Reviewed evidence rows with source type, summary, stance, confidence, source URL, author, and observed date
    PostApiRecommendRequest:
      type: object
      properties:
        projectDescription:
          type: string
          description: What you're building (a sentence or two)
        constraints:
          type: string
          description: Budget, scale, compliance, existing tools
        workload:
          type: object
          description: Explicit workload assumptions (e.g., users, MAU, storage GB, email sends, etc.)
        stackContext:
          type: object
          description: Existing tools from a repo scan or saved stack
      required:
      - projectDescription
    PostApiRecommendResponse:
      type: object
      properties:
        stack:
          type: object
          description: Recommended stack with one pick per layer
        decisionMatrix:
          type: object
          description: Fit, tradeoffs, and reasoning for each layer
        costEstimate:
          type: object
          description: Estimated monthly cost
        assumptions:
          type: array
          description: Assumptions made during recommendation
        unknowns:
          type: array
          description: Unknowns or gaps in data
        alternatives:
          type: array
          description: Alternative options
        sources:
          type: array
          description: Source references used
        generatedAt:
          type: string
          description: Timestamp of generation
    GetApiStacksSimilarResponse:
      type: object
      properties:
        stacks:
          type: array
          description: Public stack profiles with project summary, audience, stage, tools, roles, and confidence
    GetApiVendorsResponse:
      type: object
      properties:
        VendorProfile:
          type: object
          description: Structured vendor profile with pricing, limits, features, known issues, comparisons, company facts, claims, freshness,
            and confidence
    GetApiVendorsSearchResponse:
      type: object
      properties:
        results:
          type: array
          description: A short list of vendor IDs
        decisionMatrix:
          type: object
          description: Optional top‑3 decision matrix with fit labels, confidence, tradeoffs, cost notes, freshness, and sources
tags:
- name: Api