{
  "openapi": "3.1.0",
  "info": {
    "title": "FlincByte API",
    "version": "1.0.0",
    "description": "Official public API for FlincByte - a custom software development company building MVPs, web/mobile applications, SaaS products, and enterprise software. Use these endpoints to submit project inquiries, query published case studies, explore open career roles, join product waitlists, and interact with developer resources.",
    "contact": {
      "name": "FlincByte Engineering & Support",
      "email": "contact@flincbyte.com",
      "url": "https://www.flincbyte.com/developers"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://www.flincbyte.com/terms-of-service"
    }
  },
  "servers": [
    {
      "url": "https://www.flincbyte.com",
      "description": "Production API Server"
    }
  ],
  "paths": {
    "/api/contact": {
      "post": {
        "operationId": "submitContactInquiry",
        "summary": "Submit a project inquiry or contact request",
        "description": "Sends a new client inquiry to the FlincByte engineering team. An intro call or technical scope review will follow within 24 hours.",
        "tags": [
          "Inquiries"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactSubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Inquiry successfully recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Thank you for reaching out!"
                    },
                    "id": {
                      "type": "string",
                      "example": "67ce19b489a19d20c3a81234"
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid JSON body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/waitlist": {
      "post": {
        "operationId": "joinProductWaitlist",
        "summary": "Join waitlist for FlincByte products (e.g., Society App)",
        "description": "Registers a user or society admin on the waitlist for early access to FlincByte digital products.",
        "tags": [
          "Products & Waitlist"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WaitlistSubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successfully added to waitlist",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Successfully joined waitlist"
                    },
                    "entry": {
                      "type": "object",
                      "properties": {
                        "_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "societyName": {
                          "type": "string"
                        },
                        "product": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "required": [
                    "success",
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid input or email already registered",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/newsletter": {
      "post": {
        "operationId": "subscribeNewsletter",
        "summary": "Subscribe to FlincByte engineering newsletter",
        "description": "Registers an email address for monthly software engineering insights and MVP case studies.",
        "tags": [
          "Newsletter"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "description": "Subscriber email address",
                    "example": "alex@example.com"
                  },
                  "source": {
                    "type": "string",
                    "description": "Opt-in source identifier",
                    "example": "developer-portal"
                  }
                },
                "required": [
                  "email"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Subscription recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Subscription saved"
                    },
                    "id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid email or request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/blogs": {
      "get": {
        "operationId": "getPublishedBlogs",
        "summary": "List published blog posts and technical guides",
        "description": "Fetches published blog articles with cursor-based pagination and keyword search.",
        "tags": [
          "Content"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of blog posts to return (1-50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Base64 pagination cursor from previous response",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "description": "Keyword filter across title, tags, and description",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of blog articles",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/BlogPost"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "items"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/projects": {
      "get": {
        "operationId": "getFeaturedProjects",
        "summary": "List featured case studies and portfolio projects",
        "description": "Retrieves client case studies, shipped MVPs, and architecture breakdowns.",
        "tags": [
          "Projects"
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Number of projects to return (1-50)",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Pagination cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of projects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ProjectItem"
                      }
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "items"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/careers": {
      "get": {
        "operationId": "getOpenRoles",
        "summary": "List open engineering and design career roles",
        "description": "Returns active remote job postings at FlincByte.",
        "tags": [
          "Careers"
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "Filter roles by open status ('open' or 'all')",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "open",
                "all"
              ],
              "default": "open"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of career opportunities",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/CareerRole"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ContactSubmissionRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "description": "Full name of the contact person",
            "example": "Sarah Jenkins"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Primary business email address",
            "example": "sarah@acme-ventures.com"
          },
          "phone": {
            "type": "string",
            "description": "Contact phone number with international country code",
            "example": "+1 415 555 2671"
          },
          "company": {
            "type": "string",
            "description": "Organization or startup name",
            "example": "Acme Ventures"
          },
          "budget": {
            "type": "string",
            "description": "Estimated budget bracket in USD",
            "enum": [
              "< $5k",
              "$5k - $10k",
              "$10k - $25k",
              "$25k - $50k",
              "$50k+"
            ],
            "example": "$10k - $25k"
          },
          "timeline": {
            "type": "string",
            "description": "Expected launch timeline",
            "enum": [
              "Urgent (< 1 month)",
              "1 - 3 months",
              "3 - 6 months",
              "Flexible"
            ],
            "example": "1 - 3 months"
          },
          "service": {
            "type": "string",
            "description": "Primary service required",
            "enum": [
              "Custom Web Development",
              "Mobile App Development",
              "Custom Software Engineering",
              "VAPT Cybersecurity",
              "MVP in 8 Weeks",
              "Other"
            ],
            "example": "Custom Web Development"
          },
          "message": {
            "type": "string",
            "minLength": 10,
            "description": "Detailed description of the product or requirements",
            "example": "We need a multi-tenant B2B SaaS dashboard built with Next.js and Stripe billing within 8 weeks."
          },
          "turnstileToken": {
            "type": "string",
            "description": "Cloudflare Turnstile verification token"
          },
          "newsletterOptIn": {
            "type": "boolean",
            "description": "Optional subscription to engineering updates",
            "default": false
          }
        },
        "required": [
          "name",
          "email",
          "message",
          "turnstileToken"
        ]
      },
      "WaitlistSubmissionRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Full name of applicant or society representative",
            "example": "Rajesh Patel"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "rajesh@greenacres.in"
          },
          "phone": {
            "type": "string",
            "example": "+91 98765 43210"
          },
          "societyName": {
            "type": "string",
            "description": "Housing society or organization name",
            "example": "Green Acres Residency"
          },
          "flats": {
            "type": "string",
            "description": "Approximate count of residential/commercial units",
            "example": "120 units"
          },
          "product": {
            "type": "string",
            "default": "society-app",
            "example": "society-app"
          }
        },
        "required": [
          "name",
          "email",
          "phone",
          "societyName",
          "flats"
        ]
      },
      "BlogPost": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string",
            "example": "66e1b..."
          },
          "title": {
            "type": "string",
            "example": "Building Production Next.js MVPs"
          },
          "slug": {
            "type": "string",
            "example": "building-production-nextjs-mvps"
          },
          "description": {
            "type": "string",
            "example": "Key architectural patterns for shipping scalable apps in 8 weeks."
          },
          "publishedAt": {
            "type": "string",
            "format": "date-time"
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Next.js",
              "React",
              "Architecture"
            ]
          },
          "author": {
            "type": "object",
            "properties": {
              "name": {
                "type": "string",
                "example": "FlincByte Team"
              }
            }
          }
        },
        "required": [
          "title",
          "slug",
          "description"
        ]
      },
      "ProjectItem": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "Global Logistics Tracking Platform"
          },
          "slug": {
            "type": "string",
            "example": "global-logistics-platform"
          },
          "summary": {
            "type": "string",
            "example": "Real-time fleet telematics and dispatcher portal."
          },
          "techStack": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Next.js",
              "TypeScript",
              "Node.js",
              "PostgreSQL"
            ]
          },
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Web App",
              "Fintech",
              "Enterprise"
            ]
          }
        },
        "required": [
          "title",
          "slug",
          "summary"
        ]
      },
      "CareerRole": {
        "type": "object",
        "properties": {
          "_id": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "Senior Full-Stack Engineer"
          },
          "slug": {
            "type": "string",
            "example": "senior-fullstack-engineer"
          },
          "department": {
            "type": "string",
            "example": "Engineering"
          },
          "location": {
            "type": "string",
            "example": "Remote (India)"
          },
          "type": {
            "type": "string",
            "example": "Full-time"
          },
          "isOpen": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "title",
          "slug",
          "isOpen"
        ]
      },
      "ApiErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error classification code",
                "example": "VALIDATION_ERROR"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error description",
                "example": "Validation error on submitted contact form fields."
              },
              "resolution": {
                "type": "string",
                "description": "Actionable remediation instructions for agents or developers",
                "example": "Check name (min 2 chars), valid email, and message (min 10 chars)."
              },
              "details": {
                "type": "object",
                "description": "Optional granular validation breakdown"
              }
            },
            "required": [
              "code",
              "message"
            ]
          },
          "message": {
            "type": "string",
            "description": "Backwards-compatible top-level message",
            "example": "Validation error on submitted contact form fields."
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}