Endpoint Reference

Complete reference for all MarketGeist Public API endpoints. All endpoints require authentication via X-API-Key or Authorization: Bearer header.

Base URL

https://marketgeist.com/api/v1/public

Reports

GET/api/v1/public/reportsreports

List all reports for the authenticated user.

Parameters

Name	Type	Required	Description
`skip`	integer	No	Number of records to skip (default: 0)
`limit`	integer	No	Max records to return (default: 20, max: 100)

Response

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": 42,
        "niche": "SaaS CRM market",
        "report_type": "comprehensive_analysis",
        "status": "completed",
        "created_at": "2026-04-10T14:30:00"
      }
    ],
    "total": 15
  }
}

POST/api/v1/public/reportsreports

Generate a new AI-powered market research report.

Parameters

Name	Type	Required	Description
`niche`	string	Yes	Market or industry to analyze (2-200 chars)
`report_type`	string	No	Report type slug (default: comprehensive_analysis)
`context`	string	No	Additional context for the report

Response

{
  "success": true,
  "data": {
    "id": 43,
    "title": "Comprehensive Analysis: AI Recruitment Platforms",
    "status": "completed"
  }
}

GET/api/v1/public/reports/{report_id}reports

Retrieve a specific report with full content.

Response

{
  "success": true,
  "data": {
    "id": 42,
    "niche": "SaaS CRM market",
    "report_type": "comprehensive_analysis",
    "status": "completed",
    "executive_summary": "The global SaaS CRM market is valued at...",
    "sections": { ... },
    "created_at": "2026-04-10T14:30:00"
  }
}

Competitors

GET/api/v1/public/competitorscompetitors

List all tracked competitors for the authenticated user.

Response

{
  "success": true,
  "data": [
    {
      "id": 5,
      "name": "Acme Corp",
      "domain": "acme.com",
      "status": "active",
      "created_at": "2026-03-15T09:00:00"
    }
  ]
}

SEO & Keywords

GET/api/v1/public/seo/keywordsseo

List all tracked keywords with current positions and search volume.

Response

{
  "success": true,
  "data": [
    {
      "id": 12,
      "keyword": "market intelligence software",
      "target_url": "https://example.com",
      "current_position": 7,
      "search_volume": 1200,
      "position_history": [...],
      "created_at": "2026-04-01T12:00:00"
    }
  ]
}

GET/api/v1/public/seo/trendingseo

Get the latest trending keywords from the SEO intelligence map.

Response

{
  "success": true,
  "data": [
    { "keyword": "ai market research", "volume": 8500, "trend": "rising", "country": "US" }
  ]
}

Market Signals

GET/api/v1/public/signalssignals

Get real-time market signals and news intelligence.

Parameters

Name	Type	Required	Description
`q`	string	No	Search query to filter signals
`limit`	integer	No	Max results (default: 20, max: 100)

Response

{
  "success": true,
  "data": [
    {
      "title": "Series B Funding in Enterprise AI",
      "snippet": "New $50M round announced...",
      "url": "https://...",
      "source": "TechCrunch",
      "published_at": "2026-04-10"
    }
  ]
}

Social Trends

GET/api/v1/public/social-trends/{platform}social_trends

Get trending topics from a specific social platform.

Parameters

Name	Type	Required	Description
`platform`	string	Yes	One of: reddit, google_trends, pytrends, x, tiktok, feed

Response

{
  "success": true,
  "data": [
    {
      "title": "AI Agents for Sales",
      "score": 2500,
      "platform": "reddit",
      "subreddit": "r/SaaS"
    }
  ],
  "updated_at": "2026-04-10T15:00:00"
}

Market Data

GET/api/v1/public/market-data/searchmarket_data

Search for companies by name, ticker, or industry.

Parameters

Name	Type	Required	Description
`q`	string	Yes	Search query (name, ticker, or industry)
`limit`	integer	No	Max results (default: 20, max: 100)

Response

{
  "success": true,
  "data": [
    {
      "id": 123,
      "name": "Salesforce",
      "ticker": "CRM",
      "industry": "Software",
      "revenue": 31352000000,
      "market_cap": 250000000000
    }
  ]
}

Status Endpoint

Check API availability without authentication:

GET /api/v1/public/status