{
  "openapi": "3.0.3",
  "info": {
    "title": "DooLight API",
    "version": "1.0.0",
    "description": "API gratuite et sans clé pour créer des calendriers de disponibilités et y répondre. Le hash du calendrier fait office de secret (comme dans le lien partagé). Voir aussi https://doolight.org/llms.txt Serveur MCP distant : https://doolight.org/api/mcp (voir https://doolight.org/ia.html)."
  },
  "servers": [
    {
      "url": "https://doolight.org/api/v1"
    }
  ],
  "paths": {
    "/calendars": {
      "post": {
        "operationId": "createCalendar",
        "summary": "Crée un calendrier",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCalendar"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Calendrier créé",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Created"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/calendars/{hash}": {
      "get": {
        "operationId": "getCalendar",
        "summary": "Lit un calendrier, ses participants et ses meilleurs créneaux",
        "parameters": [
          {
            "$ref": "#/components/parameters/Hash"
          }
        ],
        "responses": {
          "200": {
            "description": "Le calendrier",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Calendar"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/calendars/{hash}/best-slots": {
      "get": {
        "operationId": "getBestSlots",
        "summary": "Créneaux où le plus de participants sont disponibles",
        "parameters": [
          {
            "$ref": "#/components/parameters/Hash"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 5
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Meilleurs créneaux",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "hash": {
                      "type": "string"
                    },
                    "participants_count": {
                      "type": "integer"
                    },
                    "best_slots": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BestSlot"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/calendars/{hash}/participants/{name}": {
      "put": {
        "operationId": "setParticipantAvailability",
        "summary": "Crée ou remplace les disponibilités d'un participant",
        "description": "Par défaut remplace TOUTES les disponibilités du participant ; utilisez `mode: add` ou `remove` pour les modifier sans tout effacer. Répond 403 si le participant a vérouillé son calendrier par un code.",
        "parameters": [
          {
            "$ref": "#/components/parameters/Hash"
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Nom du participant (encodé dans l'URL). Préfixez par 🤖 pour un participant IA."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetAvailability"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Participant enregistré",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "participant": {
                      "$ref": "#/components/schemas/Participant"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/ai/create": {
      "get": {
        "operationId": "createCalendarGet",
        "summary": "Crée un calendrier en deux temps (GET, pour les IA qui ne savent que visiter des URL)",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "days",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Liste séparée par des virgules, ex. sam.,dim."
          },
          {
            "name": "slots",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Liste séparée par des virgules, ex. Midi,Soir"
          },
          {
            "name": "poll",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "0",
                "1"
              ]
            }
          },
          {
            "name": "creator",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "color",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Jeton fourni par confirm_url (ne pas inventer)."
          }
        ],
        "responses": {
          "201": {
            "description": "Calendrier créé",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Created"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        },
        "description": "Sans `token` : ne crée RIEN et renvoie `status: preview` avec une `confirm_url` (jeton signé, ~1 h). Visiter `confirm_url` crée le calendrier et renvoie `share_url`. N'agissez qu'à la demande d'un humain."
      }
    },
    "/ai/set": {
      "get": {
        "operationId": "setParticipantAvailabilityGet",
        "summary": "Remplace les disponibilités d'un participant (GET)",
        "parameters": [
          {
            "name": "hash",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "name",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "week",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Lundi jj/mm/aaaa ou sondage"
          },
          {
            "name": "cases",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Cases séparées par des virgules, ex. sam.-Soir,dim.-Soir"
          },
          {
            "name": "weeks",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Alternative : JSON [{\"week\":\"..\",\"selectedCases\":[..]}]"
          },
          {
            "name": "color",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "mode",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "replace",
                "add",
                "remove"
              ]
            },
            "description": "replace (défaut) remplace tout ; add ajoute ; remove retire."
          }
        ],
        "responses": {
          "200": {
            "description": "Participant enregistré"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "422": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/ai": {
      "get": {
        "operationId": "aiGuide",
        "summary": "Guide JSON du protocole à respecter par les IA",
        "responses": {
          "200": {
            "description": "Guide"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "Hash": {
        "name": "hash",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "Identifiant du calendrier (le paramètre `cal` du lien partagé)."
      }
    },
    "responses": {
      "Error": {
        "description": "Erreur",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "CreateCalendar": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "maxLength": 200
          },
          "days": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Colonnes. Par défaut lun. mar. mer. jeu. ven. sam. dim."
          },
          "slots": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Lignes. Par défaut Matin, Midi, Aprem, Soir."
          },
          "poll": {
            "type": "boolean",
            "description": "Mode sondage (sans dates) : `week` vaut alors \"sondage\"."
          },
          "creator": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string"
              },
              "color": {
                "type": "string",
                "example": "#1FF012"
              }
            }
          }
        }
      },
      "Created": {
        "type": "object",
        "properties": {
          "hash": {
            "type": "string"
          },
          "share_url": {
            "type": "string",
            "description": "Lien à donner aux humains."
          },
          "calendar": {
            "$ref": "#/components/schemas/Calendar"
          }
        }
      },
      "Calendar": {
        "type": "object",
        "properties": {
          "hash": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "share_url": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "calendar",
              "poll"
            ]
          },
          "days": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "slots": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "case_format": {
            "type": "string"
          },
          "week_hint": {
            "type": "string"
          },
          "anonymous": {
            "type": "boolean"
          },
          "participants": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Participant"
            }
          },
          "best_slots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BestSlot"
            }
          }
        }
      },
      "Participant": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "color": {
            "type": "string"
          },
          "locked": {
            "type": "boolean"
          },
          "weeks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Week"
            }
          }
        }
      },
      "Week": {
        "type": "object",
        "required": [
          "week",
          "selectedCases"
        ],
        "properties": {
          "week": {
            "type": "string",
            "description": "Lundi de la semaine au format jj/mm/aaaa, ou \"sondage\".",
            "example": "16/11/2026"
          },
          "selectedCases": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Cases `<jour>-<créneau>`.",
            "example": [
              "lun.-Matin",
              "mar.-Midi"
            ]
          }
        }
      },
      "SetAvailability": {
        "type": "object",
        "required": [
          "weeks"
        ],
        "properties": {
          "color": {
            "type": "string",
            "example": "#1FF012"
          },
          "weeks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Week"
            }
          },
          "mode": {
            "type": "string",
            "enum": [
              "replace",
              "add",
              "remove"
            ],
            "default": "replace",
            "description": "replace remplace tout ; add ajoute ces cases ; remove les retire."
          }
        }
      },
      "BestSlot": {
        "type": "object",
        "properties": {
          "week": {
            "type": "string"
          },
          "day": {
            "type": "string"
          },
          "slot": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Absent si les réponses sont anonymes."
          }
        }
      }
    }
  }
}
