{
  "openapi": "3.1.0",
  "info": {
    "title": "Visit Arewa REST API",
    "version": "1.0.0",
    "description": "Production REST API for Visit Arewa web platform and upcoming mobile apps (iOS & Android). Features full content discovery, creator submissions, event ticketing, QR code gate verification, and ambassador management.",
    "contact": {
      "name": "Veyrix Technologies",
      "url": "https://visitarewa.com",
      "email": "support@visitarewa.com"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3000/api/v1",
      "description": "Local Development Server"
    },
    {
      "url": "https://visitarewa.com/api/v1",
      "description": "Production Edge CDN"
    }
  ],
  "tags": [
    { "name": "Destinations", "description": "Tourist sites, natural wonders, and cultural landmarks." },
    { "name": "Cuisines", "description": "Traditional Northern Nigerian dishes, recipes, and food spots." },
    { "name": "Events", "description": "Festivals, durbars, exhibitions, and ticket bookings." },
    { "name": "Crafts", "description": "Living heritage, traditional pottery, leatherwork, and crafts." },
    { "name": "Stories", "description": "In-depth editorial articles, field stories, and cultural lore." },
    { "name": "Languages", "description": "Arewa languages, dialects, origins, and audio phrases." },
    { "name": "People", "description": "Notable icons, scholars, leaders, and cultural figures." },
    { "name": "Ambassadors", "description": "Creator network, photographer profiles, and application intake." },
    { "name": "Submissions", "description": "Creator Studio publications and user submissions." },
    { "name": "Payments & Verification", "description": "Paystack verification and QR gate scanning." },
    { "name": "Discovery", "description": "Universal multi-entity search and geo-tagged map data." },
    { "name": "System", "description": "API health checks and platform status." }
  ],
  "paths": {
    "/destinations": {
      "get": {
        "tags": ["Destinations"],
        "summary": "List all destinations",
        "description": "Retrieve destinations with optional filtering by region, state, or search keyword.",
        "parameters": [
          { "name": "region", "in": "query", "schema": { "type": "string" }, "description": "Filter by region (e.g. North-West, North-Central, North-East)" },
          { "name": "state", "in": "query", "schema": { "type": "string" }, "description": "Filter by Nigerian State (e.g. Kano, Kaduna, Niger)" },
          { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "Keyword search across title and description" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Maximum number of records to return" }
        ],
        "responses": {
          "200": {
            "description": "List of destinations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestinationListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/destinations/{slug}": {
      "get": {
        "tags": ["Destinations"],
        "summary": "Get destination by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Unique destination slug (e.g. zuma-rock, kajuru-castle)" }
        ],
        "responses": {
          "200": {
            "description": "Destination detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DestinationDetailResponse"
                }
              }
            }
          },
          "404": { "description": "Destination not found" }
        }
      }
    },
    "/events": {
      "get": {
        "tags": ["Events"],
        "summary": "List events and festivals",
        "parameters": [
          { "name": "category", "in": "query", "schema": { "type": "string" }, "description": "Filter by category (e.g. Festival, Durbar, Arts)" },
          { "name": "upcoming", "in": "query", "schema": { "type": "boolean" }, "description": "Filter to only future upcoming events" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } }
        ],
        "responses": {
          "200": {
            "description": "List of events",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/events/{slug}": {
      "get": {
        "tags": ["Events"],
        "summary": "Get event by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Event detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventDetailResponse"
                }
              }
            }
          },
          "404": { "description": "Event not found" }
        }
      }
    },
    "/events/register": {
      "post": {
        "tags": ["Events"],
        "summary": "Register / Book an event ticket",
        "description": "Book a free or paid ticket for a cultural event or festival.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventRegistrationInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registration created successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EventRegistrationResponse"
                }
              }
            }
          },
          "400": { "description": "Missing required fields or invalid ticket tier" }
        }
      }
    },
    "/cuisines": {
      "get": {
        "tags": ["Cuisines"],
        "summary": "List traditional cuisines and recipes",
        "responses": {
          "200": {
            "description": "List of culinary items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CuisineListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/cuisines/{slug}": {
      "get": {
        "tags": ["Cuisines"],
        "summary": "Get cuisine by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Cuisine detail" },
          "404": { "description": "Cuisine not found" }
        }
      }
    },
    "/crafts": {
      "get": {
        "tags": ["Crafts"],
        "summary": "List traditional crafts and living heritage",
        "responses": {
          "200": {
            "description": "List of crafts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CraftListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/crafts/{slug}": {
      "get": {
        "tags": ["Crafts"],
        "summary": "Get craft by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Craft detail" },
          "404": { "description": "Craft not found" }
        }
      }
    },
    "/crafts/submit": {
      "post": {
        "tags": ["Crafts"],
        "summary": "Submit a cultural craft for curation",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CraftSubmissionInput"
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Craft submitted successfully for editorial review" },
          "400": { "description": "Validation error" }
        }
      }
    },
    "/stories": {
      "get": {
        "tags": ["Stories"],
        "summary": "List field stories and editorial articles",
        "responses": {
          "200": { "description": "List of stories" }
        }
      }
    },
    "/stories/{slug}": {
      "get": {
        "tags": ["Stories"],
        "summary": "Get field story by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Story detail" },
          "404": { "description": "Story not found" }
        }
      }
    },
    "/languages": {
      "get": {
        "tags": ["Languages"],
        "summary": "List Northern Nigerian languages",
        "responses": {
          "200": { "description": "List of languages" }
        }
      }
    },
    "/languages/{slug}": {
      "get": {
        "tags": ["Languages"],
        "summary": "Get language details and phrases by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Language detail" },
          "404": { "description": "Language not found" }
        }
      }
    },
    "/people": {
      "get": {
        "tags": ["People"],
        "summary": "List Arewa icons, scholars, and leaders",
        "responses": {
          "200": { "description": "List of people" }
        }
      }
    },
    "/people/{slug}": {
      "get": {
        "tags": ["People"],
        "summary": "Get person biography by slug",
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Person biography" },
          "404": { "description": "Person not found" }
        }
      }
    },
    "/ambassadors": {
      "get": {
        "tags": ["Ambassadors"],
        "summary": "List cultural ambassadors and explorers",
        "responses": {
          "200": { "description": "List of ambassadors" }
        }
      }
    },
    "/ambassadors/apply": {
      "post": {
        "tags": ["Ambassadors"],
        "summary": "Apply to become a Cultural Ambassador",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AmbassadorApplicationInput"
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Application submitted for editorial review" },
          "400": { "description": "Missing required fields" }
        }
      }
    },
    "/submissions": {
      "get": {
        "tags": ["Submissions"],
        "summary": "List creator publications",
        "responses": {
          "200": { "description": "List of publications" }
        }
      }
    },
    "/submissions/{id}": {
      "get": {
        "tags": ["Submissions"],
        "summary": "Get submission by ID",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Submission details" },
          "404": { "description": "Submission not found" }
        }
      },
      "put": {
        "tags": ["Submissions"],
        "summary": "Update an existing submission",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Submission updated" }
        }
      },
      "delete": {
        "tags": ["Submissions"],
        "summary": "Delete a submission",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Submission deleted" }
        }
      }
    },
    "/payments/verify": {
      "post": {
        "tags": ["Payments & Verification"],
        "summary": "Verify Paystack payment reference",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["reference"],
                "properties": {
                  "reference": { "type": "string", "example": "pay_98a7sd98fasd" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Payment verification result" },
          "400": { "description": "Missing reference or verification failed" }
        }
      }
    },
    "/tickets/{code}": {
      "get": {
        "tags": ["Payments & Verification"],
        "summary": "Gate check ticket QR code",
        "description": "Scans and validates an attendee's QR ticket code at festival gates.",
        "parameters": [
          { "name": "code", "in": "path", "required": true, "schema": { "type": "string" }, "example": "AREWA-EVT-92841" }
        ],
        "responses": {
          "200": {
            "description": "Ticket status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TicketCheckResponse"
                }
              }
            }
          },
          "404": { "description": "Ticket code invalid" }
        }
      }
    },
    "/search": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Universal search across all content",
        "parameters": [
          { "name": "q", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Search query keyword" }
        ],
        "responses": {
          "200": { "description": "Search results partitioned by category" }
        }
      }
    },
    "/map": {
      "get": {
        "tags": ["Discovery"],
        "summary": "Retrieve geo-tagged coordinates for interactive map",
        "responses": {
          "200": { "description": "Array of pinned geo-coordinates" }
        }
      }
    },
    "/health": {
      "get": {
        "tags": ["System"],
        "summary": "Service uptime health check",
        "responses": {
          "200": {
            "description": "Service healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": { "type": "string", "example": "ok" },
                    "timestamp": { "type": "string", "example": "2026-09-26T17:00:00.000Z" },
                    "environment": { "type": "string", "example": "production" }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Destination": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "slug": { "type": "string", "example": "zuma-rock" },
          "name": { "type": "string", "example": "Zuma Rock" },
          "state": { "type": "string", "example": "Niger" },
          "region": { "type": "string", "example": "North-Central" },
          "category": { "type": "string", "example": "Natural Wonder" },
          "image": { "type": "string", "example": "https://res.cloudinary.com/.../zuma.webp" },
          "shortDescription": { "type": "string" },
          "fullDescription": { "type": "string" },
          "coordinates": { "type": "string", "example": "9.1200° N, 7.2500° E" },
          "highlights": { "type": "array", "items": { "type": "string" } }
        }
      },
      "DestinationListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/Destination" } },
          "meta": { "type": "object", "properties": { "count": { "type": "integer" } } }
        }
      },
      "DestinationDetailResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": { "$ref": "#/components/schemas/Destination" }
        }
      },
      "EventRegistrationInput": {
        "type": "object",
        "required": ["eventId", "name", "email"],
        "properties": {
          "eventId": { "type": "string", "example": "argungu-fishing-festival" },
          "name": { "type": "string", "example": "Aminu Bello" },
          "email": { "type": "string", "example": "aminu@example.com" },
          "phone": { "type": "string", "example": "+2348012345678" },
          "ticketType": { "type": "string", "enum": ["free", "paid"], "default": "free" },
          "ticketPrice": { "type": "number", "example": 5000 },
          "ticketCode": { "type": "string", "example": "AREWA-ARG-9821" }
        }
      },
      "EventRegistrationResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "ticketCode": { "type": "string", "example": "AREWA-ARG-9821" },
              "qrDataUrl": { "type": "string" },
              "status": { "type": "string", "example": "confirmed" }
            }
          }
        }
      },
      "CraftSubmissionInput": {
        "type": "object",
        "required": ["name", "category", "origin", "shortDescription", "image"],
        "properties": {
          "name": { "type": "string", "example": "Kofar Mata Indigo Dyeing" },
          "category": { "type": "string", "example": "Textile Craft" },
          "origin": { "type": "string", "example": "Kano City" },
          "shortDescription": { "type": "string" },
          "image": { "type": "string" },
          "tools": { "type": "array", "items": { "type": "string" } }
        }
      },
      "AmbassadorApplicationInput": {
        "type": "object",
        "required": ["name", "email", "role"],
        "properties": {
          "name": { "type": "string", "example": "Fatima Zahra" },
          "email": { "type": "string", "example": "fatima@example.com" },
          "role": { "type": "string", "enum": ["photographer", "writer", "researcher", "videographer"] },
          "portfolioLink": { "type": "string", "example": "https://instagram.com/arewaphotos" },
          "message": { "type": "string", "example": "I have documented cultural heritage in Zamfara and Katsina for 5 years." }
        }
      },
      "TicketCheckResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean", "example": true },
          "data": {
            "type": "object",
            "properties": {
              "valid": { "type": "boolean", "example": true },
              "attendeeName": { "type": "string", "example": "Aminu Bello" },
              "eventName": { "type": "string", "example": "Argungu International Fishing Festival" },
              "ticketType": { "type": "string", "example": "VIP Access" },
              "checkedIn": { "type": "boolean", "example": false }
            }
          }
        }
      },
      "EventListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "type": "object" } }
        }
      },
      "EventDetailResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "object" }
        }
      },
      "CuisineListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "type": "object" } }
        }
      },
      "CraftListResponse": {
        "type": "object",
        "properties": {
          "success": { "type": "boolean" },
          "data": { "type": "array", "items": { "type": "object" } }
        }
      }
    }
  }
}