Lightreel

https://lightreel.ai/docs
Admin
Lightreel is an AI API and platform that allows developers to search and extract social media...
Tokens:5,788
Snippets:38
Trust Score:5.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Discover Hooks Response Example

Source: https://lightreel.ai/docs/examples/discover-hooks

Shows the structure of the returned data, containing the conversation ID and the arrays of hooks, video URLs, and app names.

```json
{
  "conversationId": "...",
  "answer": {
    "hooks": [
      "I gave my phone a bouncer. He charges 20 pushups at the door",
      "POV: your screen time app just made you earn Instagram"
    ],
    "videos": ["https://www.tiktok.com/@lockedinapp/video/74...", "https://www.tiktok.com/@gymtoksaru/video/74..."],
    "app_names": ["Lockout", "ScreenFit"]
  }
}
```

--------------------------------

### Request multiple index-aligned fields

Source: https://lightreel.ai/docs

Example request body for retrieving multiple related arrays.

```json
{
  "question": "Find me fitness creators who post workout vlogs and are open to brand deals",
  "response_fields": {
    "handles":      { "type": "array", "description": "One creator handle per entry" },
    "descriptions": { "type": "array", "description": "What the creator posts, index-aligned with handles" },
    "top_videos":   { "type": "array", "description": "Their best performing video from the last 2 weeks, index-aligned with handles" }
  }
}
```

--------------------------------

### Micro-influencer search response

Source: https://lightreel.ai/docs/examples/find-micro-influencers

Example output containing creator handles, descriptions, and brand partnership history.

```json
{
  "conversationId": "...",
  "answer": {
    "handles": ["@buildwithmarco", "@thecodingpa", "@lofidev"],
    "descriptions": [
      "Day-in-the-life builds of indie iOS apps",
      "Explains dev tools in 30-second reels",
      "Codes side projects on camera with lo-fi audio"
    ],
    "brand_partnerships": ["Raycast", "", "Notion, Warp"]
  }
}
```

--------------------------------

### GET /v1/chats

Source: https://lightreel.ai/docs

Lists the latest 50 API chat sessions.

```APIDOC
## GET /v1/chats

### Description
Returns a list of the user's latest 50 API chat sessions.

### Method
GET

### Endpoint
https://api.lightreel.ai/v1/chats

### Response
#### Success Response (200)
- **chats** (array) - A list of recent conversation objects.
```

--------------------------------

### Fetch chat transcripts

Source: https://lightreel.ai/docs

Retrieve a single chat or list recent chats using GET requests.

```bash
# fetch one transcript
curl https://api.lightreel.ai/v1/chat/CONVERSATION_ID \
  -H "Authorization: Bearer lr_live_xxx"

# list your latest 50 chats
curl https://api.lightreel.ai/v1/chats \
  -H "Authorization: Bearer lr_live_xxx"
```

--------------------------------

### GET /v1/chat/:id

Source: https://lightreel.ai/docs

Retrieves a specific past chat transcript by its conversation ID.

```APIDOC
## GET /v1/chat/:id

### Description
Retrieves the full transcript of a past chat session.

### Method
GET

### Endpoint
https://api.lightreel.ai/v1/chat/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the conversation.

### Response
#### Success Response (200)
- **conversationId** (string) - The ID of the conversation.
- **createdAt** (string) - Timestamp of creation.
- **updatedAt** (string) - Timestamp of last update.
- **messages** (array) - List of message objects containing role, question, and answer.
```

--------------------------------

### POST /discover-hooks

Source: https://lightreel.ai/docs/examples/discover-hooks

Retrieves a list of hooks, video URLs, and app names based on a natural language query about similar products.

```APIDOC
## POST /discover-hooks

### Description
Retrieves hooks similar products are currently using, including the source video and the app name.

### Request Body
- **question** (string) - Required - A natural language query describing the app and the type of hooks to find.
- **response_fields** (object) - Required - Defines the expected structure of the returned data.

### Request Example
{
  "question": "I am building a screen time app that makes you do pushups whenever you want to use your phone. Find hooks that similar screen time apps are using, ideally from the last 7 days.",
  "response_fields": {
    "hooks": { "type": "array", "description": "The hook line, one per video" },
    "videos": { "type": "array", "description": "URL of the video the hook is from, index-aligned with hooks" },
    "app_names": { "type": "array", "description": "The screen time app being promoted, index-aligned with hooks" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - Unique identifier for the conversation.
- **answer** (object) - Contains the requested hook data.
  - **hooks** (array) - The hook lines.
  - **videos** (array) - URLs of the source videos.
  - **app_names** (array) - Names of the apps being promoted.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "hooks": [
      "I gave my phone a bouncer. He charges 20 pushups at the door",
      "POV: your screen time app just made you earn Instagram"
    ],
    "videos": ["https://www.tiktok.com/@lockedinapp/video/74...", "https://www.tiktok.com/@gymtoksaru/video/74..."],
    "app_names": ["Lockout", "ScreenFit"]
  }
}
```

