{
    "openapi": "3.0.0",
    "info": {
        "title": "AVOCATS.CD Developer API",
        "description": "Documentation publique des endpoints Developer API destinés aux intégrations partenaires et agents IA.",
        "version": "1.1.0"
    },
    "servers": [
        {
            "url": "/api",
            "description": "API principale"
        }
    ],
    "paths": {
        "/v1/lawyers/search": {
            "get": {
                "tags": [
                    "Avocats"
                ],
                "summary": "Rechercher des avocats",
                "description": "Le filtre q est facultatif. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                "operationId": "eb2c654af53bb7014aedd034a4a7c8ce",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Recherche facultative. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "droit",
                            "nullable": true
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Nombre facultatif de résultats par page.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 15,
                            "maximum": 50,
                            "example": 15
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Résultats de recherche."
                    },
                    "401": {
                        "description": "Clé API invalide."
                    },
                    "403": {
                        "description": "Permission API insuffisante."
                    },
                    "429": {
                        "description": "Quota ou limite de débit dépassé."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/lawyers/{id}": {
            "get": {
                "tags": [
                    "Avocats"
                ],
                "summary": "Consulter le profil public d’un avocat",
                "operationId": "c19bffb8841fa783200aea367751c213",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Profil public de l’avocat."
                    },
                    "404": {
                        "description": "Avocat introuvable."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/lawyers/{id}/availability": {
            "get": {
                "tags": [
                    "Avocats"
                ],
                "summary": "Consulter les horaires publics d’un avocat",
                "operationId": "aa97fba7ce9e698a0c978753db91e9b0",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Horaires publics déclarés par l’avocat."
                    },
                    "404": {
                        "description": "Avocat introuvable."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/ai/lawyer-recommendations": {
            "post": {
                "tags": [
                    "Agents IA"
                ],
                "summary": "Obtenir des suggestions d’avocats à partir d’un contexte",
                "operationId": "aa7982d60e288fcb8e744ea915c86b10",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "query"
                                ],
                                "properties": {
                                    "query": {
                                        "type": "string"
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "default": 5,
                                        "maximum": 10
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Suggestions d’avocats."
                    },
                    "422": {
                        "description": "Paramètres invalides."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/legal-categories": {
            "get": {
                "tags": [
                    "Contenus juridiques"
                ],
                "summary": "Lister les catégories juridiques",
                "operationId": "ce3f17721026dd6fe1f59cf05e3603ba",
                "responses": {
                    "200": {
                        "description": "Liste des catégories juridiques."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/articles": {
            "get": {
                "tags": [
                    "Contenus juridiques"
                ],
                "summary": "Lister les articles juridiques",
                "description": "Le filtre q est facultatif. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                "operationId": "52b619b92914acbe223e0c9c2e695177",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Recherche facultative. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "droit",
                            "nullable": true
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Nombre facultatif de résultats par page.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 15,
                            "maximum": 50,
                            "example": 15
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Liste paginée des articles."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/articles/{id}": {
            "get": {
                "tags": [
                    "Contenus juridiques"
                ],
                "summary": "Consulter un article juridique",
                "operationId": "dff1e007cf774a4330f1fba59b51f193",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Article juridique."
                    },
                    "404": {
                        "description": "Article introuvable."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/legal-questions/search": {
            "get": {
                "tags": [
                    "Contenus juridiques"
                ],
                "summary": "Rechercher des questions juridiques publiques",
                "description": "Le filtre q est facultatif. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                "operationId": "030df33b01ceb3a761cf49b6f97daeb1",
                "parameters": [
                    {
                        "name": "q",
                        "in": "query",
                        "description": "Recherche facultative. Laissez ce paramètre vide ou désactivez-le dans Postman pour afficher tous les résultats.",
                        "required": false,
                        "schema": {
                            "type": "string",
                            "example": "droit",
                            "nullable": true
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "description": "Nombre facultatif de résultats par page.",
                        "required": false,
                        "schema": {
                            "type": "integer",
                            "default": 15,
                            "maximum": 50,
                            "example": 15
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Liste paginée des questions publiques."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/legal-questions/{id}": {
            "get": {
                "tags": [
                    "Contenus juridiques"
                ],
                "summary": "Consulter une question juridique publique",
                "operationId": "b76916dfb0193419a5e94f12fde26097",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Question et réponses publiques."
                    },
                    "404": {
                        "description": "Question publique introuvable."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/leads": {
            "post": {
                "tags": [
                    "Partenaires"
                ],
                "summary": "Créer un lead vers AVOCATS.CD",
                "operationId": "8e2c118c4d8523b658a54e79b7485804",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "question_text"
                                ],
                                "properties": {
                                    "question_text": {
                                        "type": "string"
                                    },
                                    "thematique_id": {
                                        "type": "integer"
                                    },
                                    "client_name": {
                                        "type": "string"
                                    },
                                    "client_email": {
                                        "type": "string",
                                        "format": "email"
                                    },
                                    "client_phone": {
                                        "type": "string"
                                    },
                                    "source_platform": {
                                        "type": "string"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Lead reçu."
                    },
                    "422": {
                        "description": "Paramètres invalides."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/analytics/events": {
            "post": {
                "tags": [
                    "Partenaires"
                ],
                "summary": "Enregistrer un événement analytics partenaire",
                "operationId": "ce576d3979565f543b04a1f17b760efd",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "event_name"
                                ],
                                "properties": {
                                    "event_name": {
                                        "type": "string"
                                    },
                                    "source_platform": {
                                        "type": "string"
                                    },
                                    "external_reference": {
                                        "type": "string"
                                    },
                                    "metadata": {
                                        "type": "object"
                                    },
                                    "occurred_at": {
                                        "type": "string",
                                        "format": "date-time"
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Événement enregistré."
                    },
                    "422": {
                        "description": "Paramètres invalides."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        },
        "/v1/ai/legal-context": {
            "post": {
                "tags": [
                    "Agents IA"
                ],
                "summary": "Obtenir un contexte juridique structuré pour un agent IA",
                "operationId": "6f75ec6d8835911925e73c0a21a5fa1e",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "required": [
                                    "query"
                                ],
                                "properties": {
                                    "query": {
                                        "type": "string"
                                    },
                                    "limit": {
                                        "type": "integer",
                                        "default": 5,
                                        "maximum": 10
                                    }
                                },
                                "type": "object"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Contexte juridique structuré."
                    },
                    "422": {
                        "description": "Paramètres invalides."
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ]
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "description": "Clé API développeur AVOCATS.CD.",
                "name": "X-API-Key",
                "in": "header"
            }
        }
    },
    "tags": [
        {
            "name": "Avocats"
        },
        {
            "name": "Contenus juridiques"
        },
        {
            "name": "Partenaires"
        },
        {
            "name": "Agents IA"
        }
    ]
}