{
  "openapi": "3.1.0",
  "info": {
    "title": "Conflicool Agent Booking & Availability API",
    "description": "API for AI assistants and autonomous agents to retrieve orientation timeslots and schedule free calls with accredited CFM mediators on behalf of citizens and businesses in Belgium.",
    "version": "1.1.0"
  },
  "servers": [
    {
      "url": "https://conflicool.org",
      "description": "Conflicool Production Edge"
    }
  ],
  "paths": {
    "/api/v1/agent/timeslots": {
      "get": {
        "operationId": "getAvailableTimeslots",
        "summary": "Retrieve available appointment dates and timeslots for orientation calls",
        "description": "Returns the upcoming business days (Mon-Fri) and available timeslots (16:00, 16:30, 17:00, 17:30 Brussels time) so the AI assistant can show real appointment options to the user before booking.",
        "parameters": [
          {
            "name": "lang",
            "in": "query",
            "required": false,
            "description": "Language for day/month names ('fr', 'nl', 'de', 'en'). Defaults to 'fr'.",
            "schema": {
              "type": "string",
              "enum": [
                "fr",
                "nl",
                "de",
                "en"
              ],
              "default": "fr"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of upcoming business days to return (1-14). Defaults to 7.",
            "schema": {
              "type": "integer",
              "default": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Available appointment options retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "timezone": {
                      "type": "string",
                      "example": "Europe/Brussels (CET/CEST)"
                    },
                    "duration": {
                      "type": "string",
                      "example": "30 minutes"
                    },
                    "cost": {
                      "type": "string",
                      "example": "Free"
                    },
                    "available_days": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "date": {
                            "type": "string",
                            "format": "date",
                            "example": "2026-10-27"
                          },
                          "weekday": {
                            "type": "string",
                            "example": "Mardi"
                          },
                          "formatted": {
                            "type": "string",
                            "example": "27 oct."
                          },
                          "is_today": {
                            "type": "boolean"
                          },
                          "is_tomorrow": {
                            "type": "boolean"
                          },
                          "available_times": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "example": "16:30"
                            }
                          }
                        }
                      }
                    },
                    "instructions_for_assistant": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/agent/book-call": {
      "post": {
        "operationId": "bookOrientationCall",
        "summary": "Book a free dispute orientation call on behalf of a user (Requires Prior User Confirmation)",
        "description": "Creates a confidential dispute case with Conflicool ASBL and schedules the orientation intake call. WORKFLOW REQUIREMENT: 1) Obtain the user's name & email, 2) Retrieve available date options using getAvailableTimeslots and show 2-3 options to the user, 3) Summarize the conflict information, and 4) Present the complete draft to the user and obtain their explicit confirmation before calling this endpoint.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "description",
                  "preferred_date",
                  "preferred_time"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The user's full name (e.g., 'Jean Dupont')"
                  },
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "The user's email address to receive the calendar invite (.ics) and confirmation"
                  },
                  "phone": {
                    "type": "string",
                    "description": "The user's phone number (optional if email is provided, e.g., '+32 470 12 34 56')"
                  },
                  "description": {
                    "type": "string",
                    "description": "A summary of the conflict situation (e.g., 'Dispute with landlord regarding unpaid heating repairs and security deposit withholding in Brussels')"
                  },
                  "preferred_date": {
                    "type": "string",
                    "format": "date",
                    "description": "The chosen appointment date in YYYY-MM-DD format (selected from getAvailableTimeslots)"
                  },
                  "preferred_time": {
                    "type": "string",
                    "enum": [
                      "16:00",
                      "16:30",
                      "17:00",
                      "17:30"
                    ],
                    "description": "The chosen timeslot (e.g., '16:30')"
                  },
                  "language": {
                    "type": "string",
                    "enum": [
                      "fr",
                      "nl",
                      "de",
                      "en"
                    ],
                    "description": "Preferred language for communication (defaults to 'fr')"
                  },
                  "country": {
                    "type": "string",
                    "enum": [
                      "BE",
                      "NL",
                      "DE",
                      "FR",
                      "LU"
                    ],
                    "default": "BE",
                    "description": "Country jurisdiction"
                  },
                  "agent_client": {
                    "type": "string",
                    "description": "The name of the AI assistant submitting the booking (e.g. 'ChatGPT', 'Perplexity', 'Claude')"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Call successfully scheduled",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "confirmed"
                    },
                    "case_code": {
                      "type": "string",
                      "example": "CF-8421"
                    },
                    "message": {
                      "type": "string",
                      "example": "Orientation call successfully scheduled."
                    },
                    "email_confirmation_sent": {
                      "type": "boolean",
                      "example": true
                    },
                    "email_recipient": {
                      "type": "string",
                      "example": "jean.dupont@example.com"
                    },
                    "scheduled_call": {
                      "type": "object",
                      "properties": {
                        "date": {
                          "type": "string",
                          "example": "2026-10-28"
                        },
                        "time": {
                          "type": "string",
                          "example": "16:30"
                        },
                        "type": {
                          "type": "string",
                          "example": "Confidential Orientation Intake"
                        }
                      }
                    },
                    "confirmation_sent_to": {
                      "type": "string",
                      "example": "jean.dupont@example.com"
                    },
                    "next_steps": {
                      "type": "string",
                      "example": "A calendar invite (.ics) and confirmation email have been sent."
                    },
                    "instructions_for_assistant": {
                      "type": "string",
                      "example": "Explicitly inform the user that a confirmation email with a calendar invite (.ics) has been sent to their email address."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation Error or missing contact info"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        }
      }
    }
  }
}