API documentation

Ask Lightreel questions from your code via api.lightreel.ai. Official SDKs are available for Node.js (npm install lightreel) and Python (pip install lightreel).

Ask a question

POST /v1/chat. Send a question. Add conversation_id to continue a chat, or response_fields for structured output.

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

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

Structured output

Add response_fields to get JSON back instead of prose. Requested fields come back nested inside answer.

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" }
    }
  }'

Response

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

You can also specify the style of response

Request

{
  "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

{
  "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"
    ]
  }
}

Have it score and critique accounts

Request

{
  "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

{
  "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"
    ]
  }
}

Pull contact info for creators

Request

{
  "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

{
  "conversationId": "...",
  "answer": {
    "emails": [
      "@bruindays | [email protected]",
      "@berkeleymornings | [email protected]"
    ]
  }
}
  • Up to 5 fields.
  • Types are "string" or "array" only.
  • Only requested keys are returned.

Fetch a transcript

GET /v1/chat/:id pulls back a past chat. GET /v1/chats lists your latest 50 API chats.

# 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"

Response

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

Errors

Failures return a non-2xx status with an error body. The SDKs raise a LightreelError carrying .status and .type.

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

Usage

  • Requests can take several minutes to complete. Set a generous timeout on your client so the request isn’t terminated before it returns.
  • API requests draw from your normal usage, the same as the dashboard.
  • Team seats do not increase API limits.

Have any questions? Email [email protected].