--------------------------------

### Request account critique

Source: https://lightreel.ai/docs/examples/score-and-critique-accounts

Submit a URL or handle to receive structured feedback formatted as an array of strings.

```json
{
  "question": "https://www.instagram.com/hoopify see if you have any feedback for these accounts",
  "response_fields": {
    "feedback": { "type": "array", "description": "One entry per account formatted as handle | feedback" }
  }
}
```

--------------------------------

### Find Trending Topics

Source: https://lightreel.ai/docs/examples/find-trending-topics

Queries for recent environmental-tech news occurrences based on a natural language question and returns associated video URLs and issue descriptions.

```APIDOC
## POST /find-trending-topics

### Description
Monitor a niche for new coverage by providing a natural language query. The system returns occurrences found within a specific time window, tagged by issue.

### Request Body
- **question** (string) - Required - A natural language description of the niche and time window to monitor.
- **response_fields** (object) - Required - Defines the structure of the returned data.
  - **video_urls** (array) - Required - One video per entry.
  - **environmental_issues** (array) - Required - The issue the video covers, index-aligned with video_urls.

### Request Example
{
  "question": "I run a podcast about environmental events — think pollution in new cities, datacenters being created, tech-adjacent news. Find every occurrence of environmental-tech news in the last 2 days.",
  "response_fields": {
    "video_urls": { "type": "array", "description": "One video per entry" },
    "environmental_issues": { "type": "array", "description": "The issue the video covers, index-aligned with video_urls" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - Unique identifier for the conversation.
- **answer** (object) - The requested data containing video_urls and environmental_issues.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "video_urls": ["https://www.tiktok.com/@climatewatch/video/74...", "https://www.tiktok.com/@gridnews/video/74..."],
    "environmental_issues": [
      "New hyperscale datacenter straining the local water supply in Phoenix",
      "Microplastic levels spiking in a newly industrialized river delta"
    ]
  }
}
```

--------------------------------

### POST /find-winning-videos

Source: https://lightreel.ai/docs/examples/find-winning-videos

Retrieves a list of winning videos for a specified account along with explanations for their performance.

```APIDOC
## POST /find-winning-videos

### Description
Retrieves every video that recently started working for an account, including an explanation of what changed to improve performance.

### Request Body
- **question** (string) - Required - A natural language query specifying the account and the request for performance explanations.
- **response_fields** (object) - Required - Defines the structure of the expected response.

### Request Example
{
  "question": "get me every video that started working for @hoopify and explain what they started doing differently",
  "response_fields": {
    "videos": { "type": "array", "description": "Include the URLs followed by the explanation for why it started doing well" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - Unique identifier for the conversation.
- **answer** (object) - Contains the requested video data.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "videos": [
      "https://www.tiktok.com/@account/video/7384... — switched to faster hooks and native captions",
      "https://www.tiktok.com/@account/video/7390... — leaned into trending audio with a bold on-screen claim"
    ]
  }
}
```

--------------------------------

### POST /score-and-critique

Source: https://lightreel.ai/docs/examples/score-and-critique-accounts

Submits account handles for analysis and returns structured feedback.

```APIDOC
## POST /score-and-critique

### Description
Get structured feedback on any account, with one entry per handle formatted as requested.

### Request Body
- **question** (string) - Required - The URL or handle of the account to critique.
- **response_fields** (object) - Required - Schema definition for the expected feedback format.

### Request Example
{
  "question": "https://www.instagram.com/hoopify see if you have any feedback for these accounts",
  "response_fields": {
    "feedback": { "type": "array", "description": "One entry per account formatted as handle | feedback" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - Unique identifier for the conversation.
- **answer** (object) - The structured feedback results.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "feedback": [
      "@hoopify | strong hooks, but post more consistently and lean into faster cuts",
      "@dunkdaily | great editing, captions are too small and CTAs are missing"
    ]
  }
}
```

