openapi: 3.0.3
info:
  title: Bigakons API
  description: |
    AI-powered procurement intelligence for Kenyan businesses.
    
    ## Base URL
    `https://api.bigakons.com/v1`
    
    ## Authentication
    - Public endpoints: No auth required
    - Protected endpoints: `X-API-Key` header (coming soon)
    
    ## Rate Limits
    | Tier | Requests/Day |
    |------|-------------|
    | Public | 100 |
    | Founder | 10,000 |
    | Enterprise | Custom |
    
    ## Support
    - Email: api@bigakons.com
    - Docs: https://developers.bigakons.com
  version: 1.0.0
  contact:
    name: Bigakons API Support
    url: https://developers.bigakons.com
    email: api@bigakons.com

servers:
  - url: https://api.bigakons.com/v1
    description: Production

tags:
  - name: Health
    description: System status
  - name: Tenders
    description: Search and retrieve tender information

paths:
  /health:
    get:
      tags: [Health]
      summary: API health status
      operationId: getHealth
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /tenders:
    get:
      tags: [Tenders]
      summary: List and search tenders
      description: |
        Search published tenders from Kenyan procurement portals.
        
        **Filters:**
        - `q`: Full-text search (title, ID, procuring entity)
        - `category`: Filter by procurement category
        - `entity_id`: Filter by specific procuring entity
        - `show_all=true`: Include expired tenders (default: active only)
        - `days_until_close`: Tenders closing within N days (1-90)
        
        **Pagination:**
        - `page`: Page number (default: 1)
        - `per_page`: Items per page (default: 20, max: 100)
        
        **Sorting:**
        - `sort=end_date_asc`: Soonest closing first (default)
        - `sort=end_date_desc`: Latest closing first
      operationId: listTenders
      parameters:
        - name: q
          in: query
          description: Search query
          schema: { type: string, maxLength: 200 }
          example: "road construction"
        - name: category
          in: query
          description: Procurement category
          schema: { type: string, enum: [goods, works, services] }
          example: "works"
        - name: entity_id
          in: query
          description: Filter by procuring entity ID
          schema: { type: string }
        - name: show_all
          in: query
          description: Include expired tenders
          schema: { type: boolean, default: false }
          example: true
        - name: days_until_close
          in: query
          description: Tenders closing within N days
          schema: { type: integer, minimum: 1, maximum: 90 }
          example: 14
        - name: sort
          in: query
          description: Sort order
          schema: { type: string, enum: [end_date_asc, end_date_desc], default: end_date_asc }
        - name: page
          in: query
          schema: { type: integer, minimum: 1, default: 1 }
        - name: per_page
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenderList'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '503':
          description: Database unavailable
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /tenders/{tender_id}:
    get:
      tags: [Tenders]
      summary: Get tender details
      operationId: getTender
      parameters:
        - name: tender_id
          in: path
          required: true
          description: Unique tender identifier
          schema: { type: string }
          example: "20260226191003-280592-10/25"
      responses:
        '200':
          description: Tender details
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tender' }
        '404':
          description: Tender not found
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /tenders/{tender_id}/score:
    post:
      tags: [Tenders]
      summary: Calculate win probability (coming soon)
      description: Trigger AI-powered win-probability analysis (async job)
      operationId: scoreTender
      parameters:
        - name: tender_id
          in: path
          required: true
          schema: { type: string }
      responses:
        '202':
          description: Job accepted
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Job' }
        '401':
          description: Authentication required (coming soon)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

  /signals:
    get:
      tags: [Signals]
      summary: Predictive intelligence (coming soon)
      description: AI-generated signals for upcoming tenders (60-90 days before RFP)
      operationId: getSignals
      responses:
        '200':
          description: Predictive signals
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/Signal' } }
                  meta: { $ref: '#/components/schemas/Meta' }

  /webhooks:
    post:
      tags: [Webhooks]
      summary: Register webhook (coming soon)
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url, events]
              properties:
                url: { type: string, format: uri, example: "https://yourapp.com/webhooks/bigakons" }
                events:
                  type: array
                  items: { type: string, enum: [tender.published, tender.updated, signal.generated] }
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Webhook' }

components:
  schemas:
    HealthResponse:
      type: object
      properties:
        status: { type: string, enum: [healthy, degraded, unhealthy], example: "healthy" }
        version: { type: string, example: "1.0.0" }
        timestamp: { type: string, format: date-time }

    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string, enum: [invalid_request, not_found, database_error, internal_error] }
            message: { type: string }
            details: { type: object }

    Tender:
      type: object
      required: [id, title, category, procuring_entity, closing_date]
      properties:
        id: { type: string, description: "Unique tender identifier", example: "20260226191003-280592-10/25" }
        title: { type: string, example: "Supply of staff uniform" }
        procurement_method: { type: string, nullable: true, example: "open" }
        category: { type: string, nullable: true, enum: [goods, works, services], example: "goods" }
        procuring_entity:
          type: object
          properties:
            id: { type: string, nullable: true, example: "7573" }
            name: { type: string, nullable: true, example: "Ministry of Education" }
        tender_fee: { $ref: '#/components/schemas/Money' }
        bid_security: { $ref: '#/components/schemas/Money' }
        closing_date:
          type: object
          properties:
            iso: { type: string, format: date-time }
            human: { type: string, example: "5 Jun 2026, 1:00pm" }
            days_remaining: { type: integer, nullable: true, example: 28 }
        start_date:
          type: object
          nullable: true
          properties:
            iso: { type: string, format: date-time }
            human: { type: string }
        links:
          type: object
          properties:
            self: { type: string, format: uri }
            apply: { type: string, format: uri, description: "Official application URL" }

    TenderList:
      type: object
      required: [data, meta, links]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Tender' } }
        meta: { $ref: '#/components/schemas/Meta' }
        links: { $ref: '#/components/schemas/PaginationLinks' }

    Money:
      type: object
      nullable: true
      properties:
        amount: { type: number, format: float, example: 5000.00 }
        currency: { type: string, default: "KES" }
        formatted: { type: string, example: "KES 5,000.00" }

    Meta:
      type: object
      properties:
        total: { type: integer, example: 247 }
        page: { type: integer, example: 1 }
        per_page: { type: integer, example: 20 }
        total_pages: { type: integer, example: 13 }

    PaginationLinks:
      type: object
      properties:
        self: { type: string, format: uri }
        first: { type: string, format: uri }
        last: { type: string, format: uri }
        next: { type: string, format: uri, nullable: true }
        prev: { type: string, format: uri, nullable: true }

    Job:
      type: object
      properties:
        id: { type: string, example: "job_abc123xyz" }
        type: { type: string, enum: [tender_scoring] }
        status: { type: string, enum: [pending, processing, completed, failed] }
        created_at: { type: string, format: date-time }

    Signal:
      type: object
      properties:
        id: { type: string }
        title: { type: string }
        sector: { type: string }
        predicted_date: { type: string, format: date }
        confidence: { type: integer, minimum: 0, maximum: 100 }

    Webhook:
      type: object
      properties:
        id: { type: string }
        url: { type: string, format: uri }
        events: { type: array, items: { type: string } }
        status: { type: string, enum: [active, paused] }
        created_at: { type: string, format: date-time }