{
  "openapi": "3.1.0",
  "info": {
    "title": "SharksAPI.AI Complete API",
    "description": "Complete API for SharksAPI.AI — the marketing platform: analytics, search, SEO, ads, social, e-mail and WordPress tools for AI agents. All data is fetched LIVE from platform APIs with OAuth2 Bearer authentication.",
    "version": "3.0.0"
  },
  "servers": [
    {
      "url": "https://sharksapi.ai"
    }
  ],
  "paths": {
    "/ai/api/user": {
      "get": {
        "summary": "Get Current User and Project Info",
        "description": "Returns the authenticated user's details and their current active project",
        "operationId": "getCurrentUser",
        "tags": ["Authentication"],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {"type": "integer"},
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "current_project": {
                      "type": "object",
                      "properties": {
                        "id": {"type": "integer"},
                        "name": {"type": "string"},
                        "slug": {"type": "string"}
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {"description": "Unauthorized"}
        }
      }
    },
    "/ai/api/v1/analytics/summary": {
      "get": {
        "summary": "Get Analytics Summary",
        "description": "Overview of all connected marketing platforms and their status",
        "operationId": "getAnalyticsSummary",
        "tags": ["Marketing - Overview"]
      }
    },
    "/ai/api/v1/analytics/ga4": {
      "get": {
        "summary": "Get Google Analytics 4 Data",
        "description": "Website traffic metrics: users, sessions, pageviews, bounce rate, avg session duration",
        "operationId": "getGA4Metrics",
        "tags": ["Marketing - Google Analytics"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "aggregate", "in": "query", "schema": {"type": "boolean", "default": true}}
        ]
      }
    },
    "/ai/api/v1/analytics/ga4/channels": {
      "get": {
        "summary": "Get GA4 Traffic by Channel",
        "description": "Sessions by channel (Organic Search, Direct, Social, Referral, Paid Search, Email)",
        "operationId": "getGA4Channels",
        "tags": ["Marketing - Google Analytics"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/gsc": {
      "get": {
        "summary": "Get Google Search Console Data",
        "description": "Search performance: clicks, impressions, CTR, average position",
        "operationId": "getGSCData",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "aggregate", "in": "query", "schema": {"type": "boolean", "default": true}}
        ]
      }
    },
    "/ai/api/v1/analytics/gsc/top-pages": {
      "get": {
        "summary": "Get Top GSC Pages",
        "description": "Landing pages with most clicks from Google Search",
        "operationId": "getGSCTopPages",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 10}}
        ]
      }
    },
    "/ai/api/v1/analytics/gsc/top-queries": {
      "get": {
        "summary": "Get Top Search Queries",
        "description": "Top search keywords bringing traffic from Google",
        "operationId": "getGSCTopQueries",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 10}}
        ]
      }
    },
    "/ai/api/v1/analytics/bing-webmaster": {
      "get": {
        "summary": "Get Bing Webmaster Tools Data",
        "description": "Search performance from Bing: clicks, impressions, CTR, average position",
        "operationId": "getBingWebmasterData",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "aggregate", "in": "query", "schema": {"type": "boolean", "default": true}}
        ]
      }
    },
    "/ai/api/v1/analytics/bing-webmaster/top-pages": {
      "get": {
        "summary": "Get Top Bing Pages",
        "description": "Landing pages with most clicks from Bing Search",
        "operationId": "getBingWebmasterTopPages",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 10}}
        ]
      }
    },
    "/ai/api/v1/analytics/bing-webmaster/top-queries": {
      "get": {
        "summary": "Get Top Bing Search Queries",
        "description": "Top search keywords bringing traffic from Bing",
        "operationId": "getBingWebmasterTopQueries",
        "tags": ["Marketing - Search Console"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 10}}
        ]
      }
    },
    "/ai/api/v1/analytics/facebook": {
      "get": {
        "summary": "Get Facebook Page Analytics",
        "description": "Facebook Page metrics: followers, impressions, reach, engagement",
        "operationId": "getFacebookInsights",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "aggregate", "in": "query", "schema": {"type": "boolean", "default": true}}
        ]
      }
    },
    "/ai/api/v1/analytics/linkedin": {
      "get": {
        "summary": "Get LinkedIn Company Page Analytics",
        "description": "LinkedIn Page metrics: followers, impressions, engagement",
        "operationId": "getLinkedInData",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/linkedin/analytics": {
      "get": {
        "summary": "Get Detailed LinkedIn Analytics",
        "operationId": "getLinkedInAnalytics",
        "tags": ["Marketing - Social Media"]
      }
    },
    "/ai/api/v1/analytics/linkedin/notifications": {
      "get": {
        "summary": "Get LinkedIn Notifications",
        "operationId": "getLinkedInNotifications",
        "tags": ["Marketing - Social Media"]
      }
    },
    "/ai/api/v1/analytics/linkedin/companies": {
      "get": {
        "summary": "List LinkedIn Companies",
        "operationId": "getLinkedInCompanies",
        "tags": ["Marketing - Social Media"]
      }
    },
    "/ai/api/v1/analytics/linkedin/posts": {
      "get": {
        "summary": "Get LinkedIn Posts",
        "operationId": "getLinkedInPosts",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 10}}
        ]
      }
    },
    "/ai/api/v1/analytics/twitter": {
      "get": {
        "summary": "Get Twitter/X Analytics",
        "description": "Twitter account metrics: followers, tweets, engagement",
        "operationId": "getTwitterData",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/instagram": {
      "get": {
        "summary": "Get Instagram Analytics",
        "description": "Instagram Business account metrics: followers, reach, impressions",
        "operationId": "getInstagramData",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/tiktok": {
      "get": {
        "summary": "Get TikTok Analytics",
        "description": "TikTok Business account metrics: followers, views, likes",
        "operationId": "getTikTokData",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/youtube": {
      "get": {
        "summary": "Get YouTube Analytics",
        "description": "YouTube channel metrics: subscribers, views, watch time",
        "operationId": "getYouTubeData",
        "tags": ["Marketing - Social Media"],
        "parameters": [
          {"name": "start_date", "in": "query", "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/google-ads": {
      "get": {
        "summary": "Get Google Ads Analytics",
        "description": "Google Ads campaign metrics: impressions, clicks, cost, conversions",
        "operationId": "getGoogleAdsData",
        "tags": ["Marketing - Advertising"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/meta-ads": {
      "get": {
        "summary": "Get Meta Ads Analytics",
        "description": "Meta (Facebook/Instagram) Ads campaign metrics",
        "operationId": "getMetaAdsData",
        "tags": ["Marketing - Advertising"],
        "parameters": [
          {"name": "start_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}},
          {"name": "end_date", "in": "query", "required": true, "schema": {"type": "string", "format": "date"}}
        ]
      }
    },
    "/ai/api/v1/analytics/google-business": {
      "get": {
        "summary": "Get Google Business Profile Data",
        "description": "Local SEO metrics: views, searches, actions",
        "operationId": "getGoogleBusinessData",
        "tags": ["Marketing - Local SEO"]
      }
    },
    "/ai/api/v1/analytics/google-business/reviews": {
      "get": {
        "summary": "Get Google Business Reviews",
        "operationId": "getGoogleBusinessReviews",
        "tags": ["Marketing - Local SEO"]
      }
    },
    "/ai/api/v1/analytics/google-business/metrics": {
      "get": {
        "summary": "Get Google Business Metrics",
        "operationId": "getGoogleBusinessMetrics",
        "tags": ["Marketing - Local SEO"]
      }
    },
    "/ai/api/v1/analytics/google-alerts": {
      "get": {
        "summary": "Get Google Alerts",
        "description": "Brand mentions with sentiment analysis",
        "operationId": "getGoogleAlerts",
        "tags": ["Marketing - Brand Monitoring"],
        "parameters": [
          {"name": "sentiment", "in": "query", "schema": {"type": "string", "enum": ["positive", "negative", "neutral"]}},
          {"name": "category", "in": "query", "schema": {"type": "string"}},
          {"name": "is_read", "in": "query", "schema": {"type": "boolean"}},
          {"name": "days", "in": "query", "schema": {"type": "integer"}},
          {"name": "limit", "in": "query", "schema": {"type": "integer", "default": 50}}
        ]
      }
    },
    "/ai/api/v1/wordpress/posts": {
      "get": {
        "summary": "List WordPress Posts",
        "operationId": "listWordPressPosts",
        "tags": ["Marketing - WordPress"],
        "parameters": [
          {"name": "per_page", "in": "query", "schema": {"type": "integer", "default": 10}},
          {"name": "status", "in": "query", "schema": {"type": "string", "enum": ["publish", "draft", "pending", "private"]}},
          {"name": "search", "in": "query", "schema": {"type": "string"}}
        ]
      },
      "post": {
        "summary": "Create WordPress Post",
        "operationId": "createWordPressPost",
        "tags": ["Marketing - WordPress"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["title", "content"],
                "properties": {
                  "title": {"type": "string"},
                  "content": {"type": "string"},
                  "status": {"type": "string", "enum": ["draft", "publish"]}
                }
              }
            }
          }
        }
      }
    },
    "/ai/api/v1/marketing/crawl/search": {
      "post": {
        "summary": "Search Web Mentions",
        "description": "Search web for brand mentions, discussions, reviews",
        "operationId": "searchWebMentions",
        "tags": ["Marketing - Brand Monitoring"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["keyword"],
                "properties": {
                  "keyword": {"type": "string"},
                  "brand_keywords": {"type": "array", "items": {"type": "string"}}
                }
              }
            }
          }
        }
      }
    },
    "/ai/api/v1/marketing/scrape": {
      "post": {
        "summary": "Scrape Website",
        "description": "Scrape any website using a headless browser. Extract page title, H1, meta description, text content, links, images, and headings. Works with JavaScript-heavy websites and SPAs. Use this for competitor analysis, SEO audits, price monitoring, and content research.",
        "operationId": "scrapeWebsite",
        "tags": ["Marketing - Web Scraper"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "The URL to scrape (must include https:// or http://)",
                    "example": "https://example.com"
                  },
                  "extract": {
                    "type": "array",
                    "description": "What data to extract from the page. Default: title, h1, meta_description, text",
                    "items": {
                      "type": "string",
                      "enum": ["title", "h1", "meta_description", "text", "links", "images", "headings"]
                    },
                    "default": ["title", "h1", "meta_description", "text"],
                    "example": ["title", "h1", "meta_description", "links"]
                  },
                  "wait_for_selector": {
                    "type": "string",
                    "description": "CSS selector to wait for before scraping (for dynamic/SPA pages)",
                    "example": ".content-loaded"
                  },
                  "custom_selector": {
                    "type": "string",
                    "description": "Custom CSS selector to extract specific elements",
                    "example": ".product-price, .product-title"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Website scraped successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "success"
                    },
                    "url": {
                      "type": "string",
                      "description": "The scraped URL"
                    },
                    "data": {
                      "type": "object",
                      "description": "Extracted data from the page",
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "Page title"
                        },
                        "h1": {
                          "type": "string",
                          "description": "First H1 heading"
                        },
                        "meta_description": {
                          "type": "string",
                          "description": "Meta description content"
                        },
                        "text": {
                          "type": "string",
                          "description": "Page text content (first 5000 chars)"
                        },
                        "links": {
                          "type": "array",
                          "description": "Links found on the page",
                          "items": {
                            "type": "object",
                            "properties": {
                              "text": {"type": "string"},
                              "href": {"type": "string"}
                            }
                          }
                        },
                        "images": {
                          "type": "array",
                          "description": "Images found on the page",
                          "items": {
                            "type": "object",
                            "properties": {
                              "src": {"type": "string"},
                              "alt": {"type": "string"}
                            }
                          }
                        },
                        "headings": {
                          "type": "array",
                          "description": "H1, H2, H3 headings",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tag": {"type": "string"},
                              "text": {"type": "string"}
                            }
                          }
                        },
                        "custom": {
                          "type": "array",
                          "description": "Custom selector results",
                          "items": {"type": "string"}
                        }
                      }
                    },
                    "message": {
                      "type": "string",
                      "example": "Website scraped successfully"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - Invalid URL or parameters"
          },
          "503": {
            "description": "Service unavailable - Scraper service is not running"
          },
          "500": {
            "description": "Server error - Failed to scrape website"
          }
        }
      }
    },
    "/ai/api/v1/marketing/emails": {
      "get": {
        "summary": "Get Marketing Emails",
        "description": "Retrieve emails from inbox with optional filters. Returns email list with full content and metadata.",
        "operationId": "getMarketingEmails",
        "tags": ["Marketing - Email"],
        "parameters": [
          {
            "name": "folder",
            "in": "query",
            "description": "Email folder to search (default: INBOX)",
            "schema": {
              "type": "string",
              "default": "INBOX"
            }
          },
          {
            "name": "unread_only",
            "in": "query",
            "description": "Show only unread emails",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "from",
            "in": "query",
            "description": "Filter by sender email address",
            "schema": {
              "type": "string",
              "format": "email"
            }
          },
          {
            "name": "subject_contains",
            "in": "query",
            "description": "Filter by subject text",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Maximum number of emails to return (max: 50)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of emails with full content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer",
                      "description": "Number of emails returned"
                    },
                    "emails": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {"type": "string"},
                          "from": {"type": "string"},
                          "to": {"type": "string"},
                          "subject": {"type": "string"},
                          "date": {"type": "string"},
                          "seen": {"type": "boolean"},
                          "body": {"type": "string"},
                          "size": {"type": "integer"}
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - No active email connection found"
          },
          "500": {
            "description": "Server error - Failed to retrieve emails"
          }
        }
      }
    },
    "/ai/api/v1/marketing/emails/send": {
      "post": {
        "summary": "Send Marketing Email",
        "description": "Send an email immediately to a recipient using the configured SMTP connection",
        "operationId": "sendMarketingEmail",
        "tags": ["Marketing - Email"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["to", "subject", "body"],
                "properties": {
                  "to": {
                    "type": "string",
                    "format": "email",
                    "description": "Recipient email address"
                  },
                  "subject": {
                    "type": "string",
                    "description": "Email subject line",
                    "maxLength": 255
                  },
                  "body": {
                    "type": "string",
                    "description": "Email body content (plain text or HTML)",
                    "maxLength": 10000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email sent successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Email sent successfully"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - No active email connection found"
          },
          "422": {
            "description": "Validation error - Invalid email format or missing required fields"
          },
          "500": {
            "description": "Server error - Failed to send email"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {},
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}