-- [[ Rscripts Risk Notice ]]
-- This script is not verified by rscripts.net. Deal with caution.
--
-- Stay safe:
--   • Never log in on unofficial Roblox sites or lookalike domains.
--   • Real Roblox links use roblox.com (check the .com ending).
--   • Treat fake Roblox login / "claim reward" pages as phishing.
-- [[ End Rscripts Risk Notice ]]
# Rscripts Public API

Base URL: `https://api.rscripts.net`
Version: v1

Read-only JSON API. All successful responses use `{ success: true, data, meta? }`.

## Authentication

All /v1 endpoints require an API key. Every signed-in user can create one instantly from [/dashboard/api](/dashboard/api).

- `Authorization: Bearer rsc_live_… (recommended)`
- `X-Api-Key: rsc_live_… (alternative)`

- /health and the root metadata route are public.
- Invalid or missing keys return 401 with code UNAUTHORIZED.
- Regenerating your key in the dashboard revokes the previous one immediately.

## Trust & safety

Every script in the API has passed automated risk screening. Scripts that score above our safety threshold are automatically removed from public results and queued for manual review. They never appear in search, list, or trending responses.

- High-risk scripts are filtered before they reach the API.
- Flagged uploads enter manual review and stay hidden until cleared.
- Each result includes a risk score (1–10) and level so you can add your own UI guardrails.
- Full findings (patterns, obfuscation, severity) are on the script detail endpoint.

A null risk field means the script has not been scanned yet, not that it is safe. Most indexed scripts include a score.

## Rate limits

- 1,000 requests per 60 seconds per IP (Redis-backed, fail-open)
- Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
- 429 when exceeded with Retry-After

## Shared query parameters

- `htmlDescription` (boolean, default false): Return descriptions as raw HTML instead of stripped plain text.
- `includeScript` (boolean, default false): Inline raw Lua source in the response. Default off on list/search/trending. Use rawScript URL instead. Always on for script detail.

## Endpoints

### GET /health

Service health check. Returns database, cache, and search service status.

Example:
`https://api.rscripts.net/health`

Example response:
```json
{
  "status": "ok",
  "services": {
    "postgres": "ok",
    "redis": "ok",
    "vector-search": "ok"
  },
  "ts": "2026-08-08T13:59:16.336Z"
}
```

### GET /v1/search

Multi-index search across scripts, users, and games. Powered by the same AI vector search ranking used on rscripts.net.

Parameters:
- `q` (string): Search query (1–100 chars). Required.
- `index` (string, default scripts,users,games): Comma-separated indexes: scripts, users, games.
- `limit` (number, default 10): Results per index (1–20).
- `page` (number, default 1): Page number (1–100).
- `htmlDescription` (boolean, default false): Return descriptions as raw HTML instead of stripped plain text.
- `includeScript` (boolean, default false): Inline raw Lua source in the response. Default off on list/search/trending. Use rawScript URL instead. Always on for script detail.

- Pagination lives in the top-level meta.pagination object (per index).
- Script hits include rawScript URL always; inline script requires includeScript=true.
- Risk summary on every script hit; full findings on the detail endpoint.
- High-risk scripts are filtered out before indexing. Results are safety-screened by default.

Example:
`https://api.rscripts.net/v1/search?q=autofarm&index=scripts&limit=5`

Example response:
```json
{
  "success": true,
  "data": {
    "query": "autofarm",
    "scripts": [
      {
        "id": "6a415d691f68eb0f1be7b582",
        "title": "Autofarm, Car Godmode, Infinite Stamina",
        "slug": "autofarm-car-godmode-example",
        "description": "Auto farm with vehicle modifiers…",
        "views": 12400,
        "likes": 42,
        "dislikes": 2,
        "rawScript": "https://rscripts.net/raw/example.txt",
        "script": null,
        "risk": {
          "score": 2,
          "level": "Safe",
          "isObfuscated": false,
          "obfuscatorDetected": null
        },
        "game": {
          "placeId": "2753915549",
          "title": "Blox Fruits",
          "thumbnailUrl": "https://tr.rbxcdn.com/…",
          "logoUrl": "https://tr.rbxcdn.com/…",
          "robloxUrl": "https://www.roblox.com/games/2753915549"
        },
        "creator": {
          "username": "dev",
          "isVerified": true,
          "subscriptionTier": "free",
          "isPro": false,
          "avatarUrl": null
        }
      }
    ],
    "users": [],
    "games": []
  },
  "meta": {
    "pagination": {
      "scripts": {
        "page": 1,
        "limit": 5,
        "total": 128,
        "totalPages": 26,
        "hasNextPage": true,
        "hasPrevPage": false
      }
    }
  }
}
```

### GET /v1/scripts

Browse or search scripts with sorting and filters. Pass placeId to list scripts for a specific Roblox game.

