version: "3.5"
api_url: "https://plsr.goated.lat"
secondary_api_url: "https://pulsar-api.netlify.app"
api_version_tag: "v3.5-Stable"

branding:
  name: "Pulsar Docs"
  logo: "/cdn/pulsar?raw=true"
  accent_color: "#ffffff"
  footer_links:
    - name: "Home"
      url: "/"
    - name: "Atlas"
      url: "/atlas"
    - name: "API"
      url: "/docs"
  sidebar_labels:
    getting_started: "Getting Started"
    api_reference: "API Reference"
    base_url: "Base URL"

introduction:
  title: "Pulsar API v3"
  description: "The Pulsar API v3 offers tools for media downloading, Roblox integration, secure Discord verification, and text translation. Hosted on Netlify edge network for low latency and high scalability."
  base_url: "/api/v3"
  getting_started: "All endpoints start with /api/v3. The API follows REST conventions and returns consistent JSON responses."
  highlight:
    title: "Performance"
    description: "Edge deployment on Netlify provides very low latency and automatic global scaling."

features:
  title: "Main Features"
  items:
    - name: "Task System"
      description: "Handles long-running operations with polling or real-time streaming"
      modes:
        - "Direct (synchronous – default)"
        - "Normal task (?task=normal)"
        - "Streaming (?task=stream)"
    - name: "Media Downloader"
      description: "Downloads videos, audio, and images from 50+ platforms with CDN proxy"
    - name: "Roblox Integration"
      description: "Access game icons, versions, scripts, avatars, stock data, and more"
    - name: "Stateless Verification"
      description: "Secure, captcha-based Discord verification (hCaptcha or Turnstile)"
    - name: "Translation"
      description: "Translate text with automatic language detection"

task_system:
  title: "Task System"
  description: "Asynchronous processing for long operations. Not every endpoint uses tasks—some have custom flows."
  note: "Important: Discord verification endpoints (/api/v3/ds/verify/*) use a separate session-based system, not tasks."
  modes:
    direct:
      description: "Synchronous (immediate) execution"
      usage: "No task parameter (default)"
      example: "/api/v3/dl?url=..."
    normal:
      description: "Create task and poll for result"
      usage: "?task=normal"
      workflow:
        - "Request returns taskId and poll URL"
        - "Poll /api/v3/task/{taskId} repeatedly"
        - "Get final result when status = success"
      example: "/api/v3/dl?url=...&task=normal"
    stream:
      description: "Real-time updates via Server-Sent Events (SSE)"
      usage: "?task=stream"
      response_type: "text/event-stream"
      workflow:
        - "Connection opens"
        - "Status updates are streamed"
        - "Final result or error is sent"
        - "Connection closes"
      example: "/api/v3/dl?task=stream&url=..."

categories:
  - id: "general"
    name: "General"
    icon: "Globe"
  - id: "download"
    name: "Download"
    icon: "Download"
  - id: "roblox"
    name: "Roblox"
    icon: "Gamepad2"
  - id: "verification"
    name: "Verification"
    icon: "ShieldCheck"
  - id: "translation"
    name: "Translation"
    icon: "Languages"
  - id: "management"
    name: "Management"
    icon: "Settings"

