{
  "openapi": "3.1.0",
  "info": {
    "title": "MonetizeGroup Facebook Group Marketplace API",
    "version": "1.0.0",
    "description": "Programmatic REST API and Autonomous Agent interface for Monetize Group (https://monetizegrouphq.com). Enables AI agents, growth marketers, and platform integrations to query verified Facebook communities, review flat-rate sponsorship pricing, book native feed placements, configure 24h pinned announcements and @everyone push notifications, verify token placements, and inspect fulfillment proof URLs.\n\n## Versioning policy\n\nThis API uses **URL-path versioning**. All current routes are implicitly v1 — the `/api/*` path prefix is equivalent to `/api/v1/*`. When a breaking change is introduced, a new path prefix (`/api/v2/*`) will be announced at least 90 days in advance via the `Deprecation` and `Sunset` response headers.\n\n- `API-Version: 1` — present on every API response to confirm the active version.\n- `Deprecation: <HTTP-date>` — set on deprecated endpoints; signals that the endpoint will stop accepting requests after the Sunset date.\n- `Sunset: <HTTP-date>` — the date after which a deprecated endpoint is removed. Example: `Sunset: Sat, 01 Jan 2028 00:00:00 GMT`.\n\nSee RFC 8594 for `Sunset` semantics and draft-ietf-httpapi-deprecation-header for `Deprecation`.\n\n## Rate limiting\n\nRequests are rate-limited to **1 000 requests per 15-minute window** per IP address. Every API response includes the following headers:\n\n| Header | Description |\n|---|---|\n| `RateLimit-Limit` | Maximum requests allowed per window |\n| `RateLimit-Remaining` | Requests remaining in the current window |\n| `RateLimit-Reset` | Unix timestamp when the window resets |\n| `X-RateLimit-Limit` | Legacy alias for `RateLimit-Limit` |\n| `X-RateLimit-Remaining` | Legacy alias for `RateLimit-Remaining` |\n| `X-RateLimit-Reset` | Legacy alias for `RateLimit-Reset` |\n\nWhen the limit is exceeded, the server responds with `429 Too Many Requests` and a `Retry-After` header specifying the number of seconds to wait.",
    "termsOfService": "https://monetizegrouphq.com/terms",
    "contact": {
      "name": "Monetize Group Developer Support",
      "url": "https://monetizegrouphq.com/developers",
      "email": "support@monetizegrouphq.com"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://monetizegrouphq.com/terms"
    },
    "x-api-version": "1",
    "x-versioning-strategy": "url-path",
    "x-sunset-policy": "90-day notice via Deprecation + Sunset headers before any breaking change"
  },
  "servers": [
    {
      "url": "https://monetizegrouphq.com/api",
      "description": "Production API server (v1)"
    }
  ],
  "tags": [
    {
      "name": "Groups",
      "description": "Discover verified Facebook communities, member demographics, and sponsorship rates"
    },
    {
      "name": "Orders",
      "description": "Book sponsored posts, select add-ons, and audit campaign delivery proof"
    },
    {
      "name": "User",
      "description": "Profile, prepaid wallet balances, and payout configurations"
    }
  ],
  "paths": {
    "/groups": {
      "get": {
        "tags": ["Groups"],
        "summary": "List and filter verified Facebook groups",
        "description": "Retrieve active Facebook groups available for sponsorship booking, filtered by category niche or owner ID.",
        "operationId": "listGroups",
        "parameters": [
          {
            "name": "owner_id",
            "in": "query",
            "required": false,
            "description": "Filter groups owned by a specific publisher user ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "niche",
            "in": "query",
            "required": false,
            "description": "Filter by community category niche (e.g. Technology, E-commerce, Crypto, Lifestyle)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Array of verified Facebook group listings",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Group"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": ["Groups"],
        "summary": "Register a new Facebook group listing",
        "description": "Submit a Facebook group for automated description token scanning and listing in the marketplace.",
        "operationId": "createGroup",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateGroupRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Group listing created with generated verification token",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Group"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/groups/{id}": {
      "get": {
        "tags": ["Groups"],
        "summary": "Get group listing details",
        "description": "Retrieve comprehensive details, rate card, and verification status for a specific group.",
        "operationId": "getGroupById",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the group listing",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Group listing details",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Group"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/orders": {
      "get": {
        "tags": ["Orders"],
        "summary": "List sponsorship campaign orders",
        "description": "Retrieve campaign orders where the authenticated user is either merchant (buyer) or group admin (seller).",
        "operationId": "listOrders",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Filter by role perspective ('buyer' or 'seller')",
            "schema": {
              "type": "string",
              "enum": ["buyer", "seller"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of campaign orders",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Order"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": ["Orders"],
        "summary": "Book a Facebook group sponsorship order",
        "description": "Initiate a sponsored post campaign booking with atomic prepaid balance deduction and 48-hour delivery escrow.",
        "operationId": "createOrder",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrderRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Order successfully booked and routed to group admin",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "tags": ["Orders"],
        "summary": "Get order status and fulfillment proof",
        "description": "Inspect real-time status of a campaign order, including 48-hour countdown, submitted Facebook permalink, and payout settlement.",
        "operationId": "getOrderById",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Order ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order details with live fulfillment tracking",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFoundError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/user/me": {
      "get": {
        "tags": ["User"],
        "summary": "Get authenticated user profile and balances",
        "description": "Retrieve current account information, prepaid wallet balance, and PayPal payout settings.",
        "operationId": "getProfile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "User profile data",
            "headers": {
              "$ref": "#/components/headers/ApiResponseHeaders"
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          },
          "429": {
            "$ref": "#/components/responses/RateLimitError"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "ApiResponseHeaders": {
        "description": "Standard headers present on every API response",
        "schema": {
          "type": "object",
          "properties": {
            "API-Version": {
              "schema": { "type": "string", "example": "1" },
              "description": "The active API major version."
            },
            "RateLimit-Limit": {
              "schema": { "type": "integer", "example": 1000 },
              "description": "Maximum requests allowed in the current window."
            },
            "RateLimit-Remaining": {
              "schema": { "type": "integer", "example": 999 },
              "description": "Requests remaining in the current window."
            },
            "RateLimit-Reset": {
              "schema": { "type": "integer", "example": 1700000900 },
              "description": "Unix timestamp when the rate-limit window resets."
            },
            "Deprecation": {
              "schema": { "type": "string", "example": "Mon, 01 Jan 2029 00:00:00 GMT" },
              "description": "Present only on deprecated endpoints. Date when the endpoint became deprecated."
            },
            "Sunset": {
              "schema": { "type": "string", "example": "Sat, 01 Jul 2029 00:00:00 GMT" },
              "description": "Present only on deprecated endpoints. Date after which the endpoint is removed."
            }
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT or Session Token",
        "description": "Provide session token via Cookie (better-auth.session_token) or Authorization: Bearer <token>"
      },
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API Key authentication for autonomous buying agents"
      }
    },
    "schemas": {
      "Group": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "group-1741234567"
          },
          "name": {
            "type": "string",
            "example": "Full-Stack Web Developers & Startups"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://facebook.com/groups/fullstackdevs"
          },
          "niche": {
            "type": "string",
            "example": "Tech & Web Development"
          },
          "member_count": {
            "type": "integer",
            "example": 48500
          },
          "base_price": {
            "type": "number",
            "example": 65.00
          },
          "addon_pinned_price": {
            "type": "number",
            "example": 15.00
          },
          "addon_tag_price": {
            "type": "number",
            "example": 20.00
          },
          "status": {
            "type": "string",
            "enum": ["pending", "verified", "rejected"],
            "example": "verified"
          },
          "verification_token": {
            "type": "string",
            "example": "SPONSOR-JSDEV99"
          }
        }
      },
      "CreateGroupRequest": {
        "type": "object",
        "required": ["name", "url", "niche", "member_count", "base_price"],
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "niche": {
            "type": "string"
          },
          "member_count": {
            "type": "integer"
          },
          "base_price": {
            "type": "number"
          },
          "addon_pinned_price": {
            "type": "number",
            "default": 15.00
          },
          "addon_tag_price": {
            "type": "number",
            "default": 20.00
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ord-88319"
          },
          "group_id": {
            "type": "string",
            "example": "group-1741234567"
          },
          "merchant_id": {
            "type": "string"
          },
          "total_price": {
            "type": "number",
            "example": 85.00
          },
          "status": {
            "type": "string",
            "enum": ["pending", "accepted", "completed", "cancelled", "disputed"],
            "example": "completed"
          },
          "post_copy": {
            "type": "string",
            "example": "Supercharge your deployment pipeline with our developer tools..."
          },
          "image_url": {
            "type": "string",
            "format": "uri"
          },
          "destination_url": {
            "type": "string",
            "format": "uri",
            "example": "https://example.com/?utm_source=fbgroup&utm_campaign=devs"
          },
          "is_pinned": {
            "type": "boolean",
            "example": true
          },
          "is_tagged": {
            "type": "boolean",
            "example": false
          },
          "live_post_url": {
            "type": "string",
            "format": "uri",
            "example": "https://facebook.com/groups/fullstackdevs/posts/9918237412"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CreateOrderRequest": {
        "type": "object",
        "required": ["group_id", "total_price", "post_copy"],
        "properties": {
          "group_id": {
            "type": "string"
          },
          "total_price": {
            "type": "number"
          },
          "post_copy": {
            "type": "string"
          },
          "image_url": {
            "type": "string"
          },
          "destination_url": {
            "type": "string"
          },
          "is_pinned": {
            "type": "boolean",
            "default": false
          },
          "is_tagged": {
            "type": "boolean",
            "default": false
          }
        }
      },
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "role": {
            "type": "string",
            "enum": ["user", "admin", "super_admin"]
          },
          "wallet_balance": {
            "type": "number",
            "example": 250.00
          },
          "payout_email": {
            "type": "string",
            "format": "email",
            "example": "payouts@creator.com"
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Structured error envelope. All API errors use this shape so agents can parse them without reading HTML.",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error identifier",
                "example": "NOT_FOUND",
                "enum": [
                  "UNAUTHORIZED",
                  "FORBIDDEN",
                  "NOT_FOUND",
                  "BAD_REQUEST",
                  "RATE_LIMITED",
                  "INTERNAL_ERROR"
                ]
              },
              "message": {
                "type": "string",
                "description": "Human-readable error description",
                "example": "Order not found."
              },
              "hint": {
                "type": "string",
                "description": "Optional resolution hint for agents",
                "example": "Check the ID and confirm the resource exists."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Link to developer documentation",
                "example": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      }
    },
    "responses": {
      "UnauthorizedError": {
        "description": "Authentication credentials are missing or invalid",
        "headers": {
          "API-Version": {
            "schema": { "type": "string" },
            "description": "Active API version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "UNAUTHORIZED",
                "message": "Authentication required. Provide a valid session cookie or Bearer token.",
                "docs": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      },
      "BadRequestError": {
        "description": "Invalid input parameters or insufficient balance",
        "headers": {
          "API-Version": {
            "schema": { "type": "string" },
            "description": "Active API version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "BAD_REQUEST",
                "message": "Missing required fields: name, url, niche.",
                "hint": "Include all required fields in the request body.",
                "docs": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      },
      "NotFoundError": {
        "description": "The requested resource was not found",
        "headers": {
          "API-Version": {
            "schema": { "type": "string" },
            "description": "Active API version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "NOT_FOUND",
                "message": "Order not found.",
                "hint": "Check the ID and confirm the resource exists.",
                "docs": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      },
      "RateLimitError": {
        "description": "Request rate limit exceeded",
        "headers": {
          "API-Version": {
            "schema": { "type": "string" },
            "description": "Active API version"
          },
          "Retry-After": {
            "schema": { "type": "integer", "example": 47 },
            "description": "Seconds to wait before retrying"
          },
          "RateLimit-Limit": {
            "schema": { "type": "integer", "example": 1000 },
            "description": "Maximum requests per window"
          },
          "RateLimit-Remaining": {
            "schema": { "type": "integer", "example": 0 },
            "description": "Requests remaining in current window"
          },
          "RateLimit-Reset": {
            "schema": { "type": "integer", "example": 1700000900 },
            "description": "Unix timestamp when the window resets"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "RATE_LIMITED",
                "message": "Rate limit exceeded. Try again after the Retry-After period.",
                "hint": "Reduce request frequency or contact support@monetizegrouphq.com to raise your limit.",
                "docs": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Unexpected server error",
        "headers": {
          "API-Version": {
            "schema": { "type": "string" },
            "description": "Active API version"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": {
                "code": "INTERNAL_ERROR",
                "message": "An unexpected error occurred. Please try again.",
                "docs": "https://monetizegrouphq.com/developers"
              }
            }
          }
        }
      }
    }
  }
}