{ "$schema": "https://creator-connect-earn.lovable.app/schemas/developer-sdk.v1.json", "title": "MemeFlow Developer SDK & AI Agent Specification", "description": "Comprehensive, machine-readable SDK and REST API specification for MemeFlow Connect. Synchronized with the production /api/v1 server contract.", "version": "1.4.0", "api_version": "v1", "generated_at": "2026-10-05T23:28:57.759Z", "application": { "application_id": "app_starter", "application_name": "MemeFlow Developer Starter", "developer_id": "dev_starter", "developer_name": "MemeFlow Developer", "api_base_url": "https://creator-connect-earn.lovable.app", "enabled_scopes": [ "posts:create", "posts:read", "media:upload", "links:create", "analytics:read" ], "key_prefix": "mf_live_", "secret_status": "never_exported_to_downloads" }, "authentication": { "type": "bearer_or_api_key", "description": "Every request to protected MemeFlow endpoints requires your API Key provided in Authorization: Bearer or X-API-Key: . Each API key is bound to its registered developer application.", "headers": { "Authorization": "Bearer YOUR_MEMEFLOW_API_KEY", "X-API-Key": "YOUR_MEMEFLOW_API_KEY" }, "idempotency": { "header": "Idempotency-Key", "body_field": "idempotency_key", "ttl_hours": 24, "supported_endpoints": [ "POST /api/v1/posts", "POST /api/v1/links", "POST /api/v1/posts/temporary", "POST /api/v1/partner/action", "POST /api/v1/partner/content", "POST /api/v1/partner/content/resolve" ], "description": "Provide a unique key in Idempotency-Key header (or idempotency_key JSON body field on partner routes). Replaying the same key with the same payload within 24 hours returns the cached response. Reusing the same key with a different payload returns 409 Conflict.", "example": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" }, "rate_limit": { "limit": 120, "window": "1 minute", "hourly_limit": 2000, "upload_limit_per_minute": 30, "headers": { "limit": "X-RateLimit-Limit", "remaining": "X-RateLimit-Remaining", "reset": "X-RateLimit-Reset", "retry_after": "Retry-After" } } }, "partner_delivery_architecture": { "delivery_mode": "browser_local", "description": "Partner content is delivered through a temporary browser-local delivery session. MemeFlow retains only the server metadata required for delivery authorization, attribution, analytics, idempotency, and audit. The visitor's browser receives and holds the content locally (IndexedDB/Blob) for the active session and purges it upon exit or expiration." }, "audio_studio_multitrack_standards": { "directive": "BandLab Quality Audio Engine", "description": "Preserve multi-track studio audio without destructive resampling or compression. Audio tracks maintain 48kHz sample rate, 24-bit depth, and 320kbps bitrate.", "supported_formats": [ "audio/wav", "audio/mpeg", "audio/ogg", "audio/flac", "audio/mp4", "audio/aac" ], "metadata_schema": { "isMultiTrack": "boolean (required true for stems/multi-tracks)", "sampleRate": "number (default: 48000)", "bitDepth": "number (default: 24)", "channelCount": "number (default: 2 for stereo)", "tempoBpm": "number (optional tempo in BPM)" }, "example": { "isMultiTrack": true, "sampleRate": 48000, "bitDepth": 24, "channelCount": 2, "tempoBpm": 128 } }, "endpoints": [ { "path": "/api/v1/auth/verify", "method": "GET", "summary": "Verify API Key & Permissions", "description": "Validates API key authenticity and returns developer, application, permissions, and rate limit details.", "required_scopes": [], "responses": { "200": { "success": true, "developer_id": "dev_starter", "developer_name": "MemeFlow Developer", "developer_status": "active", "application_id": "app_starter", "application_name": "MemeFlow Developer Starter", "application_status": "active", "key_prefix": "mf_live_", "environment": "live", "permissions": [ "posts:create", "posts:read", "media:upload", "links:create", "analytics:read" ], "rate_limit": { "limit": 120, "remaining": 119, "reset": 1789491060 } } } }, { "path": "/api/v1/posts", "method": "GET", "summary": "List Application Posts", "description": "Returns paginated posts belonging to the authenticated application.", "required_scopes": ["posts:read"], "responses": { "200": { "success": true, "data": [], "pagination": { "limit": 50, "offset": 0, "total": 0 } } } }, { "path": "/api/v1/posts", "method": "POST", "summary": "Create a Permanent Multi-File Post", "description": "Creates a new post with HTTPS media descriptors (media_url or media[]) and automatically generates a Smart Meme Link.", "required_scopes": ["posts:create"], "supports_idempotency": true, "headers": { "Content-Type": "application/json", "Authorization": "Bearer YOUR_MEMEFLOW_API_KEY", "Idempotency-Key": "UUID v4" }, "request_body": { "title": "My Viral Post Title", "caption": "Full text content or description.", "category": "Nigerian Memes", "external_reference_id": "ext_post_001", "smart_link_slug": "optional-custom-slug", "tags": ["viral", "music"], "media": [ { "media_url": "https://cdn.example.com/audio/track-01.wav", "media_type": "audio", "file_name": "track-01.wav", "file_size": 15420000, "audio_metadata": { "isMultiTrack": true, "sampleRate": 48000, "bitDepth": 24, "channelCount": 2 } } ] }, "responses": { "201": { "success": true, "data": { "post_id": "post_UUID", "title": "My Viral Post Title", "status": "published", "smart_link": "https://creator-connect-earn.lovable.app/m/abc12345", "smart_link_slug": "abc12345" } } } }, { "path": "/api/v1/posts/{id}", "method": "GET / POST / PATCH / PUT / DELETE", "summary": "Retrieve, Republish, Update, or Delete Post by ID", "description": "GET returns post details, media items, lineage, and Smart Link metadata (posts:read). POST executes republish, download, or reupload_as_creator (posts:create). PATCH/PUT updates post metadata (posts:create). DELETE deletes the post (posts:create).", "required_scopes": ["posts:read", "posts:create"], "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "success": true, "data": { "id": "post_UUID", "title": "My Viral Post Title", "status": "published", "smart_link_slug": "abc12345", "smart_link_url": "https://creator-connect-earn.lovable.app/m/abc12345" } } } }, { "path": "/api/v1/posts/temporary", "method": "GET / POST", "summary": "Create, Reuse, or Query Browser-Local Temporary Partner Delivery Session", "description": "POST registers or reuses a browser-local partner delivery session without permanently storing partner media in MemeFlow Storage (posts:create). GET inspects session status, metrics, or triggers cleanup (posts:read).", "required_scopes": ["posts:create", "posts:read"], "supports_idempotency": true, "request_body": { "partner_content_id": "partner-item-99182", "content_version": "1.0", "action_type": "view", "title": "Temporary Game Highlight", "media": [ { "media_url": "https://cdn.example.com/highlights/clip.mp4", "media_type": "video", "file_name": "clip.mp4" } ] }, "responses": { "200": { "status": "requires_upload", "requires_upload": true, "cache_lookup": "CACHE_MISS" }, "201": { "success": true, "status": "active", "post_id": "temp_UUID", "smart_link": "https://creator-connect-earn.lovable.app/m/tempSlug123", "expires_at": "ISO string", "delivery_mode": "browser_local", "cache_lookup": "CACHE_MISS" } } }, { "path": "/api/v1/partner/action", "method": "POST", "summary": "Execute Partner Action & Create/Reuse Browser-Local Delivery Session", "description": "Creates or reuses an active browser-local delivery session for a visitor action (view, download, watch, listen, save, open, export, share).", "required_scopes": ["partner.content.resolve", "posts:create"], "supports_idempotency": true, "request_body": { "partner_content_id": "partner-item-99182", "content_version": "1.0", "action": "view", "title": "Partner Track", "media_url": "https://cdn.example.com/audio/stem.wav" }, "responses": { "200": { "status": "requires_upload", "requires_upload": true, "smart_link": null }, "201": { "status": "active", "post_id": "post_UUID", "smart_link": "https://creator-connect-earn.lovable.app/m/p_abc123", "expires_at": "ISO string", "delivery_mode": "browser_local" } } }, { "path": "/api/v1/partner/content", "method": "POST", "summary": "Create or Reuse Partner Content Delivery Session", "description": "Creates or reuses a browser-local partner content delivery session using HTTPS media_url or media[] descriptors.", "required_scopes": ["partner.content.upload", "posts:create"], "supports_idempotency": true, "request_body": { "partner_content_id": "track_982401", "content_version": "1.0", "action": "view", "title": "Partner Audio Master", "media_url": "https://cdn.example.com/audio/master.wav", "media": [ { "media_url": "https://cdn.example.com/audio/master.wav", "media_type": "audio", "file_name": "master.wav" } ] }, "responses": { "200": { "status": "active", "post_id": "post_UUID", "smart_link": "https://creator-connect-earn.lovable.app/m/p_abc123", "expires_at": "ISO string", "delivery_mode": "browser_local", "cache": { "hit": true, "status": "CACHE_HIT" } }, "201": { "status": "active", "post_id": "post_UUID", "smart_link": "https://creator-connect-earn.lovable.app/m/p_abc123", "expires_at": "ISO string", "delivery_mode": "browser_local", "cache": { "hit": false, "status": "CACHE_MISS" } } } }, { "path": "/api/v1/partner/content/resolve", "method": "POST", "summary": "Resolve Partner Content Browser-Local Delivery Session", "description": "Checks whether an active browser-local delivery session exists for (application_id, partner_content_id, content_version) or signals requires_upload: true.", "required_scopes": ["partner.content.resolve", "posts:read"], "supports_idempotency": true, "request_body": { "partner_content_id": "track_982401", "content_version": "1.0", "action": "view" }, "responses": { "200": { "status": "active | requires_upload", "requires_upload": false, "post_id": "post_UUID", "smart_link": "https://creator-connect-earn.lovable.app/m/p_abc123", "expires_at": "ISO string", "delivery_mode": "browser_local" } } }, { "path": "/api/v1/links", "method": "GET", "summary": "List Smart Links", "description": "Lists Smart Meme Links belonging to the authenticated application.", "required_scopes": ["posts:read", "links:read"], "responses": { "200": { "success": true, "data": [], "pagination": { "limit": 50, "offset": 0, "count": 0 } } } }, { "path": "/api/v1/links", "method": "POST", "summary": "Generate Smart Link", "description": "Generates a shareable Smart Link (/m/{slug}) for an existing post.", "required_scopes": ["posts:create", "links:create"], "supports_idempotency": true, "request_body": { "post_id": "post_UUID", "slug": "optional-custom-slug", "external_reference_id": "optional_ref" }, "responses": { "201": { "success": true, "data": { "id": "link_UUID", "post_id": "post_UUID", "slug": "abc12345", "smart_link_url": "https://creator-connect-earn.lovable.app/m/abc12345" } } } }, { "path": "/api/v1/links/{slug}", "method": "GET", "summary": "Retrieve Smart Link Details & Analytics", "description": "Retrieves smart link metadata, post info, and click/visitor counts.", "required_scopes": ["posts:read", "links:read"], "responses": { "200": { "success": true, "data": { "id": "link_UUID", "slug": "abc12345", "smart_link_url": "https://creator-connect-earn.lovable.app/m/abc12345", "post_id": "post_UUID", "total_clicks": 42, "total_unique_visitors": 38 } } } }, { "path": "/api/v1/media", "method": "POST", "summary": "Request Presigned Upload URL", "description": "Obtains a signed upload_url and public_url for direct media uploads up to 500MB, including studio multi-track audio.", "required_scopes": ["media:upload"], "request_body": { "file_name": "master_track.wav", "file_type": "audio/wav", "file_size": 24500000, "media_category": "audio", "is_studio_audio": true }, "responses": { "201": { "success": true, "data": { "media_id": "media_UUID", "upload_url": "https://...", "public_url": "https://...", "expires_in": 3600 } } } }, { "path": "/api/v1/analytics", "method": "GET", "summary": "Get Application Analytics & Storage Metrics", "description": "Returns API request telemetry, Smart Link clicks, unique visitors, revenue estimates, and active browser-local delivery session statistics.", "required_scopes": ["analytics:read"], "responses": { "200": { "success": true, "data": { "developer_id": "dev_starter", "application_id": "app_starter", "total_requests": 1200, "successful_requests": 1195, "failed_requests": 5, "posts_created": 10, "smart_links_created": 12, "total_clicks": 450, "total_unique_visitors": 390, "eligible_impressions": 382, "estimated_revenue_usd": 1.53, "finalized_revenue_usd": 1.34, "period_breakdown": [], "storage_metrics": {}, "partner_metrics": {} } } } }, { "path": "/api/v1/webhooks", "method": "GET / POST / PATCH / DELETE", "summary": "Manage Webhook Subscriptions", "description": "List (GET 200), register (POST 201), update (PATCH 200), or delete (DELETE 200) HTTPS webhook subscriptions.", "required_scopes": ["webhooks:manage"] }, { "path": "/api/v1/sdk/download", "method": "GET", "summary": "Download Personalized SDK Bundle or Spec", "description": "Downloads the SDK archive or specification in zip, json, or md format.", "required_scopes": [] } ], "webhooks": { "configured": false, "url": "", "events": [], "signature_header": "X-MemeFlow-Signature", "signature_format": "t=,v1=", "signed_payload_template": "${timestamp}.${rawBody}", "algorithm": "HMAC-SHA256", "supported_events": [ "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", "*" ] }, "ai_agent_instructions": { "role": "Backend Integration Engineer", "implementation_strategy": "Implement a reusable client class (MemeFlowClient) without heavy dependencies. Include automatic Bearer authentication, UUID v4 idempotency generation, retry with exponential backoff on 429 (120 req/min) and 5xx codes, webhook verification using t=,v1= over ${timestamp}.${rawBody}, and BandLab audio fidelity preservation.", "env_variables": { "MEMEFLOW_API_KEY": "Your MemeFlow API Key (starts with mf_live_)", "MEMEFLOW_APP_ID": "app_starter", "MEMEFLOW_BASE_URL": "https://creator-connect-earn.lovable.app" } } }