Documentation

Everything you need to call Lightreel from your own code.

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).

The more context you give in your questions, the better the responses will be.

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": "..."
  }
}

In your response_fields descriptions, include what the field is supposed to be and any supporting context / evidence you want.

If you want multiple attributes about the same items, include multiple arrays and say in the descriptions that they should be index-aligned:

Request

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

Response

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

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].