openapi: 3.0.3
info:
  title: Timo Hub API
  version: 1.0.0
  description: |
    RESTful API for programmatic access to Timo Hub features.
    
    ## Authentication
    All API endpoints (except `/health`) require authentication via API key.
    
    Include your API key in the Authorization header:
    ```
    Authorization: Bearer timo_live_your_api_key_here
    ```
    
    ## Rate Limiting
    API calls are rate-limited based on your plan:
    - **Free:** 1,000 calls/month
    - **Starter:** 5,000 calls/month
    - **Developer:** 50,000 calls/month
    - **Business:** 250,000 calls/month
    - **Enterprise:** Unlimited
    
    Rate limit info is returned in response headers:
    - `X-RateLimit-Limit`: Total calls allowed per month
    - `X-RateLimit-Remaining`: Calls remaining this month
    - `X-RateLimit-Reset`: Unix timestamp when limit resets
    
    ## Errors
    Errors follow a standard format:
    ```json
    {
      "error": {
        "code": "invalid_parameter",
        "message": "The 'period' parameter must be one of: 7d, 30d, 90d",
        "type": "api_error",
        "param": "period"
      },
      "meta": {
        "request_id": "req_abc123",
        "timestamp": "2026-02-04T04:00:00Z"
      }
    }
    ```
  contact:
    name: Timo Hub Support
    url: https://dashboard.scottmartin.tech
    email: scott@scottmartin.tech
  license:
    name: Proprietary

servers:
  - url: https://dashboard.scottmartin.tech/api/v1
    description: Production API
  - url: http://127.0.0.1:8080/api/v1
    description: Local development

tags:
  - name: Authentication
    description: API key management
  - name: Account
    description: Account and quota information
  - name: Usage
    description: Usage analytics and tracking
  - name: Teams
    description: Team management (Enterprise)
  - name: Alerts
    description: Alert and notification management

paths:
  /health:
    get:
      summary: Health check
      description: Public endpoint to check API status (no auth required)
      tags:
        - System
      responses:
        '200':
          description: API is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      status:
                        type: string
                        example: ok
                      version:
                        type: string
                        example: 1.0.0
                      timestamp:
                        type: string
                        format: date-time

  /auth/keys:
    get:
      summary: List API keys
      description: Get all API keys for the authenticated user
      tags:
        - Authentication
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: List of API keys
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      keys:
                        type: array
                        items:
                          $ref: '#/components/schemas/ApiKey'
    
    post:
      summary: Create API key
      description: Generate a new API key. The full key is only shown once!
      tags:
        - Authentication
      security:
        - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  example: Production Server
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      api_key:
                        type: string
                        example: timo_live_abc123xyz789
                        description: Full API key (only shown once!)
                      prefix:
                        type: string
                        example: timo_live_abc12
                      name:
                        type: string
                      warning:
                        type: string
  
  /auth/keys/{keyId}:
    delete:
      summary: Revoke API key
      description: Permanently revoke an API key
      tags:
        - Authentication
      security:
        - ApiKeyAuth: []
      parameters:
        - name: keyId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Key revoked
        '404':
          description: Key not found

  /account:
    get:
      summary: Get account info
      description: Get account details for the authenticated user
      tags:
        - Account
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Account'

  /account/quota:
    get:
      summary: Get API quota usage
      description: Get current month's API quota usage
      tags:
        - Account
      security:
        - ApiKeyAuth: []
      responses:
        '200':
          description: Quota information
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Quota'

  /usage/stats:
    get:
      summary: Get usage statistics
      description: Get usage analytics for a time period
      tags:
        - Usage
      security:
        - ApiKeyAuth: []
      parameters:
        - name: period
          in: query
          schema:
            type: string
            enum: [7d, 30d, 90d]
            default: 30d
      responses:
        '200':
          description: Usage statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UsageStats'

  /usage/forecast:
    get:
      summary: Get usage forecast
      description: Get predictive analytics for quota usage
      tags:
        - Usage
      security:
        - ApiKeyAuth: []
      parameters:
        - name: days
          in: query
          schema:
            type: integer
            minimum: 7
            maximum: 90
            default: 30
      responses:
        '200':
          description: Usage forecast
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Forecast'

components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        API key authentication. Include your key in the Authorization header:
        ```
        Authorization: Bearer timo_live_your_api_key_here
        ```

  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: integer
        key_prefix:
          type: string
          example: timo_live_abc12
        name:
          type: string
        last_used_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        revoked:
          type: integer
          enum: [0, 1]

    Account:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        username:
          type: string
        plan:
          type: string
          enum: [free, starter, developer, business, enterprise]
        status:
          type: string
        created_at:
          type: string
          format: date-time

    Quota:
      type: object
      properties:
        plan:
          type: string
        limit:
          type: integer
          description: Total API calls allowed per month
        used:
          type: integer
          description: API calls used this month
        remaining:
          type: integer
          description: API calls remaining
        reset_at:
          type: integer
          description: Unix timestamp when quota resets
        percentage:
          type: number
          format: float
          description: Percentage of quota used

    UsageStats:
      type: object
      properties:
        total_events:
          type: integer
        time_saved_hours:
          type: number
        value_delivered:
          type: number
        automations_run:
          type: integer
        api_calls:
          type: integer

    Forecast:
      type: object
      properties:
        trend:
          type: string
          enum: [increasing, decreasing, stable]
        growth_rate:
          type: number
        projected_usage:
          type: integer
        days_until_limit:
          type: integer
          nullable: true
        confidence:
          type: number
          description: R² confidence score (0-1)

    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            type:
              type: string
              default: api_error
        meta:
          type: object
          properties:
            request_id:
              type: string
            timestamp:
              type: string
              format: date-time
