{
  "openapi": "3.0.3",
  "info": {
    "title": "TIM Platform API",
    "description": "TIM (The Intelligence Machine) Platform API enables developers to integrate AI-powered real estate sales automation into their applications. TIM provides three core capabilities: THINK (agent decisions), REMEMBER (memory storage), and ACT (workflow execution).",
    "version": "1.0.0",
    "contact": {
      "name": "TIM Support",
      "email": "support@timlive.ai",
      "url": "https://timlive.ai"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://timlive.ai/terms"
    }
  },
  "servers": [
    {
      "url": "https://ztyfadxegrzzctxwlcmy.supabase.co",
      "description": "TIM API"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Agent",
      "description": "THINK - AI decision-making for lead actions"
    },
    {
      "name": "Memory",
      "description": "REMEMBER - Store and extract insights from notes"
    },
    {
      "name": "Workflow",
      "description": "ACT - Execute calls, SMS, stage changes, and analysis"
    }
  ],
  "paths": {
    "/functions/v1/api-run-agent": {
      "post": {
        "tags": ["Agent"],
        "summary": "Get AI Decision",
        "description": "Submit a lead ID and receive TIM's AI-powered recommendation for the best next action. In sandbox mode, uses a demo lead. In live mode, queries your actual lead data.",
        "operationId": "runAgent",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRequest"
              },
              "example": {
                "lead_id": "demo",
                "prompt": "What should I do next with this lead?"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful agent decision",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "decision": {
                      "action": "call",
                      "reasoning": "Lead showed high motivation in recent conversation. Timeline is urgent (moving in 2 weeks). Best to call now to maintain momentum.",
                      "priority": "high",
                      "suggested_script": "Hi Martha, this is TIM following up on our conversation about your property on Oak Street. You mentioned needing to move quickly - I wanted to see if you had any questions about our offer."
                    },
                    "lead_context": {
                      "name": "Martha Johnson",
                      "stage": "pre_offer_follow_up",
                      "last_contact": "2024-01-15T14:30:00Z",
                      "motivation_level": "high"
                    }
                  },
                  "error": null,
                  "timestamp": "2024-01-16T10:30:00Z",
                  "mode": "sandbox"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/functions/v1/api-memory-write": {
      "post": {
        "tags": ["Memory"],
        "summary": "Store Note with AI Extraction",
        "description": "Store a note for a lead and automatically extract structured insights using AI. Extracts timeline, pricing signals, motivation level, urgency, key facts, and sentiment.",
        "operationId": "writeMemory",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryRequest"
              },
              "example": {
                "lead_id": "demo",
                "note": "Seller mentioned they need to move by end of February for a new job in Texas. They're motivated but want at least $285k. Property has some deferred maintenance on the roof."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Note stored successfully with extracted insights",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "stored": true,
                    "insights": {
                      "timeline": "End of February - job relocation to Texas",
                      "pricing_signal": "$285k minimum asking price",
                      "motivation": "high",
                      "urgency": "high",
                      "key_facts": [
                        "Relocating for new job",
                        "Moving to Texas",
                        "Roof needs maintenance"
                      ],
                      "sentiment": "motivated but price-conscious"
                    }
                  },
                  "error": null,
                  "timestamp": "2024-01-16T10:35:00Z",
                  "mode": "sandbox"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/functions/v1/api-workflow-execute": {
      "post": {
        "tags": ["Workflow"],
        "summary": "Execute Workflow",
        "description": "Trigger predefined workflows including making calls, sending SMS, changing lead stages, or running AI analysis on leads.",
        "operationId": "executeWorkflow",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkflowRequest"
              },
              "examples": {
                "call_lead": {
                  "summary": "Trigger a call",
                  "value": {
                    "workflow": "call_lead",
                    "lead_id": "demo",
                    "params": {
                      "priority": "high",
                      "script_override": "Custom opening script for this call"
                    }
                  }
                },
                "send_sms": {
                  "summary": "Send SMS message",
                  "value": {
                    "workflow": "send_sms",
                    "lead_id": "demo",
                    "params": {
                      "message": "Hi Martha, just following up on our conversation. Let me know if you have any questions!"
                    }
                  }
                },
                "stage_change": {
                  "summary": "Change lead stage",
                  "value": {
                    "workflow": "stage_change",
                    "lead_id": "demo",
                    "params": {
                      "new_stage": "make_offer"
                    }
                  }
                },
                "analyze": {
                  "summary": "Run AI analysis",
                  "value": {
                    "workflow": "analyze",
                    "lead_id": "demo",
                    "params": {
                      "analysis_type": "full"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Workflow executed successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkflowResponse"
                },
                "example": {
                  "success": true,
                  "data": {
                    "workflow": "call_lead",
                    "execution_id": "exec_abc123",
                    "status": "queued",
                    "scheduled_at": "2024-01-16T10:40:00Z",
                    "result": {
                      "action_id": "action_xyz789",
                      "message": "Call queued for Martha Johnson"
                    }
                  },
                  "error": null,
                  "timestamp": "2024-01-16T10:40:00Z",
                  "mode": "sandbox"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request or unsupported workflow",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key provided by TIM. Use `demo_key_sandbox_12345` for testing."
      }
    },
    "schemas": {
      "AgentRequest": {
        "type": "object",
        "required": ["lead_id"],
        "properties": {
          "lead_id": {
            "type": "string",
            "description": "The lead ID to analyze. Use 'demo' for sandbox testing.",
            "example": "demo"
          },
          "prompt": {
            "type": "string",
            "description": "Optional custom prompt to guide TIM's analysis.",
            "example": "What should I do next with this lead?"
          }
        }
      },
      "AgentResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "$ref": "#/components/schemas/AgentDecision"
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string",
            "enum": ["sandbox", "live"]
          }
        }
      },
      "AgentDecision": {
        "type": "object",
        "properties": {
          "decision": {
            "type": "object",
            "properties": {
              "action": {
                "type": "string",
                "enum": ["call", "sms", "email", "wait", "escalate"],
                "description": "Recommended action type"
              },
              "reasoning": {
                "type": "string",
                "description": "TIM's reasoning for this recommendation"
              },
              "priority": {
                "type": "string",
                "enum": ["low", "medium", "high", "urgent"]
              },
              "suggested_script": {
                "type": "string",
                "description": "Suggested talking points or message"
              }
            }
          },
          "lead_context": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "stage": {
                "type": "string"
              },
              "last_contact": {
                "type": "string",
                "format": "date-time"
              },
              "motivation_level": {
                "type": "string"
              }
            }
          }
        }
      },
      "MemoryRequest": {
        "type": "object",
        "required": ["lead_id", "note"],
        "properties": {
          "lead_id": {
            "type": "string",
            "description": "The lead ID to store the note for. Use 'demo' for sandbox.",
            "example": "demo"
          },
          "note": {
            "type": "string",
            "description": "The note content to store and analyze.",
            "example": "Seller mentioned they need to move by end of February."
          }
        }
      },
      "MemoryResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "stored": {
                "type": "boolean"
              },
              "insights": {
                "$ref": "#/components/schemas/InsightExtraction"
              }
            }
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string",
            "enum": ["sandbox", "live"]
          }
        }
      },
      "InsightExtraction": {
        "type": "object",
        "properties": {
          "timeline": {
            "type": "string",
            "description": "Extracted timeline information"
          },
          "pricing_signal": {
            "type": "string",
            "description": "Any pricing information mentioned"
          },
          "motivation": {
            "type": "string",
            "enum": ["low", "medium", "high"],
            "description": "Assessed motivation level"
          },
          "urgency": {
            "type": "string",
            "enum": ["low", "medium", "high"],
            "description": "Assessed urgency level"
          },
          "key_facts": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Key facts extracted from the note"
          },
          "sentiment": {
            "type": "string",
            "description": "Overall sentiment analysis"
          }
        }
      },
      "WorkflowRequest": {
        "type": "object",
        "required": ["workflow", "lead_id"],
        "properties": {
          "workflow": {
            "type": "string",
            "enum": ["call_lead", "send_sms", "stage_change", "analyze"],
            "description": "The workflow type to execute"
          },
          "lead_id": {
            "type": "string",
            "description": "The lead ID to execute the workflow for"
          },
          "params": {
            "type": "object",
            "description": "Workflow-specific parameters",
            "additionalProperties": true
          }
        }
      },
      "WorkflowResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "object",
            "properties": {
              "workflow": {
                "type": "string"
              },
              "execution_id": {
                "type": "string"
              },
              "status": {
                "type": "string",
                "enum": ["queued", "processing", "completed", "failed"]
              },
              "scheduled_at": {
                "type": "string",
                "format": "date-time"
              },
              "result": {
                "type": "object",
                "additionalProperties": true
              }
            }
          },
          "error": {
            "type": "string",
            "nullable": true
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string",
            "enum": ["sandbox", "live"]
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "data": {
            "type": "object",
            "nullable": true
          },
          "error": {
            "type": "string",
            "example": "Invalid API key"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "mode": {
            "type": "string",
            "enum": ["sandbox", "live"]
          }
        }
      },
      "LeadStage": {
        "type": "string",
        "enum": [
          "new_lead",
          "contacted_unqualified",
          "pre_offer_follow_up",
          "get_info",
          "make_offer",
          "post_offer_follow_up",
          "counter_offer",
          "underwriting",
          "offer_accepted",
          "desk_tim",
          "dead"
        ],
        "description": "Valid lead stages in TIM"
      },
      "DemoLead": {
        "type": "object",
        "description": "Demo lead object used in sandbox mode",
        "properties": {
          "id": {
            "type": "string",
            "example": "demo-lead-001"
          },
          "first_name": {
            "type": "string",
            "example": "Martha"
          },
          "last_name": {
            "type": "string",
            "example": "Johnson"
          },
          "phone_number": {
            "type": "string",
            "example": "5551234567"
          },
          "email": {
            "type": "string",
            "example": "martha.johnson@example.com"
          },
          "address": {
            "type": "string",
            "example": "123 Oak Street"
          },
          "city": {
            "type": "string",
            "example": "Austin"
          },
          "state": {
            "type": "string",
            "example": "TX"
          },
          "stage": {
            "type": "string",
            "example": "pre_offer_follow_up"
          },
          "motivation_level": {
            "type": "string",
            "example": "high"
          },
          "asking_price": {
            "type": "string",
            "example": "$285,000"
          },
          "master_notes_log": {
            "type": "string",
            "example": "Initial contact made. Seller motivated due to job relocation."
          }
        }
      }
    }
  }
}