Kokos API Documentation

This page documents all available API endpoints in the Kokos Laravel application. Endpoints are organized into two categories:

REST API Endpoints

External API routes under /api/* for integrations, webhooks, and programmatic access. Authentication varies per group.

Internal Web API Endpoints

JSON/HTMX endpoints within web routes that return data for frontend components. Require session authentication.

Authentication Methods
Method Header Description
AI Workflows Token Authorization: Bearer {token} Bearer token for AI/automation integrations. Set via AI_WORKFLOWS_API_TOKEN env var.
DMCA Token X-DMCA-Token: {token} DMCA-specific token for content takedown API. Set via DMCA_TOKEN_SECRET env var.
Webhook Signature Varies by provider HMAC signature verification for GitHub, UpDown.io webhooks.
Session Cookie-based Google OAuth session via RouteAccessMiddleware. Used by internal web API endpoints.
None - Public endpoint, no authentication required.
Base URL

All API routes are prefixed with /api. The base URL depends on the environment: 

Production:  https://kokos.xyz/api
Development: https://dev.kokos.xyz/api
Local:       http://localhost:8000/api

Quick Navigation

REST API

Internal Web API

REST API Endpoints

DmBot 4 endpoints

Method URI Description Auth Rate Limit
GET /api/dmbot/actions/next Get the next pending DmBot action to execute. None -
GET /api/dmbot/actions/{id}/last Get the last attempt for a specific DmBot action.
Params: id - Action ID 		None -
POST /api/dmbot/actions/{id}/log Record a new attempt for a DmBot action.
Params: id - Action ID 		None -
POST /api/dmbot/actions/{id}/update-attempt Update an existing DmBot action attempt with results.
Params: id - Action ID 		None -

Linksites Diversification 3 endpoints

Method URI Description Auth Rate Limit
POST /api/linksites/suggest-server Suggest the best server for a new linksite based on diversification rules (IP, location, hosting provider). None -
GET /api/linksites/diversification-stats Get current diversification statistics across all linksites. None -
GET /api/linksites/available-servers List available servers with market count data for placement decisions. None -

UpDown.io Webhooks 1 endpoints

Method URI Description Auth Rate Limit
POST /api/updown/webhook Receive uptime monitoring webhooks from UpDown.io service. UpDown webhook signature verification -

DMCA Check 2 endpoints

Method URI Description Auth Rate Limit
POST /api/dmca-check Submit a new DMCA check request for a URL. DMCA Token (dmca.token middleware) 60 requests/minute
GET /api/dmca-check/websites List websites available for DMCA checking. None 60 requests/minute

Ahrefs SEO Metrics 6 endpoints

Method URI Description Auth Rate Limit
GET /api/ahrefs/backlinks-stats/{domain} Get backlinks statistics for a domain from Ahrefs.
Params: domain - Domain name (e.g., example.com) 		AI Workflows Token (Bearer) 60 requests/minute
GET /api/ahrefs/domain-rating/{domain} Get Domain Rating (DR) for a domain.
Params: domain - Domain name 		AI Workflows Token (Bearer) 60 requests/minute
GET /api/ahrefs/metrics/{domain} Get comprehensive SEO metrics for a domain.
Params: domain - Domain name 		AI Workflows Token (Bearer) 60 requests/minute
GET /api/ahrefs/outlinks-stats/{domain} Get outgoing links statistics for a domain.
Params: domain - Domain name 		AI Workflows Token (Bearer) 60 requests/minute
GET /api/ahrefs/backlinks/{domain} List stored backlinks from MongoDB (no Ahrefs API credits consumed).
Params: domain - Domain name 		AI Workflows Token (Bearer) 60 requests/minute
POST /api/ahrefs/backlinks/{domain}/fetch Fetch fresh backlinks from Ahrefs API (rate limited: 5/hour).
Params: domain - Domain name 		AI Workflows Token (Bearer) -

Websites 1 endpoints

Method URI Description Auth Rate Limit
GET /api/websites List all websites with basic information. AI Workflows Token (Bearer) 60 requests/minute

GitHub Webhooks 2 endpoints

Method URI Description Auth Rate Limit
POST /api/github/webhook Receive GitHub webhook events (push, PR, deployment). Only accessible via dev.kokos.xyz domain. GitHub webhook signature (HMAC-SHA256) 10 requests/60 minutes
GET /api/github/ping Health check endpoint for GitHub webhook integration. None -

Internal Web API Endpoints

Health Check 1 endpoints

Method URI Description Auth
GET /health Application health check. Returns MySQL, MongoDB, cache, and storage status. None (public)

SEO Dashboard 2 endpoints

Method URI Description Auth
GET /seo/dashboard/quick-stats Get quick statistics for the SEO dashboard (HTMX partial). Session (RouteAccessMiddleware)
POST /seo/dashboard/refresh Trigger a refresh of SEO dashboard data. Session (RouteAccessMiddleware)

Target Markets 2 endpoints

Method URI Description Auth
GET /seo/target-markets/api/statistics Get target market statistics (website counts, diversity scores). Session (RouteAccessMiddleware)
POST /seo/target-markets/update-statistics Trigger recalculation of target market statistics. Session (RouteAccessMiddleware)

Server IPs 2 endpoints

Method URI Description Auth
GET /tech/server-ips/api/suggest Suggest available IPs for website deployment based on diversification. Session (RouteAccessMiddleware)
POST /tech/server-ips/api/collect Trigger IP collection from servers. Session (RouteAccessMiddleware)

Architecture Overview

Application Stack

Framework Laravel 12.x
PHP 8.4+
Primary DB MySQL (Eloquent ORM)
Secondary DB MongoDB (time-series data, backlinks)
Queue Redis + Laravel Horizon
Cache Redis
Frontend Blade + HTMx + Bulma CSS
Hosting RunCloud managed servers

External Integrations

SEO Ahrefs, AccuRanker, Google Analytics, Google Search Console
Hosting RunCloud, MainWP (WordPress)
Monitoring UpDown.io, Zabbix, VisualPing
Email ImprovMX (forwarding)
DNS/CDN Cloudflare, NitroPack
Revenue Voonix
Proxy Decodo, FlareSolverr, Microlink
Auth Google OAuth 2.0 + UMS

Key Design Patterns

  • BaseController - CRUD with HTMX, pagination, filtering, hooks
  • BaseCommand - Command locking, tracking, output capture
  • BaseJob - Job tracking, retry, Issue model integration
  • BaseMySqlModel / BaseMongoModel - UUID, validation, timestamps
  • ApiRateLimiter - Circuit breaker pattern for external APIs
  • Auditable trait - Opt-in audit logging for model changes

Security Model

  • Web Auth - Google OAuth 2.0 with session management
  • Route Access - RouteAccessMiddleware checks roles/permissions
  • API Auth - Bearer tokens for AI/automation integrations
  • Webhooks - HMAC signature verification (GitHub, UpDown)
  • Rate Limiting - Per-route throttle middleware
  • CSRF - Laravel built-in CSRF protection for web routes