{
  "openapi": "3.1.0",
  "info": {
    "title": "Sevren AI: leads API",
    "version": "1.0.0",
    "summary": "Public route for an AI agent to send a lead on behalf of a company.",
    "description": "Public route for an AI agent to send a lead on behalf of a company. One of the Sevren partners answers on the WhatsApp number provided; there is no automatic proposal. Send a lead only with authorization from the person or company represented (LGPD), one submission per company, no sensitive data. Do not send the `status` field: without it the lead is stored as `em_conversa` and the team reviews it before any contact. The server also accepts internal fields used by the site chat (`id`, `status`, `transcript`, `requestedSite`, `requestedCall`, `preferredCallWindow`, `ownerRequest`); agents should not send them.",
    "contact": {
      "name": "Sevren AI",
      "url": "https://sevrenai.com/agentes/"
    }
  },
  "servers": [
    {
      "url": "https://sevrenai.com"
    }
  ],
  "tags": [
    {
      "name": "leads"
    }
  ],
  "paths": {
    "/api/leads": {
      "post": {
        "tags": [
          "leads"
        ],
        "operationId": "createLead",
        "summary": "Send a lead",
        "description": "Creates a lead. Limit: 30 requests per minute per IP. Maximum body: 64 KB. The 200 response carries the id and the stored status (em_conversa when the agent does not send status).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LeadRequest"
              },
              "examples": {
                "agente": {
                  "summary": "Lead from an AI agent (fictitious data)",
                  "value": {
                    "name": "Ana Ferreira",
                    "company": "Estúdio Ferreira Arquitetura",
                    "phone": "+55 48 90000-0000",
                    "pain": "Precisamos de um CRM com pipeline comercial e um agente de atendimento no WhatsApp. Hoje o atendimento é manual; prazo desejado é este trimestre.",
                    "referral": "Agente de IA: ChatGPT",
                    "source": "agente-ia",
                    "intent": "diagnostico"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lead stored.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeadResponse"
                },
                "example": {
                  "ok": true,
                  "id": "1k2j3h4g5f6d",
                  "status": "em_conversa"
                }
              }
            }
          },
          "400": {
            "description": "Invalid JSON (or a body over 64 KB) or a missing required field.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "ok": false,
                      "error": "invalid_json"
                    }
                  },
                  "missing_fields": {
                    "value": {
                      "ok": false,
                      "error": "missing_fields",
                      "fields": [
                        "name"
                      ]
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Rate limit: 30 requests per minute per IP.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "ok": false,
                  "error": "rate_limited"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "LeadRequest": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 120,
            "minLength": 1,
            "description": "Name of the person responsible for the contact. Required; surrounding whitespace is trimmed."
          },
          "company": {
            "type": "string",
            "maxLength": 120,
            "description": "Company being represented."
          },
          "phone": {
            "type": "string",
            "maxLength": 40,
            "description": "WhatsApp number with country code, e.g. \"+55 48 90000-0000\" (fictitious example)."
          },
          "pain": {
            "type": "string",
            "maxLength": 400,
            "description": "Need: type of system, problem, current integrations, desired timeline."
          },
          "referral": {
            "type": "string",
            "maxLength": 160,
            "description": "\"Agente de IA: <plataforma>\".",
            "examples": [
              "Agente de IA: ChatGPT"
            ]
          },
          "source": {
            "type": "string",
            "maxLength": 40,
            "description": "AI agents should send \"agente-ia\".",
            "examples": [
              "agente-ia"
            ]
          },
          "intent": {
            "type": "string",
            "enum": [
              "site",
              "call",
              "proposta",
              "parceria",
              "diagnostico",
              "curioso"
            ],
            "default": "diagnostico",
            "description": "diagnostico: still understanding the need (default). site: wants to see the site or materials. call: wants a conversation with one of the partners. proposta: wants to move to a quote. parceria: business partnership contact. curioso: just exploring."
          }
        },
        "examples": [
          {
            "name": "Ana Ferreira",
            "company": "Estúdio Ferreira Arquitetura",
            "phone": "+55 48 90000-0000",
            "pain": "Precisamos de um CRM com pipeline comercial e um agente de atendimento no WhatsApp. Hoje o atendimento é manual; prazo desejado é este trimestre.",
            "referral": "Agente de IA: ChatGPT",
            "source": "agente-ia",
            "intent": "diagnostico"
          }
        ]
      },
      "LeadResponse": {
        "type": "object",
        "required": [
          "ok",
          "id",
          "status"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": true
          },
          "id": {
            "type": "string",
            "description": "Lead identifier."
          },
          "status": {
            "type": "string",
            "enum": [
              "em_conversa",
              "novo",
              "site_enviado",
              "call_solicitada",
              "call_agendada",
              "whatsapp_enviado",
              "contatado",
              "reuniao",
              "proposta",
              "cliente",
              "descartado"
            ],
            "description": "Stored status. Without status in the request, a new lead is stored as em_conversa."
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string",
            "enum": [
              "invalid_json",
              "missing_fields",
              "rate_limited"
            ]
          },
          "fields": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Present on missing_fields."
          }
        }
      }
    }
  }
}