> **Building with AI coding agents?** Install the authstack plugin with one command. This equips your agent with accurate Scalekit implementation patterns.
>
> **Recommended** (the `-y` flags skip prompts, so the command runs without an interactive terminal):
> ```bash
> npx -y @scalekit-inc/cli setup -y
> ```
>
> Global:
> ```bash
> npm install -g @scalekit-inc/cli
> scalekit setup -y
> ```
>
> Supports Claude Code, Cursor, GitHub Copilot, Codex + skills for other Agent Skills-compatible agents in `~/.agents/skills`.
> Skills: integrate-agentkit, implement-saaskit, add-mcp-oauth, implement-sso, implement-scim.
> [Full setup guide](https://docs.scalekit.com/dev-kit/build-with-ai/)

---

# Connect AI agents to Spotlightr

The Spotlightr connector lets your AI agent act in each user's Spotlightr account. Each user connects their own Spotlightr API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 15 tools.

**Authentication:** API Key
**Categories:** Media, Marketing
**Tools:** 15: 6 read, 8 write, 1 destructive
**Users sign in with:** API key
**Built by:** Scalekit connector
**Try it:** [Playground in the Scalekit dashboard](https://app.scalekit.com/ws/signup?sk_intent=playground&provider=SPOTLIGHTR)

## Setup

1. ### Install the SDK

   **Node.js**

   ```bash
   npm install @scalekit-sdk/node dotenv
   ```

   **Python**

   ```bash
   pip install scalekit-sdk-python python-dotenv
   ```

2. ### Set your credentials

   Add your Scalekit credentials to your `.env` file. Find values in **[app.scalekit.com](https://app.scalekit.com)** > **Developers** > **API Credentials**.

   ```sh title=".env"
   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>
   ```

3. ### Create the Spotlightr connection

   In **AgentKit > Connections**, create a Spotlightr connection. The name you give it is the `connection_name` your code passes. See [Configure connections](/agentkit/connections/).

4. ### Authorize a user and make your first call

   **Node.js** (`quickstart.mts`)

   ```typescript
   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   import { createInterface } from 'node:readline/promises'

   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENVIRONMENT_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions

   const connector = 'spotlightr'
   const identifier = 'user_123'

   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Spotlightr:', link)
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   await rl.question('Press Enter after authorizing...')
   rl.close()

   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'spotlightr_domains_list',
     toolInput: {},
   })
   console.log(result)
   ```

   ```bash
   npx tsx quickstart.mts
   ```

   **Python** (`quickstart.py`)

   ```python
   import os
   from scalekit import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()

   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions

   connection_name = "spotlightr"
   identifier = "user_123"

   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Spotlightr:", link_response.link)
   input("Press Enter after authorizing...")

   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="spotlightr_domains_list",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)
   ```

   ```bash
   python quickstart.py
   ```

   Each user opens the link once and enters their Spotlightr credentials there. See [Authorize a user](/agentkit/tools/authorize/) for the full flow and statuses.

## Tools

Pass the exact name to `execute_tool`, with an input like each tool's example. To ask for a tool that's missing, use the [request form](https://scalekitsupport.portal.usepylon.com/forms/request-a-connector-tool).

**Node.js**

```typescript
const result = await actions.executeTool({
  toolName: 'spotlightr_domains_list',
  toolInput: {},
  connector: 'spotlightr',
  identifier: 'user_123',
})
```

**Python**

```python
result = actions.execute_tool(
    tool_name="spotlightr_domains_list",
    tool_input={},
    connection_name="spotlightr",
    identifier="user_123",
)
```

`result.data` is the app's response as JSON, and `result.execution_id` (`executionId` in Node.js) is the ID of the call.

### `spotlightr_domains_list`

List Whitelisted Domains · Read-only

List the domains whitelisted to embed your Spotlightr videos.
Returns the whitelisted domains.
Use spotlightr_domain_add to allow another domain.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `spotlightr_groups_list`

List Projects · Read-only

List the projects (video groups) in your Spotlightr account.
Returns projects with their id and name.
Use this to find a project ID for spotlightr_videos_list or spotlightr_video_create.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs: none.

Example input: `{}`

### `spotlightr_top_videos_list`

List Top Videos · Read-only

List your most-viewed videos over a recent period.
Returns the top videos with their view statistics.
Use this for a quick performance overview. Use spotlightr_video_metrics_get for one video.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `days` (`integer`, optional): Reporting period in days. Spotlightr defaults to 30. Example: 30.
- `total` (`integer`, optional): Number of top videos to return. Spotlightr defaults to 3. Example: 5.

Example input: `{}`

### `spotlightr_video_metrics_get`

Get Video Metrics · Read-only

Get analytics for one video.
Returns loads, plays, playRate, watched (average percent watched), completitionRate and shares.
Use spotlightr_video_views_list for individual views.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `video_id` (`integer`, required): Numeric Spotlightr video ID (the decoded ID, not the base64 string in watch URLs). Get it from spotlightr_videos_list. Example: 1352090.

Example input: `{"video_id":1352090}`

### `spotlightr_video_views_list`

List Video Views · Read-only

List the individual views of a video, optionally for one known viewer or only views where something was watched.
Returns view records with viewer and watch-progress details.
Use spotlightr_video_metrics_get for totals.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `video_id` (`integer`, required): Numeric Spotlightr video ID (the decoded ID, not the base64 string in watch URLs). Get it from spotlightr_videos_list. Example: 1352090.
- `all_views` (`boolean`, optional): true to return all views without pagination. Example: false.
- `custom_viewer_id` (`string`, optional): ID or email of a known viewer to return views for. Example: jane@example.com.
- `only_watched` (`boolean`, optional): true to return only views with more than 1 percent watched. Example: true.

Example input: `{"video_id":1352090}`

### `spotlightr_videos_list`

List Videos · Read-only

List the videos in your Spotlightr account, optionally narrowed to one video or one project.
Returns video records with their id, name, project (videoGroup), URLs and settings.
Use this to find video IDs. Use spotlightr_video_metrics_get for a video's analytics.

Read only: yes. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `video_group` (`integer`, optional): Return only videos in this project (group) ID, from spotlightr_groups_list. Example: 4521.
- `video_id` (`integer`, optional): Return only this video. Example: 1352090.

Example input: `{}`

### `spotlightr_access_expire`

Expire Access Record · Write

Expire a student's course access record.
Returns the update result.
Use this to revoke a student's access to a course.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `expire` (`integer`, required): Set to 1 to expire the record. Example: 1. One of: `1`.
- `id` (`integer`, required): Access record ID. Example: 55021.

Example input: `{"expire":1,"id":55021}`

### `spotlightr_domain_add`

Add Whitelisted Domain · Write

Add a domain to the list allowed to embed your Spotlightr videos.
Returns the result.
Use spotlightr_domains_list to see the current list.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `domain` (`string`, required): Domain to whitelist, without protocol. Example: example.com.

Example input: `{"domain":"<domain>"}`

### `spotlightr_gallery_code_expire`

Expire Gallery Access Code · Write

Expire a gallery access code so it can no longer be used.
Returns the update result.
Use this to revoke a shared gallery code.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `expires` (`integer`, required): Set to 1 to expire the code. Example: 1. One of: `1`.
- `id` (`integer`, required): Access code ID. Example: 3307.

Example input: `{"expires":1,"id":3307}`

### `spotlightr_group_create`

Create Project · Write

Create a new project (video group) in Spotlightr.
Returns the created project.
Use its ID as video_group when creating or listing videos.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `name` (`string`, required): Name of the new project. Example: Onboarding videos.

Example input: `{"name":"<name>"}`

### `spotlightr_student_create`

Create Course Student · Write

Create a student login for a Spotlightr course or gallery, with optional expiry and unlock limits.
Returns the created student access.
Use this to grant a person access to a protected course or gallery.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `email` (`string`, required): Student's email address. Example: student@example.com.
- `expires` (`string`, required): Expiry date as YYYY-MM-DD, or 0000-00-00 for none. Example: 0000-00-00.
- `id` (`integer`, required): Course or gallery ID. Example: 8812.
- `never` (`integer`, required): 1 if access never expires, 0 otherwise. Example: 1. One of: `0`, `1`.
- `password` (`string`, required): Password the student signs in with. Example: S3cure-pass-2026.
- `time` (`integer`, required): Time limit for access, or 0 for none. Example: 0.
- `unlocks` (`integer`, required): Number of unlocks allowed, or 0 for no limit. Example: 0.

Example input: `{"email":"<email>","expires":"<expires>","id":8812,"never":1,"password":"<password>","time":0,"unlocks":0}`

### `spotlightr_video_create`

Create Video From URL · Write

Create a Spotlightr video from a link (YouTube, Vimeo, Google Drive, Dropbox or a direct file URL), optionally copying another video's player settings.
Returns the created video's watch URL.
Use this to add a hosted or linked video. Uploading a file from disk is not supported by this tool.

Read only: no. Destructive: no. Idempotent (safe to retry): no.

Inputs:

- `custom_s3` (`integer`, required): 0 to use Spotlightr storage, or the ID of a custom S3 integration. Example: 0.
- `name` (`string`, required): Name of the new video. Example: Product demo.
- `url` (`string`, required): Link to the video source: YouTube, Vimeo, Google Drive, Dropbox or a direct video URL. Example: https://www.youtube.com/watch?v=dQw4w9WgXcQ.
- `create` (`integer`, optional): 1 to create the video, 0 for a debug dry run. Example: 1. One of: `0`, `1`.
- `hls` (`integer`, optional): 1 to encode the video as secure HLS, 0 to leave it unencoded. Example: 1. One of: `0`, `1`.
- `player_settings` (`integer`, optional): ID of one of your videos (decoded, not base64) whose player settings to copy. Default settings are used if omitted. Example: 1352090.
- `video_group` (`integer`, optional): Project (group) ID to put the video in, from spotlightr_groups_list. Example: 4521.

Example input: `{"custom_s3":0,"name":"<name>","url":"<url>"}`

### `spotlightr_video_settings_update`

Update Video Player Settings · Write

Update individual player settings of a video. Only the keys you send change.
Returns the update result.
Use this to change the player (for example autoplay or colors) without editing other settings.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): Video ID (decoded number, not the base64 string). Example: 1352090.
- `settings` (`string`, required): JSON object, as a string, holding only the player setting keys to change. Example: {"autoplay": true}

Example input: `{"id":1352090,"settings":"<settings>"}`

### `spotlightr_video_source_update`

Replace Video Source · Write

Replace the source of an existing Spotlightr video with a new URL, keeping its ID, settings and analytics.
Returns the update result.
Use this to swap the underlying file or link of a published video.

Read only: no. Destructive: no. Idempotent (safe to retry): yes.

Inputs:

- `id` (`integer`, required): ID of the video whose source to replace. Example: 1352090.
- `url` (`string`, required): New source URL for the video. Example: https://vimeo.com/76979871.

Example input: `{"id":1352090,"url":"<url>"}`

### `spotlightr_video_delete`

Delete Videos · Destructive

Permanently delete one or more videos from your Spotlightr account.
Returns the deletion result.
Get video IDs from spotlightr_videos_list.

Read only: no. Destructive: yes. Idempotent (safe to retry): yes.

Inputs:

- `ids` (`string`, required): IDs of the videos to delete, as a JSON array of numbers. Example: [1234,5678]

Example input: `{"ids":"<ids>"}`

## Related

Other Media connectors ([all 65](/agentkit/connectors/?category=media)):

- [Spotify](/agentkit/connectors/spotify/): Scalekit connector, OAuth, 47 tools
- [Reddit](/agentkit/connectors/reddit/): Scalekit connector, OAuth, 105 tools
- [Diarize](/agentkit/connectors/diarize/): Scalekit connector, Access token, 3 tools


---

## More Scalekit documentation

| Resource | What it contains | When to use it |
|----------|-----------------|----------------|
| [/llms.txt](/llms.txt) | Structured index with routing hints per product area | Start here — find which documentation set covers your topic before loading full content |
| [/llms-full.txt](/llms-full.txt) | Complete documentation for all Scalekit products in one file | Use when you need exhaustive context across multiple products or when the topic spans several areas |
| [sitemap-0.xml](https://docs.scalekit.com/sitemap-0.xml) | Full URL list of every documentation page | Use to discover specific page URLs you can fetch for targeted, page-level answers |