--------------------------------

### Request trending topics query

Source: https://lightreel.ai/docs/examples/find-trending-topics

Define the search question and specify the required response fields for video URLs and environmental issues.

```json
{
  "question": "I run a podcast about environmental events — think pollution in new cities, datacenters being created, tech-adjacent news. Find every occurrence of environmental-tech news in the last 2 days.",
  "response_fields": {
    "video_urls":           { "type": "array", "description": "One video per entry" },
    "environmental_issues": { "type": "array", "description": "The issue the video covers, index-aligned with video_urls" }
  }
}
```

--------------------------------

### Discover Hooks Request Schema

Source: https://lightreel.ai/docs/examples/discover-hooks

Defines the input structure for querying hooks, including the user's prompt and the expected response fields.

```json
{
  "question": "I am building a screen time app that makes you do pushups whenever you want to use your phone. Find hooks that similar screen time apps are using, ideally from the last 7 days.",
  "response_fields": {
    "hooks":     { "type": "array", "description": "The hook line, one per video" },
    "videos":    { "type": "array", "description": "URL of the video the hook is from, index-aligned with hooks" },
    "app_names": { "type": "array", "description": "The screen time app being promoted, index-aligned with hooks" }
  }
}
```

--------------------------------

### Request structured output

Source: https://lightreel.ai/docs

Include response_fields in the request body to receive structured JSON instead of prose.

```bash
curl -X POST https://api.lightreel.ai/v1/chat \
  -H "Authorization: Bearer lr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "find me the top fitness hooks this week",
    "response_fields": {
      "hooks":   { "type": "array",  "description": "the hook lines" },
      "summary": { "type": "string", "description": "one-paragraph recap" }
    }
  }'
```

--------------------------------

### Receive Ad Inspiration Response

Source: https://lightreel.ai/docs/examples/meta-ad-inspiration

JSON structure returned by the agent containing trending ad formats, reference URLs, and reasoning for their applicability.

```json
{
  "conversationId": "...",
  "answer": {
    "formats": [
      "Fake street interview where the interviewer keeps getting distracted by the product",
      "Before/after where the 'after' is absurdly minor but played completely straight"
    ],
    "video_urls": ["https://www.tiktok.com/@snackfluent/video/74...", "https://www.tiktok.com/@gymbrolabs/video/74..."],
    "why_applicable": [
      "Started spiking 4 days ago — the interruption showcases packaging without feeling like an ad",
      "Same before/after energy as your past winners, but the deadpan absurdity is the part that's newly working"
    ]
  }
}
```

--------------------------------

### Ask a question via cURL

Source: https://lightreel.ai/docs

Send a POST request to the chat endpoint to receive an answer.

```bash
curl -X POST https://api.lightreel.ai/v1/chat \
  -H "Authorization: Bearer lr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "question": "find me the top fitness hooks this week" }'
```

--------------------------------

### Creator contact information response

Source: https://lightreel.ai/docs/examples/pull-creator-contacts

JSON response containing the conversation ID and the requested list of creator emails.

```json
{
  "conversationId": "...",
  "answer": {
    "emails": [
      "@bruindays | jordan.lee@ucla.edu",
      "@berkeleymornings | mia.k@berkeley.edu"
    ]
  }
}
```

--------------------------------

### Account critique response

Source: https://lightreel.ai/docs/examples/score-and-critique-accounts

The API returns an object containing a conversation ID and an array of feedback strings mapped to the requested handles.

```json
{
  "conversationId": "...",
  "answer": {
    "feedback": [
      "@hoopify | strong hooks, but post more consistently and lean into faster cuts",
      "@dunkdaily | great editing, captions are too small and CTAs are missing"
    ]
  }
}
```

--------------------------------

### Winning video response structure

Source: https://lightreel.ai/docs/examples/find-winning-videos

The expected JSON response containing a list of video URLs paired with explanations for their performance.

```json
{
  "conversationId": "...",
  "answer": {
    "videos": [
      "https://www.tiktok.com/@account/video/7384... — switched to faster hooks and native captions",
      "https://www.tiktok.com/@account/video/7390... — leaned into trending audio with a bold on-screen claim"
    ]
  }
}
```

--------------------------------

### Creator contact information request

Source: https://lightreel.ai/docs/examples/pull-creator-contacts

