CommunityHub logo Archivist Documentation

Current Section

Media API

Upload meeting videos, list video metadata to find the right video ID, and retrieve clickable frame images from specific timestamps.

Use the API GitHub

Normal User Flow

How People Use It

Users should not guess video IDs. They upload a video, list metadata, choose the right record, then request the frame they need.

1

Upload MP4

Send a meeting video and optional metadata. The API returns a generated videoId.

2

List Videos

Call the public metadata endpoint to see uploaded videos and match the correct record.

3

Request Frame

Pass videoId in the path and timestamp as a query parameter.

4

Open URL

Use the returned frameUrl as the clickable image link.

Timestamp Rule

Where The Timestamp Goes

The timestamp is passed to the frame-generation endpoint, not to the image endpoint.

Use GET /videos/{videoId}/frame?timestamp=00:28:35. The response gives you a frameUrl, which points to /media/frames/{videoId}/{frameFile}. 

GET /videos/{videoId}/frame?timestamp=00:28:35

Response:
{
  "videoId": "vid_...",
  "timestamp": "00:28:35.000",
  "frameUrl": "https://.../media/frames/...jpg",
  "cached": false
}

Endpoint Reference

Media API Endpoints

Public

GET /videos

Lists uploaded videos and metadata so users can find the correct videoId.

Bearer Token

POST /videos

Uploads an MP4 file and returns the generated video record.

Bearer Token

GET /videos/{videoId}/frame

Creates or returns a frame for a specific timestamp.

Bearer Token

PUT /videos/{videoId}/status

Marks a video completed and deletes its source MP4. Metadata and frames already extracted are kept.

Public

GET /media/frames/{videoId}/{frameFile}

Opens an already-generated JPEG image. This endpoint does not accept timestamps.

Copyable Calls

Examples

List Video Metadata

No token required.

curl "https://206-189-199-110.sslip.io/archivist/api/videos?limit=50"

Upload A Video

Requires Authorization: Bearer <token>.

curl -H "Authorization: Bearer $ARCHIVIST_API_TOKEN" \
  -F "meetingTitle=CH_Des Archivist" \
  -F "meetingDate=2026-08-21" \
  -F "source=box-download" \
  -F "uploadedBy=Kwaku" \
  -F "file=@/path/to/meeting.mp4;type=video/mp4" \
  "https://206-189-199-110.sslip.io/archivist/api/videos"

Retrieve A Frame

The timestamp is the query parameter.

curl -H "Authorization: Bearer $ARCHIVIST_API_TOKEN" \
  "https://206-189-199-110.sslip.io/archivist/api/videos/vid_01M0TP1NKCFMAWPAQZ09PKN23S/frame?timestamp=00:28:35"

Complete And Delete

Frees the disk space used by the source video. This cannot be undone.

curl -X PUT -H "Authorization: Bearer $ARCHIVIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "completed"}' \
  "https://206-189-199-110.sslip.io/archivist/api/videos/vid_01M0TP1NKCFMAWPAQZ09PKN23S/status"

Known Video

First Uploaded Meeting

videoId vid_01M0TP1NKCFMAWPAQZ09PKN23S
displayName CH_Des Archivist
originalFilename 260821 CH_Des Archivist - video.mp4
meetingDate 2026-08-21

Troubleshooting

Common Errors

401 unauthorized Missing or wrong bearer token on protected endpoints.

413 upload_too_large Uploaded MP4 exceeds configured max size.

415 unsupported_file_type File is not an MP4.

400 invalid_timestamp Timestamp is not seconds, MM:SS, or HH:MM:SS.

404 video_not_found The requested video ID does not exist.

410 video_completed The video was completed and its source file was deleted.