endpoints:
  # ────────────────────────────────────────────────
  # GENERAL
  - path: "/api/v3"
    method: "GET"
    category: "general"
    description: "Simple health check – confirms API v3 is running"
    response:
      success:
        message: "API v3 is running"
    features:
      - "Cached for 5 minutes"
    examples:
      - "/api/v3"

  # ────────────────────────────────────────────────
  # DOWNLOAD
  - path: "/api/v3/dl"
    method: "GET"
    category: "download"
    description: "Download video, audio or images from supported platforms. Supports async task modes."
    parameters:
      - name: "url"
        type: "string"
        required: true
        description: "Media URL"
      - name: "task"
        type: "string"
        required: false
        description: "Task mode: normal or stream"
    response:
      success:
        videos: "Array of video URLs"
        audios: "Array of audio URLs"
        images: "Array of image URLs"
        title: "Media title"
    features:
      - "All downloads proxied via /cdn/"
      - "Optional task system"
    examples:
      - "/api/v3/dl?url=https://tiktok.com/@user/video/123"
      - "/api/v3/dl?url=...&task=normal"

  - path: "/api/v3/dl/supported"
    method: "GET"
    category: "download"
    description: "List of supported domains/platforms"
    parameters:
      - name: "format"
        type: "string"
        required: false
        values: ["grouped", "flat"]
    examples:
      - "/api/v3/dl/supported?format=flat"

  - path: "/api/v3/dl/info"
    method: "GET"
    category: "download"
    description: "Get metadata only (title, thumbnail, available formats) – no download"
    parameters:
      - name: "url"
        type: "string"
        required: true
    response:
      success:
        title: "string"
        thumbnail: "string"
        videos: "array"
        audios: "array"
    features:
      - "Cached for 1 hour"
    examples:
      - "/api/v3/dl/info?url=https://youtube.com/watch?v=..."

  # ────────────────────────────────────────────────
  # ROBLOX
  - path: "/api/v3/rblx/version"
    method: "GET"
    category: "roblox"
    description: "Current Roblox client version information"
    example: "/api/v3/rblx/version"

  - path: "/api/v3/rblx/gs/icon"
    method: "GET"
    category: "roblox"
    description: "Get game icon by Roblox game ID"
    parameters:
      - name: "gameId"
        type: "string"
        required: true
    example: "/api/v3/rblx/gs/icon?gameId=123456789"

  - path: "/api/v3/rblx/ss/fetch"
    method: "GET"
    category: "roblox"
    description: "List Pulsar-hosted Roblox scripts (paginated)"
    parameters:
      - name: "page"
        type: "number"
        default: 1
      - name: "max"
        type: "number"
        default: 20
      - name: "type"
        type: "string"
        values: ["free", "paid"]
      - name: "sort"
        type: "string"
        values: ["views", "created", "updated"]
    example: "/api/v3/rblx/ss/fetch?type=free&sort=views"

  - path: "/api/v3/rblx/ss/search"
    method: "GET"
    category: "roblox"
    description: "Search Pulsar-hosted Roblox scripts"
    parameters:
      - name: "q"
        type: "string"
        required: true
    example: "/api/v3/rblx/ss/search?q=admin"

  - path: "/api/v3/rblx/st/bf"
    method: "GET"
    category: "roblox"
    description: "Current Blox Fruits stock / stock value"
    example: "/api/v3/rblx/st/bf"

  - path: "/api/v3/rblx/st/pvsb"
    method: "GET"
    category: "roblox"
    description: "Current Project Slayers (PVSB) stock"
    example: "/api/v3/rblx/st/pvsb"

  - path: "/api/v3/rblx/exp"
    method: "GET"
    category: "roblox"
    description: "List of Roblox exploits with download links"
    example: "/api/v3/rblx/exp"

  # ────────────────────────────────────────────────
  # VERIFICATION (separate session workflow – NOT tasks)
  - path: "/api/v3/ds/verify/create"
    method: "POST"
    category: "verification"
    description: "Start a new stateless verification session"
    parameters:
      - name: "taskId"
        type: "string"
        required: true
        description: "Your internal task/job identifier"
      - name: "discordId"
        type: "string"
        required: true
      - name: "serverName"
        type: "string"
        required: false
      - name: "serverIcon"
        type: "string"
        required: false
      - name: "serverDescription"
        type: "string"
        required: false
      - name: "serverBanner"
        type: "string"
        required: false
      - name: "captchaProvider"
        type: "string"
        values: ["hcaptcha", "turnstile"]
        default: "hcaptcha"
    response:
      success:
        verifyUrl: "Link to send user to"
        statusUrl: "Endpoint to poll"
        captchaProvider: "hcaptcha | turnstile"
    examples:
      - |
        POST /api/v3/ds/verify/create
        {
          "taskId": "job-8472",
          "discordId": "9471283947123",
          "captchaProvider": "turnstile"
        }

  - path: "/api/v3/ds/verify/status"
    method: "GET"
    category: "verification"
    description: "Check verification session status"
    parameters:
      - name: "vid"
        type: "string"
        required: true
        description: "Verification ID (short or full)"
    response:
      success:
        status: "pending | completed | expired"
    examples:
      - "/api/v3/ds/verify/status?vid=xy12ab34"

  - path: "/api/v3/ds/verify/check"
    method: "POST"
    category: "verification"
    description: "Internal endpoint – submit captcha result (called by verification page)"
    parameters:
      - name: "vid"
        type: "string"
        required: true
      - name: "captchaToken"
        type: "string"
        required: true
    examples:
      - |
        POST /api/v3/ds/verify/check
        {
          "vid": "xy12ab34",
          "captchaToken": "..."
        }

  # ────────────────────────────────────────────────
  # TRANSLATION
  - path: "/api/v3/tr"
    method: "GET"
    category: "translation"
    description: "Translate text to target language"
    parameters:
      - name: "q"
        type: "string"
        required: true
      - name: "target"
        type: "string"
        default: "en"
      - name: "source"
        type: "string"
        description: "Optional – auto-detected if omitted"
    examples:
      - "/api/v3/tr?q=hola&target=en"

  # ────────────────────────────────────────────────
  # MANAGEMENT
  - path: "/api/v3/task/{id}"
    method: "GET"
    category: "management"
    description: "Check task status and get result when ready"
    parameters:
      - name: "id"
        type: "string"
        required: true
    example: "/api/v3/task/abc123-def456"

  - path: "/api/v3/db/status"
    method: "GET"
    category: "management"
    description: "Check health of database / KV storage"
    example: "/api/v3/db/status"

response_format:
  title: "Response Format"
  success:
    status: "success"
    data: "Object | Array"
    message: "Optional success message"
  error:
    status: "error"
    message: "Human readable explanation"
    code: "ERR_CODE"

error_codes:
  title: "Common Error Codes"
  items:
    - code: "MISSING_PARAMETER"
      description: "Required field is missing"
    - code: "INVALID_PARAMETERS"
      description: "Parameter value is not valid"
    - code: "INTERNAL_ERROR"
      description: "Unexpected server error"
    - code: "TASK_FAILED"
      description: "Background task failed"
    - code: "TASK_NOT_FOUND"
      description: "Task ID invalid or expired"
    - code: "SESSION_NOT_FOUND"
      description: "Verification session not found or expired"
    - code: "BOT_DETECTED"
      description: "Request blocked (suspected automation)"
    - code: "DATABASE_ERROR"
      description: "Database operation failed"
    - code: "DB_SERVICE_UNAVAILABLE"
      description: "Database temporarily unavailable"
    - code: "VERIFICATION_FAILED"
      description: "Captcha or verification process failed"