JSON payload to query creators based on specific profile criteria and requested response fields.

```json
{
  "question": "Find me creators who are tier 1 (UCLA / Berkeley) college students making day in the life videos",
  "response_fields": {
    "emails": { "type": "array", "description": "One per creator formatted as handle | email" }
  }
}
```

--------------------------------

### POST /v1/chat

Source: https://lightreel.ai/docs

Sends a question to the Lightreel assistant. You can provide a conversation_id to continue an existing chat or define response_fields for structured JSON output.

```APIDOC
## POST /v1/chat

### Description
Sends a question to the Lightreel assistant. Optionally provide a conversation_id to continue a chat or response_fields to receive structured data.

### Method
POST

### Endpoint
https://api.lightreel.ai/v1/chat

### Request Body
- **question** (string) - Required - The question to ask the assistant.
- **conversation_id** (string) - Optional - The ID of an existing conversation to continue.
- **response_fields** (object) - Optional - A schema defining the structure of the returned answer. Supports up to 5 fields of type "string" or "array".

### Request Example
{
  "question": "find me the top fitness hooks this week",
  "response_fields": {
    "hooks": { "type": "array", "description": "the hook lines" },
    "summary": { "type": "string", "description": "one-paragraph recap" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - The ID of the conversation.
- **answer** (string/object) - The assistant's response in prose or structured format based on request_fields.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "hooks": ["...", "..."],
    "summary": "..."
  }
}
```

--------------------------------

### Structured output response

Source: https://lightreel.ai/docs

The JSON response format when using response_fields.

```json
{
  "conversationId": "...",
  "answer": {
    "hooks": ["...", "..."],
    "summary": "..."
  }
}
```

--------------------------------

### Request winning video data

Source: https://lightreel.ai/docs/examples/find-winning-videos

Define the query for identifying high-performing videos and the expected response format.

```json
{
  "question": "get me every video that started working for @hoopify and explain what they started doing differently",
  "response_fields": {
    "videos": { "type": "array", "description": "Include the URLs followed by the explanation for why it started doing well" }
  }
}
```

--------------------------------

### Response trending topics data

Source: https://lightreel.ai/docs/examples/find-trending-topics

The API returns a conversation ID and an object containing the requested video URLs and their corresponding environmental issues.

```json
{
  "conversationId": "...",
  "answer": {
    "video_urls": ["https://www.tiktok.com/@climatewatch/video/74...", "https://www.tiktok.com/@gridnews/video/74..."],
    "environmental_issues": [
      "New hyperscale datacenter straining the local water supply in Phoenix",
      "Microplastic levels spiking in a newly industrialized river delta"
    ]
  }
}
```

--------------------------------

### Transcript response format

Source: https://lightreel.ai/docs

The structure of a returned chat transcript.

```json
{
  "conversationId": "...",
  "createdAt": "...",
  "updatedAt": "...",
  "messages": [
    { "role": "user", "question": "..." },
    { "role": "assistant", "answer": "..." }
  ]
}
```

--------------------------------

### Micro-influencer search request

Source: https://lightreel.ai/docs/examples/find-micro-influencers

Defines the search criteria and expected response fields for identifying tech micro-influencers.

```json
{
  "question": "I am building an AI coding startup that lets people code from their Apple Watch. I need tech micro influencers with under 50,000 followers who post on Instagram — be very broad and find as many as you can. I'm focusing on breadth over depth here.",
  "response_fields": {
    "handles":            { "type": "array", "description": "One creator handle per entry" },
    "descriptions":       { "type": "array", "description": "What the creator posts, index-aligned with handles" },
    "brand_partnerships": { "type": "array", "description": "Brands they have partnered with, index-aligned with handles — leave \"\" if none" }
  }
}
```

--------------------------------

### Chat response format

Source: https://lightreel.ai/docs

The expected JSON response structure for a chat request.

```json
{
  "conversationId": "...",
  "answer": "Here are the top hooks this week..."
}
```

--------------------------------

### Request Meta Ad Inspiration

Source: https://lightreel.ai/docs/examples/meta-ad-inspiration

JSON payload to query the agent for ad creative inspiration, including specific brand context and desired response fields.

