{
  "openapi": "3.1.0",
  "info": {
    "title": "MemeFlow Connect — Partner Content Monetization & Publishing API",
    "version": "1.4.0",
    "summary": "REST API for external platforms, developers, and AI agents to publish content, provision browser-local partner delivery sessions, generate monetized Smart Links (/m/{slug}), and earn standard 80% of net Google AdSense revenue (with application-level negotiated options).",
    "description": "MemeFlow Connect allows external platforms to monetize their content (articles, breaking news, 48kHz studio audio, videos, memes, PDFs, and ZIP archives) via shareable Smart Links (/m/{slug}). Supports both session-scoped browser-local temporary partner delivery (with zero MemeFlow Storage bloat) and permanent multi-file creator posts. Rate limit: 120 requests/minute per application (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`). Idempotency (`Idempotency-Key` header or `idempotency_key` body field) is enforced on `POST /api/v1/posts`, `POST /api/v1/posts/temporary`, `POST /api/v1/partner/content`, `POST /api/v1/partner/content/resolve`, and `POST /api/v1/partner/action`.",
    "contact": {
      "name": "MemeFlow Developer Platform",
      "url": "https://creator-connect-earn.lovable.app/developers"
    }
  },
  "servers": [
    {
      "url": "https://creator-connect-earn.lovable.app",
      "description": "MemeFlow Production Server"
    }
  ],
  "security": [{ "BearerAuth": [] }, { "ApiKeyAuth": [] }],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Pass your MemeFlow API key as `Authorization: Bearer YOUR_MEMEFLOW_API_KEY`"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Pass your MemeFlow API key in the `x-api-key` or `x-memeflow-api-key` header"
      }
    },
    "parameters": {
      "IdempotencyKeyHeader": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Unique key (e.g., UUID v4) for safe retry replay over a 24-hour window. Reusing the same key with a different payload returns 409 IDEMPOTENCY_CONFLICT.",
        "schema": { "type": "string", "maxLength": 256 }
      }
    },
    "schemas": {
      "AudioMetadata": {
        "type": "object",
        "properties": {
          "isMultiTrack": { "type": "boolean" },
          "sampleRate": { "type": "integer", "example": 48000 },
          "bitrateKbps": { "type": "integer", "example": 320 },
          "bitDepth": { "type": "integer", "example": 24 },
          "channels": { "type": "integer", "example": 2 },
          "stemName": { "type": "string" },
          "waveformPeaks": { "type": "array", "items": { "type": "number" } }
        }
      },
      "MediaInputItem": {
        "type": "object",
        "required": ["media_url", "media_type", "file_name"],
        "properties": {
          "media_url": {
            "type": "string",
            "format": "uri",
            "description": "Valid publicly reachable HTTPS URL to the media asset (`https://...`). `blob:` and `data:` URIs are rejected."
          },
          "media_type": {
            "type": "string",
            "enum": ["image", "video", "audio", "document", "archive", "other", "text"]
          },
          "file_name": { "type": "string", "minLength": 1, "maxLength": 255 },
          "file_size": { "type": "integer", "minimum": 0 },
          "mime_type": { "type": "string", "maxLength": 128 },
          "audio_metadata": { "$ref": "#/components/schemas/AudioMetadata" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "status"],
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" },
              "status": { "type": "integer" },
              "request_id": { "type": "string" },
              "details": {}
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1/auth/verify": {
      "get": {
        "operationId": "verifyApiKey",
        "summary": "Verify API Key & Application Status",
        "description": "Validates the provided MemeFlow API key and returns the associated developer ID, application ID, active scopes, and 120 req/min rate limit state.",
        "responses": {
          "200": {
            "description": "API key is valid and active",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": { "type": "boolean", "example": true },
                    "developer_id": { "type": "string", "format": "uuid" },
                    "developer_name": { "type": "string" },
                    "developer_status": { "type": "string", "example": "active" },
                    "application_id": { "type": "string", "format": "uuid" },
                    "application_name": { "type": "string" },
                    "application_status": { "type": "string", "example": "active" },
                    "key_id": { "type": "string", "format": "uuid" },
                    "key_name": { "type": "string" },
                    "key_prefix": { "type": "string", "example": "mf_live_" },
                    "environment": { "type": "string", "enum": ["live", "test"] },
                    "permissions": { "type": "array", "items": { "type": "string" } },
                    "rate_limit": {
                      "type": "object",
                      "properties": {
                        "limit": { "type": "integer", "example": 120 },
                        "remaining": { "type": "integer", "example": 119 },
                        "reset": { "type": "integer", "example": 60 }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } }
            }
          }
        }
      }
    },
    "/api/v1/posts": {
      "get": {
        "operationId": "listPosts",
        "summary": "List Application Posts",
        "description": "Lists posts belonging to the authenticated developer and application (`posts:read`).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          { "name": "external_reference_id", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Paginated list of posts with Smart Links" },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Forbidden" }
        }
      },
      "post": {
        "operationId": "createPermanentPost",
        "summary": "Create a Permanent Multi-File Post & Smart Link",
        "description": "Creates a persistent post with 1–10 HTTPS media descriptors (`media[]`) and returns a monetized MemeFlow Smart Link (`/m/{slug}`). Supports idempotency via `Idempotency-Key` header or `idempotency_key` body field.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "media"],
                "properties": {
                  "title": { "type": "string", "minLength": 1, "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100, "default": "General" },
                  "external_reference_id": { "type": "string", "maxLength": 256 },
                  "monetization": {
                    "type": "string",
                    "enum": ["eligible", "not_eligible"],
                    "default": "eligible"
                  },
                  "status": {
                    "type": "string",
                    "enum": ["published", "draft"],
                    "default": "published"
                  },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "smart_link_slug": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{3,64}$" },
                  "return_url": { "type": "string", "format": "uri" },
                  "idempotency_key": { "type": "string", "maxLength": 256 },
                  "media": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 10,
                    "items": { "$ref": "#/components/schemas/MediaInputItem" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Post and Smart Link created" },
          "400": { "description": "Validation error or invalid media URL" },
          "409": { "description": "Slug conflict or idempotency payload mismatch" }
        }
      }
    },
    "/api/v1/posts/{id}": {
      "get": {
        "operationId": "getPostById",
        "summary": "Get Post Details, Lineage & Engagement Metrics",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Post details, media items, lineage, and Smart Link metrics" },
          "404": { "description": "Post not found" }
        }
      },
      "post": {
        "operationId": "performPostAction",
        "summary": "Republish, Re-upload as Creator, or Record Download Lineage",
        "description": "Executes `action: \"republish\"` (default, HTTP 201), `action: \"reupload_as_creator\"` (HTTP 201), or `action: \"download\"` (HTTP 200) on an owned post.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "action": {
                    "type": "string",
                    "enum": ["republish", "reupload_as_creator", "download"],
                    "default": "republish"
                  },
                  "media_url": { "type": "string", "format": "uri" },
                  "title": { "type": "string", "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100 },
                  "tags": { "type": "array", "items": { "type": "string" } },
                  "external_reference_id": { "type": "string" },
                  "visitor_token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Download lineage event recorded" },
          "201": { "description": "Stage 2 creator post republished or re-uploaded" }
        }
      },
      "patch": {
        "operationId": "patchPost",
        "summary": "Partially Update Post Metadata",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string", "minLength": 1, "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "minLength": 1, "maxLength": 100 },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "status": {
                    "type": "string",
                    "enum": ["published", "draft", "archived", "restricted", "removed"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Post updated" },
          "403": { "description": "Forbidden" }
        }
      },
      "put": {
        "operationId": "updatePost",
        "summary": "Update Post Metadata",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "title": { "type": "string", "minLength": 1, "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "minLength": 1, "maxLength": 100 },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "status": {
                    "type": "string",
                    "enum": ["published", "draft", "archived", "restricted", "removed"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Post updated" },
          "403": { "description": "Forbidden" }
        }
      },
      "delete": {
        "operationId": "deletePost",
        "summary": "Delete Post & Deactivate Smart Links",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Post deleted and associated Smart Links deactivated" },
          "403": { "description": "Forbidden" }
        }
      }
    },
    "/api/v1/posts/temporary": {
      "get": {
        "operationId": "getTemporaryPostStatusOrMetrics",
        "summary": "Inspect Browser-Local Delivery Session Status or Temporary Metrics",
        "description": "Queries active browser-local partner delivery session status by `delivery_session_id`, `partner_content_id`, `post_id`, or `temporary_post_id`, or runs `action=metrics|cleanup`.",
        "parameters": [
          { "name": "delivery_session_id", "in": "query", "schema": { "type": "string" } },
          { "name": "partner_content_id", "in": "query", "schema": { "type": "string" } },
          {
            "name": "content_version",
            "in": "query",
            "schema": { "type": "string", "default": "1.0" }
          },
          { "name": "post_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          {
            "name": "temporary_post_id",
            "in": "query",
            "schema": { "type": "string", "format": "uuid" }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["cleanup", "metrics", "storage_metrics", "status"]
            }
          },
          { "name": "verify", "in": "query", "schema": { "type": "boolean" } }
        ],
        "responses": {
          "200": { "description": "Session status or storage metrics" },
          "404": { "description": "Session not found" },
          "410": { "description": "Delivery session expired" }
        }
      },
      "post": {
        "operationId": "createTemporaryPartnerPost",
        "summary": "Create or Resolve a Browser-Local Ephemeral Partner Delivery Session",
        "description": "Creates or resolves an ephemeral browser-local partner delivery session (`delivery_mode: \"browser_local\"`, `storage_mode: \"temporary\"`). Partner content is delivered directly to the visitor's browser without storing binary files in MemeFlow Storage, and is cleared when the visitor leaves or returns to the partner platform. Supports idempotency via `Idempotency-Key` header or `idempotency_key` body field.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["partner_content_id"],
                "properties": {
                  "partner_content_id": { "type": "string", "minLength": 1, "maxLength": 256 },
                  "content_version": { "type": "string", "maxLength": 64, "default": "1.0" },
                  "action": { "type": "string", "default": "view" },
                  "action_type": { "type": "string" },
                  "title": { "type": "string", "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100, "default": "Partner Content" },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "return_url": { "type": "string", "format": "uri" },
                  "idempotency_key": { "type": "string", "maxLength": 256 },
                  "monetization": {
                    "type": "string",
                    "enum": ["eligible", "not_eligible", "disabled"],
                    "default": "eligible"
                  },
                  "media": {
                    "type": "array",
                    "maxItems": 10,
                    "items": { "$ref": "#/components/schemas/MediaInputItem" }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Cache miss (`status: \"requires_upload\"` or `\"expired\"`) or maintenance action result"
          },
          "201": {
            "description": "Active browser-local delivery session created (`status: \"active\"`)"
          },
          "409": { "description": "Idempotency conflict" }
        }
      }
    },
    "/api/v1/partner/content": {
      "get": {
        "operationId": "getPartnerContentStatus",
        "summary": "Check Partner Content Delivery Session Status",
        "parameters": [
          {
            "name": "partner_content_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "content_version",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "1.0" }
          }
        ],
        "responses": {
          "200": {
            "description": "Current delivery session status (`active`, `expired`, or `requires_upload`)"
          }
        }
      },
      "post": {
        "operationId": "ingestPartnerContent",
        "summary": "Register Partner Content for Browser-Local Delivery & Smart Link",
        "description": "Registers partner-hosted HTTPS media (`media_url` or `media[]`) for a fresh 10-minute browser-local partner delivery session (`delivery_mode: \"browser_local\"`) and issues a canonical Smart Link (`/m/{slug}`). Multipart binary uploads and Base64 payloads are prohibited. Supports idempotency via `Idempotency-Key` header or `idempotency_key` body field.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["partner_content_id"],
                "properties": {
                  "partner_content_id": { "type": "string", "minLength": 1, "maxLength": 256 },
                  "content_version": { "type": "string", "maxLength": 64, "default": "1.0" },
                  "action": { "type": "string", "default": "view" },
                  "title": { "type": "string", "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100, "default": "Partner Content" },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "return_url": { "type": "string", "format": "uri" },
                  "media_url": { "type": "string", "format": "uri" },
                  "media": {
                    "type": "array",
                    "maxItems": 10,
                    "items": { "$ref": "#/components/schemas/MediaInputItem" }
                  },
                  "idempotency_key": { "type": "string", "maxLength": 256 },
                  "monetization": {
                    "type": "string",
                    "enum": ["eligible", "not_eligible", "disabled"],
                    "default": "eligible"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Browser-local partner delivery session created and Smart Link issued"
          },
          "400": { "description": "Missing or invalid parameters" },
          "409": { "description": "Idempotency conflict" },
          "422": { "description": "Invalid content ID, version, return_url, or source media_url" }
        }
      }
    },
    "/api/v1/partner/content/resolve": {
      "get": {
        "operationId": "resolvePartnerContentGet",
        "summary": "Check Partner Content Resolution Status (GET)",
        "parameters": [
          {
            "name": "partner_content_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string" }
          },
          {
            "name": "content_version",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "1.0" }
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "default": "view" }
          }
        ],
        "responses": {
          "200": {
            "description": "Resolution status (`requires_upload` when no media is supplied)"
          }
        }
      },
      "post": {
        "operationId": "resolvePartnerContent",
        "summary": "Resolve Partner Content or Auto-Provision Browser-Local Session",
        "description": "Resolves partner content for browser-local visitor delivery (`partner.content.resolve`). Returns HTTP 200 with `status: \"requires_upload\"` when media is not supplied, or HTTP 201 with `status: \"active\"` and a fresh Smart Link when `media_url`/`media[]` is provided. Supports idempotency via `Idempotency-Key` header or `idempotency_key` body field.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["partner_content_id"],
                "properties": {
                  "partner_content_id": { "type": "string", "minLength": 1, "maxLength": 256 },
                  "content_version": { "type": "string", "maxLength": 64, "default": "1.0" },
                  "action": { "type": "string", "default": "view" },
                  "return_url": { "type": "string", "format": "uri" },
                  "title": { "type": "string", "maxLength": 200 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100 },
                  "tags": { "type": "array", "items": { "type": "string" } },
                  "media_url": { "type": "string", "format": "uri" },
                  "media": {
                    "type": "array",
                    "maxItems": 10,
                    "items": { "$ref": "#/components/schemas/MediaInputItem" }
                  },
                  "idempotency_key": { "type": "string", "maxLength": 256 }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "No media provided (`status: \"requires_upload\"`, `requires_upload: true`)"
          },
          "201": {
            "description": "Fresh browser-local partner delivery session created (`status: \"active\"`)"
          },
          "409": { "description": "Idempotency conflict" },
          "422": {
            "description": "Validation error on partner_content_id, content_version, return_url, or media_url"
          }
        }
      }
    },
    "/api/v1/partner/action": {
      "post": {
        "operationId": "recordPartnerAction",
        "summary": "Execute Partner Action & Provision Browser-Local Delivery Session",
        "description": "Server-authoritative partner action endpoint (`view`, `watch`, `listen`, `download`, `save`, `open`, `export`, `share`). Returns HTTP 201 (`status: \"active\"`) when `media_url`/`media[]` is provided, or HTTP 200 (`status: \"requires_upload\"`) when media is omitted. Supports idempotency via `Idempotency-Key` header or `idempotency_key` body field.",
        "parameters": [{ "$ref": "#/components/parameters/IdempotencyKeyHeader" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["partner_content_id"],
                "properties": {
                  "partner_content_id": { "type": "string", "minLength": 1, "maxLength": 256 },
                  "content_version": { "type": "string", "maxLength": 64, "default": "1.0" },
                  "action": { "type": "string", "maxLength": 64, "default": "view" },
                  "return_url": { "type": "string", "format": "uri" },
                  "title": { "type": "string", "maxLength": 300 },
                  "caption": { "type": "string", "maxLength": 2000 },
                  "category": { "type": "string", "maxLength": 100, "default": "Partner Content" },
                  "tags": {
                    "type": "array",
                    "maxItems": 20,
                    "items": { "type": "string", "maxLength": 50 }
                  },
                  "media_url": { "type": "string", "format": "uri" },
                  "media": {
                    "type": "array",
                    "maxItems": 10,
                    "items": { "$ref": "#/components/schemas/MediaInputItem" }
                  },
                  "idempotency_key": { "type": "string", "maxLength": 256 },
                  "monetization": {
                    "type": "string",
                    "enum": ["eligible", "disabled"],
                    "default": "eligible"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Action requires media upload (`status: \"requires_upload\"`)" },
          "201": {
            "description": "Fresh browser-local delivery session created (`status: \"active\"`)"
          },
          "409": { "description": "Idempotency conflict" },
          "422": { "description": "Unprocessable parameter" }
        }
      }
    },
    "/api/v1/links": {
      "get": {
        "operationId": "listSmartLinks",
        "summary": "List Smart Links",
        "description": "Lists Smart Links belonging to the authenticated developer and application (`posts:read`).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          { "name": "post_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }
        ],
        "responses": {
          "200": { "description": "List of Smart Links" }
        }
      },
      "post": {
        "operationId": "createSmartLink",
        "summary": "Generate a Smart Link (/m/{slug}) for an Existing Post",
        "description": "Generates or retrieves an active Smart Link (`/m/{slug}`) for an existing owned post (`links:create`). Pass optional `slug` (3–64 alphanumeric/hyphen/underscore chars) and optional `return_url`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["post_id"],
                "properties": {
                  "post_id": { "type": "string", "format": "uuid" },
                  "slug": {
                    "type": "string",
                    "pattern": "^[a-zA-Z0-9_-]{3,64}$",
                    "description": "Optional custom slug (3–64 characters)"
                  },
                  "return_url": { "type": "string", "format": "uri" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Existing active Smart Link returned (`is_existing: true`)" },
          "201": { "description": "New Smart Link generated" },
          "404": { "description": "Target post not found" },
          "409": { "description": "Requested `slug` is already in use" }
        }
      }
    },
    "/api/v1/links/{slug}": {
      "get": {
        "operationId": "resolveSmartLink",
        "summary": "Resolve Smart Link Metadata by Slug or UUID",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,64}$" }
          }
        ],
        "responses": {
          "200": { "description": "Smart Link metadata and click/visitor counters" },
          "404": { "description": "Smart Link not found" }
        }
      }
    },
    "/api/v1/media": {
      "post": {
        "operationId": "createPresignedMediaUpload",
        "summary": "Request Presigned Media Upload URL",
        "description": "Generates a presigned upload target for images, videos, 48kHz/24-bit studio audio, PDFs, or ZIP archives (`media:upload`). Direct multipart binary and Base64 uploads are rejected.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["file_name", "file_type", "file_size"],
                "properties": {
                  "file_name": { "type": "string", "minLength": 1, "maxLength": 255 },
                  "file_type": { "type": "string", "minLength": 1, "maxLength": 128 },
                  "file_size": { "type": "integer", "minimum": 1, "maximum": 524288000 },
                  "media_category": {
                    "type": "string",
                    "enum": ["image", "video", "audio", "document", "archive", "text", "other"],
                    "default": "image"
                  },
                  "is_studio_audio": { "type": "boolean", "default": false }
                }
              }
            }
          }
        },
        "responses": {
          "201": { "description": "Presigned upload descriptor created" },
          "400": { "description": "Validation error" },
          "413": { "description": "File size exceeds maximum allowed for category" }
        }
      }
    },
    "/api/v1/analytics": {
      "get": {
        "operationId": "getPartnerAnalytics",
        "summary": "Get Partner Traffic, Storage & Revenue Analytics",
        "description": "Returns request counters, posts created, Smart Links created, clicks, unique visitors, eligible impressions, estimated/finalized revenue, and browser-local partner delivery metrics (`analytics:read`).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          {
            "name": "days",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 365 }
          },
          {
            "name": "period",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": ["24h", "today", "7d", "30d", "90d", "365d", "month", "all"]
            }
          },
          { "name": "start_date", "in": "query", "schema": { "type": "string", "format": "date" } },
          { "name": "end_date", "in": "query", "schema": { "type": "string", "format": "date" } }
        ],
        "responses": {
          "200": { "description": "Analytics and storage summary" }
        }
      }
    },
    "/api/v1/webhooks": {
      "get": {
        "operationId": "listWebhooks",
        "summary": "List Registered Webhooks or Get Webhook Details",
        "parameters": [
          { "name": "webhook_id", "in": "query", "schema": { "type": "string", "format": "uuid" } },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          }
        ],
        "responses": {
          "200": { "description": "List of webhooks or single webhook with recent delivery logs" }
        }
      },
      "post": {
        "operationId": "registerOrTestWebhook",
        "summary": "Register HMAC-SHA256 Signed Webhook or Dispatch Test Ping",
        "description": "Registers a new HTTPS webhook subscription (HTTP 201, returning the one-time `signing_secret`) or dispatches a signed test ping when `action: \"test\" | \"ping\"` is passed (HTTP 200). Outgoing webhooks include `X-MemeFlow-Signature: t=<timestamp>,v1=<signature>` where `<signature>` is the hex HMAC-SHA256 digest over `${timestamp}.${rawBody}`.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public HTTPS endpoint (`https://...`)"
                  },
                  "events": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "enum": [
                        "post.created",
                        "post.published",
                        "post.republished",
                        "post.updated",
                        "post.restricted",
                        "post.removed",
                        "partner_delivery_session.created",
                        "partner_delivery_session.active",
                        "partner_delivery_session.expired",
                        "partner_delivery_session.cleaned",
                        "temporary_post.created",
                        "temporary_post.active",
                        "temporary_post.expiring",
                        "temporary_post.expired",
                        "temporary_post.deleted",
                        "temporary_post.cleanup_failed",
                        "smart_link.created",
                        "smart_link.visited",
                        "smart_link.expired",
                        "monetization.updated",
                        "earnings.updated",
                        "earnings.finalized",
                        "payout.updated",
                        "*"
                      ]
                    }
                  },
                  "secret": { "type": "string", "minLength": 24, "maxLength": 256 },
                  "action": { "type": "string", "enum": ["test", "ping"] },
                  "webhook_id": { "type": "string", "format": "uuid" },
                  "signing_secret": { "type": "string", "minLength": 24 }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Test webhook ping dispatched" },
          "201": {
            "description": "Webhook subscription registered (`signing_secret` returned once)"
          },
          "422": {
            "description": "Invalid webhook URL (must be public HTTPS) or unsupported event type"
          }
        }
      },
      "patch": {
        "operationId": "updateWebhook",
        "summary": "Update Webhook URL, Events, or Status",
        "parameters": [
          {
            "name": "webhook_id",
            "in": "query",
            "required": false,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "webhook_id": { "type": "string", "format": "uuid" },
                  "url": { "type": "string", "format": "uri" },
                  "events": { "type": "array", "items": { "type": "string" } },
                  "status": { "type": "string", "enum": ["active", "disabled"] }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Webhook updated" },
          "404": { "description": "Webhook not found" }
        }
      },
      "delete": {
        "operationId": "deleteWebhook",
        "summary": "Delete Webhook Subscription",
        "parameters": [
          {
            "name": "webhook_id",
            "in": "query",
            "required": true,
            "schema": { "type": "string", "format": "uuid" }
          }
        ],
        "responses": {
          "200": { "description": "Webhook deleted" },
          "404": { "description": "Webhook not found" }
        }
      }
    },
    "/api/v1/sdk/download": {
      "get": {
        "operationId": "downloadPersonalizedSdk",
        "summary": "Download Personalized Developer SDK Package (ZIP, JSON, or Markdown)",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "schema": { "type": "string", "enum": ["zip", "json", "md"], "default": "zip" }
          },
          {
            "name": "application_id",
            "in": "query",
            "schema": { "type": "string", "format": "uuid" }
          },
          { "name": "standard_name", "in": "query", "schema": { "type": "boolean" } }
        ],
        "responses": {
          "200": { "description": "SDK archive or specification file" },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Application boundary mismatch" }
        }
      }
    }
  }
}