Complete reference for RareSift's REST API endpoints, authentication, and response formats
All API requests should be made to this base URL with HTTPS.
Include your API key in the Authorization header for all requests.
Check the health status of the API service
curl -X GET https://api.raresift.com/v1/health
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2024-01-15T10:30:00Z",
"database": "connected",
"redis": "connected"
}Search for video frames using natural language queries or image similarity
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Natural language description of the scenario |
| limit | integer | No | Maximum number of results (default: 10, max: 100) |
| similarity_threshold | float | No | Minimum similarity score (0.0 - 1.0, default: 0.2) |
| filters | object | No | Optional filters (time_of_day, weather, category) |
curl -X POST https://api.raresift.com/v1/search \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "cars merging onto highway",
"limit": 10,
"similarity_threshold": 0.7,
"filters": {
"time_of_day": "day",
"weather": "sunny"
}
}'{
"results": [
{
"frame_id": 1234,
"video_id": 56,
"timestamp": 45.2,
"similarity": 0.89,
"frame_path": "/frames/video_56_frame_45.jpg",
"frame_url": "https://cdn.raresift.com/frames/...",
"metadata": {
"weather": "sunny",
"time_of_day": "day",
"location": "highway"
},
"video_filename": "highway_drive_001.mp4",
"video_duration": 300.5
}
],
"total_found": 1,
"search_time_ms": 125
}Upload a video file for processing and indexing
Use multipart/form-data encoding for file uploads
| Field | Type | Required | Description |
|---|---|---|---|
| file | file | Yes | Video file (MP4, MOV, AVI) |
| metadata | JSON string | No | Video metadata as JSON |
curl -X POST https://api.raresift.com/v1/videos/upload \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@/path/to/video.mp4" \
-F 'metadata={"weather":"sunny","time_of_day":"day","location":"highway"}'{
"video_id": 123,
"filename": "video.mp4",
"size_bytes": 52428800,
"duration_seconds": 300.5,
"processing_status": "queued",
"created_at": "2024-01-15T10:30:00Z",
"estimated_processing_time": "2-5 minutes"
}Get details about a specific video and its processing status
curl -X GET https://api.raresift.com/v1/videos/123 \ -H "Authorization: Bearer YOUR_API_KEY"
{
"video_id": 123,
"filename": "highway_drive.mp4",
"size_bytes": 52428800,
"duration_seconds": 300.5,
"processing_status": "completed",
"frames_extracted": 300,
"embeddings_generated": 300,
"created_at": "2024-01-15T10:30:00Z",
"processed_at": "2024-01-15T10:35:00Z",
"metadata": {
"weather": "sunny",
"time_of_day": "day",
"location": "highway"
}
}100 requests/hour
10 video uploads/day
1,000 requests/hour
100 video uploads/day
Custom limits
Priority support