```json
{
  "question": "I'm creating a D2C protein muffin company. We sell muffins to consumers that have 20 grams of protein, and we mainly advertise through Meta ads. What has worked well for us in the past is videos showing extremely skinny people doing before and afters, specifically if there's some level of humor or an absurd background element. I don't need exact copies of this — just general video inspiration or hooks that are really breaking out right now on TikTok that can be used as inspiration. For context, I'm the head of marketing and have A LOT of context about the current social media landscape — surface really nuanced formats and details that JUST started working so I can use them for future ads. You're not constrained to just this — if you find some format that might generally be useful that I can use, show it to me too.",
  "response_fields": {
    "formats":        { "type": "array", "description": "The format or hook, described specifically enough to brief an editor" },
    "video_urls":     { "type": "array", "description": "A breakout example of the format, index-aligned with formats" },
    "why_applicable": { "type": "array", "description": "Why this works for a D2C protein brand, index-aligned with formats" }
  }
}
```

--------------------------------

### POST /find-micro-influencers

Source: https://lightreel.ai/docs/examples/find-micro-influencers

Queries the system to identify micro-influencers based on a provided prompt and requested data fields.

```APIDOC
## POST /find-micro-influencers

### Description
Finds niche creators under a follower cap based on a natural language query. Returns creator handles, descriptions, and brand partnerships.

### Method
POST

### Request Body
- **question** (string) - Required - A natural language description of the target micro-influencers and the desired breadth of the search.
- **response_fields** (object) - Required - Defines the structure of the returned data.
  - **handles** (array) - Required - One creator handle per entry.
  - **descriptions** (array) - Required - What the creator posts, index-aligned with handles.
  - **brand_partnerships** (array) - Required - Brands they have partnered with, index-aligned with handles.

### Request Example
{
  "question": "I am building an AI coding startup that lets people code from their Apple Watch. I need tech micro influencers with under 50,000 followers who post on Instagram — be very broad and find as many as you can. I'm focusing on breadth over depth here.",
  "response_fields": {
    "handles": { "type": "array", "description": "One creator handle per entry" },
    "descriptions": { "type": "array", "description": "What the creator posts, index-aligned with handles" },
    "brand_partnerships": { "type": "array", "description": "Brands they have partnered with, index-aligned with handles — leave \"\" if none" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - Unique identifier for the conversation.
- **answer** (object) - The requested creator data.
  - **handles** (array) - List of creator handles.
  - **descriptions** (array) - List of creator descriptions.
  - **brand_partnerships** (array) - List of brand partnerships.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "handles": ["@buildwithmarco", "@thecodingpa", "@lofidev"],
    "descriptions": [
      "Day-in-the-life builds of indie iOS apps",
      "Explains dev tools in 30-second reels",
      "Codes side projects on camera with lo-fi audio"
    ],
    "brand_partnerships": ["Raycast", "", "Notion, Warp"]
  }
}
```

--------------------------------

### POST /pull-creator-contacts

Source: https://lightreel.ai/docs/examples/pull-creator-contacts

Retrieves contact information for creators matching a natural language profile query.

```APIDOC
## POST /pull-creator-contacts

### Description
Finds creators matching a specific profile description and returns their contact information.

### Request Body
- **question** (string) - Required - A natural language description of the creator profile to search for.
- **response_fields** (object) - Required - Defines the fields to return, such as emails.

### Request Example
{
  "question": "Find me creators who are tier 1 (UCLA / Berkeley) college students making day in the life videos",
  "response_fields": {
    "emails": { "type": "array", "description": "One per creator formatted as handle | email" }
  }
}

### Response
#### Success Response (200)
- **conversationId** (string) - The ID of the conversation.
- **answer** (object) - The requested contact information.

#### Response Example
{
  "conversationId": "...",
  "answer": {
    "emails": [
      "@bruindays | jordan.lee@ucla.edu",
      "@berkeleymornings | mia.k@berkeley.edu"
    ]
  }
}
```

--------------------------------

### Multiple index-aligned fields response

Source: https://lightreel.ai/docs

The JSON response containing index-aligned arrays.

```json
{
  "conversationId": "...",
  "answer": {
    "handles": ["@liftwithlena", "@dailypushups"],
    "descriptions": ["Strength vlogs with form breakdowns", "30-day challenge shorts with daily progress"],
    "top_videos": ["https://www.tiktok.com/@liftwithlena/video/7401...", "https://www.tiktok.com/@dailypushups/video/7398..."]
  }
}
```

--------------------------------

### Error response format

Source: https://lightreel.ai/docs

The structure returned when an API request fails.

```json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}
```
Tokens:
Raw