Pureframe AI API Documentation

Results are grouped by video. Each video in data carries a list of matching segments:

{
  "video_id": "vid_abc123",
  "filename": "footage.mp4",
  "collection_id": "col_xyz",
  "status": "done",
  "segments": [
    {
      "timestamp_start": 42.5,
      "timestamp_end": 47.0,
      "score": 0.91,
      "type": "frame",
      "text_content": "Hey everyone, welcome back!",
      "bbox": null,
      "video_url": "https://...",
      "thumbnail_url": "https://...",
      "hidden": false,
      "rank": 0
    }
  ]
}

Segment fields

Field	Type	Description
`timestamp_start` / `timestamp_end`	number	Segment boundaries in seconds
`score`	number	Relevance from 0 to 1
`type`	string	Which signal matched: `frame`, `transcript`, `scene`, or `ocr`. See Combined Queries
`text_content`	string \| null	Transcribed speech or caption text, if this segment has any
`bbox`	object \| null	Bounding box within the frame, present on some `ocr` matches
`video_url`	string \| null	Presigned URL to stream the full video (valid ~1 hour)
`thumbnail_url`	string \| null	Presigned URL to the matched frame image (valid ~1 hour)
`hidden`	boolean	Whether you’ve marked this segment hidden via search feedback
`rank`	integer	Position in this page of results: use it when logging a click, see below

Video group fields

Field	Type	Description
`video_id`	string	ID of the matched video
`filename`	string \| null	Original uploaded filename
`collection_id`	string \| null	Collection this video belongs to
`status`	string \| null	Processing status of the video
`segments`	array	Matching segments, see above

Response meta

{
  "meta": {
    "total": 12,
    "page": 1,
    "per_page": 10,
    "search_id": "a1b2c3d4-...",
    "facets": { "scene_labels": { "whiteboard": 4, "outdoor": 2 } }
  }
}

search_id identifies the search. Include it when you log a result click. facets is present when the response includes scene-label counts that you can use in a filter interface.

Logging a click

Log the result a user opened to help improve search relevance.

curl -X POST https://api.pureframe.ai/v1/search/click \
  -H "Authorization: Bearer pf_..." \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "a1b2c3d4-...",
    "video_id": "vid_abc123",
    "timestamp_start": 42.5,
    "rank": 0,
    "result_type": "frame"
  }'

Feedback

Mark a segment up or down for a query. A downvote hides that segment from future searches for the same account.

curl -X POST https://api.pureframe.ai/v1/search/feedback \
  -H "Authorization: Bearer pf_..." \
  -F "video_id=vid_abc123" \
  -F "timestamp_start=42.5" \
  -F "signal=down" \
  -F "query=pricing objection"

signal accepts up or down. Feedback requires an API key associated with an active account user.