{
  "openapi": "3.1.0",
  "info": {
    "title": "Cicini Public API",
    "version": "1.0.0",
    "description": "Read-only Public API v1 for organization data. Authenticate with an organization API key (`cic_test_…` or `cic_live_…`). Current operations: list customers, list appointments. Dashboard/admin routes are not part of this contract. API key management requires Professional+ (plan-core `apiAccess`). Developer guides: https://docs.cicini.com (Mintlify; source developer-docs/).",
    "contact": {
      "name": "Cicini",
      "url": "https://cicini.com"
    }
  },
  "servers": [
    {
      "url": "https://cicini.com",
      "description": "Production"
    },
    {
      "url": "http://localhost:3000",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "Customers",
      "description": "Customer directory (read-only)"
    },
    {
      "name": "Appointments",
      "description": "Appointments / reservations (read-only)"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API Key",
        "description": "Organization API key. Prefix with `Bearer `. Test keys start with `cic_test_`; live keys with `cic_live_`."
      }
    },
    "schemas": {},
    "parameters": {}
  },
  "paths": {
    "/api/public/v1/customers": {
      "get": {
        "operationId": "listCustomers",
        "summary": "List customers",
        "description": "Returns a paginated list of active customers for the organization associated with the API key.",
        "tags": ["Customers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "description": "Max items to return (1–100). Default: 50.",
              "example": 50
            },
            "required": false,
            "description": "Max items to return (1–100). Default: 50.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": ["integer", "null"],
              "minimum": 0,
              "description": "Number of items to skip. Default: 0.",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip. Default: 0.",
            "name": "offset",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated customer list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "Customer id"
                          },
                          "supportId": {
                            "type": "string"
                          },
                          "firstName": {
                            "type": "string"
                          },
                          "lastName": {
                            "type": "string"
                          },
                          "displayName": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string",
                            "format": "email"
                          },
                          "phone": {
                            "type": "string"
                          },
                          "primaryPhone": {
                            "type": "string"
                          },
                          "secondaryPhone": {
                            "type": "string"
                          },
                          "preferredContactMethod": {
                            "type": "string"
                          },
                          "dateOfBirth": {
                            "type": "string"
                          },
                          "gender": {
                            "type": "string"
                          },
                          "notes": {
                            "type": "string"
                          },
                          "marketingConsent": {
                            "type": "boolean"
                          },
                          "addressLine1": {
                            "type": "string"
                          },
                          "addressLine2": {
                            "type": "string"
                          },
                          "city": {
                            "type": "string"
                          },
                          "region": {
                            "type": "string"
                          },
                          "postalCode": {
                            "type": "string"
                          },
                          "country": {
                            "type": "string"
                          },
                          "preferredStaffId": {
                            "type": "string"
                          },
                          "isActive": {
                            "type": "boolean"
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "updatedAt": {
                            "type": "string"
                          }
                        },
                        "required": ["id", "firstName", "lastName", "displayName"]
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      },
                      "required": ["limit", "offset", "total", "hasMore"]
                    }
                  },
                  "required": ["data", "pagination"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      }
    },
    "/api/public/v1/appointments": {
      "get": {
        "operationId": "listAppointments",
        "summary": "List appointments",
        "description": "Returns a paginated list of active appointments for the organization associated with the API key. Supports status, customer, staff, and date filters.",
        "tags": ["Appointments"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "description": "Max items to return (1–100). Default: 50.",
              "example": 50
            },
            "required": false,
            "description": "Max items to return (1–100). Default: 50.",
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": ["integer", "null"],
              "minimum": 0,
              "description": "Number of items to skip. Default: 0.",
              "example": 0
            },
            "required": false,
            "description": "Number of items to skip. Default: 0.",
            "name": "offset",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "enum": ["scheduled", "confirmed", "checked_in", "no_show", "cancelled", "completed"],
              "description": "Filter by appointment status."
            },
            "required": false,
            "description": "Filter by appointment status.",
            "name": "status",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by customer id."
            },
            "required": false,
            "description": "Filter by customer id.",
            "name": "customerId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "description": "Filter by staff id."
            },
            "required": false,
            "description": "Filter by staff id.",
            "name": "staffId",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive lower bound (ISO-8601) on start time."
            },
            "required": false,
            "description": "Inclusive lower bound (ISO-8601) on start time.",
            "name": "startDate",
            "in": "query"
          },
          {
            "schema": {
              "type": "string",
              "format": "date-time",
              "description": "Inclusive upper bound (ISO-8601) on start time."
            },
            "required": false,
            "description": "Inclusive upper bound (ISO-8601) on start time.",
            "name": "endDate",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated appointment list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "orgId": {
                            "type": "string"
                          },
                          "customerId": {
                            "type": "string"
                          },
                          "staffId": {
                            "type": "string"
                          },
                          "serviceId": {
                            "type": "string"
                          },
                          "start": {
                            "type": "string",
                            "description": "ISO-8601 start time"
                          },
                          "end": {
                            "type": "string",
                            "description": "ISO-8601 end time"
                          },
                          "status": {
                            "type": "string"
                          },
                          "locationType": {
                            "type": "string"
                          },
                          "resourceId": {
                            "type": "string"
                          },
                          "priceCents": {
                            "type": "integer"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "note": {
                            "type": "string"
                          },
                          "paymentStatus": {
                            "type": "string"
                          },
                          "amountPaidCents": {
                            "type": ["integer", "null"]
                          },
                          "paymentKind": {
                            "type": ["string", "null"]
                          },
                          "paymentId": {
                            "type": ["string", "null"]
                          },
                          "invoiceId": {
                            "type": ["string", "null"]
                          },
                          "requiresPayment": {
                            "type": "boolean"
                          },
                          "confirmedAfterPayment": {
                            "type": "boolean"
                          },
                          "dayKey": {
                            "type": "string"
                          },
                          "createdAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "string",
                                "format": "date-time"
                              }
                            ]
                          },
                          "updatedAt": {
                            "anyOf": [
                              {
                                "type": "string"
                              },
                              {
                                "type": "string",
                                "format": "date-time"
                              }
                            ]
                          }
                        },
                        "required": ["id", "start", "end"]
                      }
                    },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        },
                        "hasMore": {
                          "type": "boolean"
                        }
                      },
                      "required": ["limit", "offset", "total", "hasMore"]
                    }
                  },
                  "required": ["data", "pagination"]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "500": {
            "description": "Internal server error",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "details": {}
                  },
                  "required": ["error"]
                }
              }
            }
          }
        }
      }
    }
  },
  "webhooks": {}
}