REST API

The REST API lets any program - a web page, a script, or an AI agent - read from and write to a Fast Video Cataloger server.

The REST API is served by the Fast Video Cataloger server, not by the desktop application. Any HTTP client can use it: a web page, a command line tool, a program in any language, or an AI assistant. It covers reading and writing - videos, thumbnails, tags, actors, bins, playlists, clips, subtitles, properties and archives.

You do not need the separate server product to try this. Open Start -> Server in Fast Video Cataloger, click Setup, and the wizard installs and starts the server on your own machine.

For the complete endpoint reference, see REST API in the server guide.

Finding the API¶

Every endpoint lives under /api/v1/. The server describes itself, so you rarely need to look anything up by hand:

The OpenAPI document is the fastest way to point a code generator - or an AI assistant - at the API. It lists every route, parameter and response type.

Responses use camelCase JSON and are wrapped in a common envelope:

{ "success": true, "data": [ ... ], "totalCount": 42 }

Authentication¶

If the catalog has user accounts configured, log in first and pass the returned token as a bearer token.

curl -X POST http://localhost:8754/api/v1/auth/login \
     -H "Content-Type: application/json" \
     -d "{\"username\":\"user@example.com\",\"password\":\"yourpassword\"}"

curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:8754/api/v1/videos?limit=10

Three roles are available. Viewer can read, Editor can also create, update and delete, and Admin can additionally manage users.

Call GET /api/v1/auth/required to find out whether a server needs a login at all. If a catalog has no authentication configured, the API is open to anyone who can reach the port - keep that in mind before exposing the server beyond your own machine.

Session tokens expire after eight hours. For a script or an AI assistant that runs unattended, an administrator can create an API key instead - a long-lived credential with its own role, presented the same way:

curl -X POST http://localhost:8754/api/v1/apikeys \
     -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"my agent\",\"role\":\"Viewer\"}"

The key comes back once and is not stored, so save it when you create it. Give it the smallest role that does the job.

Sample: search and tag¶

Find videos, then tag one of the results. This is the whole loop most integrations need.

# Search the catalog
curl "http://localhost:8754/api/v1/videos?search=apollo&limit=5"

# Search scene thumbnails by keyword
curl "http://localhost:8754/api/v1/thumbnails/search?keywords=launch&limit=20"

# Search spoken words in transcribed videos.
# This returns the ids of the matching subtitle LINES, not video ids - read a line with
# GET /api/v1/subtitles/{id} to get its text, its videoFileID and its timecode.
curl "http://localhost:8754/api/v1/subtitles/search?search=we%20have%20liftoff"

# Tag a video with a comma-separated list (requires the Editor role)
curl -X PUT http://localhost:8754/api/v1/videos/12/tags \
     -H "Content-Type: application/json" \
     -d "{\"tags\":\"trailer,apollo\"}"

Sample: images and video¶

Thumbnails and videos are served as bytes, so a web page can show them directly and an image-capable program can read them:

GET /api/v1/thumbnails/{id}/image     scene thumbnail as an image
GET /api/v1/videos/{id}/image         video cover image
GET /api/v1/videos/{id}/stream        the video itself, with range requests for seeking

A minimal page that lists videos and shows their covers:

<script>
  var server_url = "http://localhost:8754/"; // Change to your server address

  fetch(server_url + "api/v1/videos?limit=20")
    .then(function (r) { return r.json(); })
    .then(function (result) {
      result.data.forEach(function (video) {
        var img = document.createElement("img");
        img.src = server_url + "api/v1/videos/" + video.id + "/image";
        img.title = video.title;
        document.body.appendChild(img);
      });
    });
</script>

Sample: index a video¶

Adding a video with POST /api/v1/videos only creates the catalog entry - it has no thumbnails and no duration yet. Ask the server to index it:

curl -X POST http://localhost:8754/api/v1/videos/12/index

The response returns immediately with 202 Accepted because indexing takes minutes. Follow progress by polling the thumbnails:

curl http://localhost:8754/api/v1/videos/12/thumbnails

Indexing runs whatever the server is configured for, so this is also how transcription, face recognition and scene classification get applied - see the server settings for which of those are enabled. One video is indexed at a time; further requests queue.

To find everything that still needs work:

curl http://localhost:8754/api/v1/videos/pending-indexing

What the REST API does not cover¶

The API works on the catalog and on indexing whole videos. Finer-grained control still belongs to the desktop application - there is no endpoint to capture a single frame at a given time, drive the video player, or run a specific AI model over an existing thumbnail. Use the scripting API for those; it runs inside the application and reaches the parts the REST API does not.