Parameters:
- `q` (string): Optional search query (uses AI vector search when set).
- `placeId` (string): Roblox place ID. When set, returns only scripts for that game (same as game pages on rscripts.net). Combines with q and other filters.
- `page` (number, default 1): Page (1–200).
- `limit` (number, default 20): Items per page (1–48).
- `sort` (enum, default newest): newest | oldest | most-views | least-views | most-likes | trending
- `noKeySystem` (boolean, default false): Exclude key-system scripts.
- `mobileOnly` (boolean, default false): Mobile-ready scripts only.
- `freeOnly` (boolean, default false): Free scripts only.
- `verifiedOnly` (boolean, default false): Verified creators only.
- `htmlDescription` (boolean, default false): Return descriptions as raw HTML instead of stripped plain text.
- `includeScript` (boolean, default false): Inline raw Lua source in the response. Default off on list/search/trending. Use rawScript URL instead. Always on for script detail.

- Pagination is in the top-level meta object.
- When placeId is set, meta.game includes the resolved game title, thumbnails, and Roblox URL.
- Returns public scripts only. Patched, private, and under-review scripts are excluded.

Example:
`https://api.rscripts.net/v1/scripts?placeId=2753915549&sort=most-likes&limit=12`

Example response:
```json
{
  "success": true,
  "data": [
    {
      "id": "…",
      "title": "…",
      "slug": "…",
      "rawScript": "https://rscripts.net/raw/…",
      "script": null,
      "game": {
        "placeId": "2753915549",
        "title": "Blox Fruits"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 12,
    "total": 842,
    "totalPages": 71,
    "hasNextPage": true,
    "hasPrevPage": false,
    "game": {
      "placeId": "2753915549",
      "title": "Blox Fruits",
      "thumbnailUrl": "https://tr.rbxcdn.com/…",
      "logoUrl": "https://tr.rbxcdn.com/…",
      "robloxUrl": "https://www.roblox.com/games/2753915549"
    }
  }
}
```

### GET /v1/scripts/:slug

Full script object by slug, including executors, game, risk findings, and inline Lua source.

Parameters:
- `htmlDescription` (boolean, default false): Return description as raw HTML.

- Script content is always included on detail (no includeScript flag needed).

Example:
`https://api.rscripts.net/v1/scripts/example-slug-abc123`

Example response:
```json
{
  "success": true,
  "data": {
    "id": "69e11446c3822ebe4c6400f8",
    "title": "Example Script",
    "slug": "example-script-abc",
    "description": "Plain-text description…",
    "rawScript": "https://rscripts.net/raw/example.txt",
    "script": "loadstring(game:HttpGet(\"…\"))()",
    "risk": {
      "score": 3,
      "level": "Low Risk",
      "isObfuscated": false,
      "findings": [
        {
          "label": "HttpService",
          "severity": "info",
          "description": null
        }
      ]
    },
    "game": {
      "placeId": "123",
      "title": "Game",
      "robloxUrl": "https://www.roblox.com/games/123"
    },
    "creator": {
      "username": "creator",
      "isVerified": true,
      "subscriptionTier": "pro",
      "isPro": true,
      "avatarUrl": null
    },
    "executors": [
      {
        "id": "…",
        "name": "Solara",
        "platforms": [
          "Windows"
        ],
        "imageUrl": null
      }
    ]
  }
}
```

### GET /v1/trending

Same two sections as the /scripts/trending page: rising (24h analytics signals) and trending (48h pageviews).

Parameters:
- `htmlDescription` (boolean, default false): Return descriptions as raw HTML instead of stripped plain text.
- `includeScript` (boolean, default false): Inline raw Lua source in the response. Default off on list/search/trending. Use rawScript URL instead. Always on for script detail.

- rising: up to 8 newer scripts gaining traction (24h analytics, ≤21 days old).
- trending: up to 12 most-viewed scripts in the last 48 hours.

Example:
`https://api.rscripts.net/v1/trending`

Example response:
```json
{
  "success": true,
  "data": {
    "rising": [
      {
        "title": "Rising script",
        "slug": "rising-example",
        "rawScript": "https://rscripts.net/raw/…"
      }
    ],
    "trending": [
      {
        "title": "Hot script",
        "slug": "trending-example",
        "rawScript": "https://rscripts.net/raw/…"
      }
    ]
  }
}
```

## Error codes

- VALIDATION_ERROR (400): bad query params
- UNAUTHORIZED (401): missing or invalid API key
- NOT_FOUND (404): route or script missing
- RATE_LIMITED (429): too many requests
- INTERNAL_ERROR (500): server error
- SERVICE_UNAVAILABLE (503): search unavailable

## Script object (summary)

id, title, slug, description, views, likes, dislikes, createdAt, lastUpdatedAt, lastBumpedAt,
isPatched, isMobileReady, isKeySystem, keySystemUrl, isPaid, discordUrl, youtubeUrl,
rawScript, script, imageUrl, game, creator, executors, risk

High-risk scripts are removed from public results and held for manual review.