Skip to content
Gaard Gaard

Getting Started

This tutorial walks you through sending your first video to the Gaard Vision API and retrieving the classification result. By the end, you will have a working API call you can adapt for your integration.

Prerequisites

Section titled “Prerequisites”
  • A Gaard account with API access
  • curl installed on your machine
  • A video file to classify (MP4 or MOV)

  1. Get your API token

    Section titled “Get your API token”

    Create an API token in the Gaard app at Settings > Platform > Integrations.

    Once you have the token, export it as an environment variable so the commands in this tutorial can reference it:

    terminal
    export API_KEY="your-api-token"

  2. Get a sample video

    Section titled “Get a sample video”

    If you do not have a video file ready, download our sample clip or grab one from the VIRAT dataset.

    Save the video file to your working directory. The examples below assume the file is named video.mp4.

  3. Send a video for classification

    Section titled “Send a video for classification”

    The classification endpoint accepts a multipart/form-data POST request. You upload the video file as a form field using -F, not as a JSON payload.

Async mode (default)

Section titled “Async mode (default)”

By default, classification runs asynchronously. The API accepts the video and returns an ID you use to poll for the result.

terminal
curl -X POST https://vision.gaard.ai/api/classify \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

The response contains the classification ID and a timestamp:

{
  "id": "66436fc66d24ab9cf81140eb",
  "accepted_at": "2024-05-14T16:05:58.444Z"
}

Use the id value to retrieve the result:

terminal
curl https://vision.gaard.ai/api/result/66436fc66d24ab9cf81140eb \
  -H "Authorization: Bearer $API_KEY"

If the classification is still processing, poll this endpoint again after a few seconds until the result is available.

Sync mode

Section titled “Sync mode”

If you prefer to wait for the result in a single request, add ?sync=true. The API blocks until classification is complete and returns the full result directly.

terminal
curl -X POST "https://vision.gaard.ai/api/classify?sync=true" \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]"

Adding metadata (optional)

Section titled “Adding metadata (optional)”

You can attach a JSON metadata file alongside the video to provide additional context such as site and camera identifiers. Create a file named metadata.json:

{
  "site_id": "134188",
  "camera_id": "VI01"
}

Then include it in the request as a second form field:

terminal
curl -X POST https://vision.gaard.ai/api/classify \
  -H "Authorization: Bearer $API_KEY" \
  -F "[email protected]" \
  -F "[email protected]"

What’s next

Section titled “What’s next”

Now that you have successfully classified a video, explore the rest of the API:

  • Endpoints — full endpoint reference for classify, result, annotate, and delete
  • Response structure — understand the fields in a classification response
  • Classification result — result types, statuses, and detailed examples
  • Metadata — the full metadata format and available fields
  • Webhooks — receive async results via webhook instead of polling