# FAF API

## Health

## health

<mark style="color:blue;">`GET`</mark> `https://faf.traces.cloud/api/v1/health`

This endpoint allows to test that service is up

#### Headers

| Name                                        | Type   | Description                                    |
| ------------------------------------------- | ------ | ---------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces FAF API |

{% tabs %}
{% tab title="200 " %}

```
ALIVE
```

{% endtab %}

{% tab title="404 " %}

```
```

{% endtab %}
{% endtabs %}

#### Example

{% tabs %}
{% tab title="Bash" %}

```sh
curl -X GET https://faf.traces.cloud/api/v1.1/health -H "x-api-key: YOUR_API_KEY"
```

{% endtab %}
{% endtabs %}

## Operations <a href="#id-0g-operations" id="id-0g-operations"></a>

## filter-alarm

<mark style="color:green;">`POST`</mark> `https://faf.traces.cloud/api/v1/filter-alarm`

Performs alarm filtering and returns alarm type, confidence, and a list of objects that triggered an event with corresponding information. \
This endpoint accepts any number of frames with a minimum limit of 5 frames per event.

#### Headers

| Name                                        | Type   | Description                                    |
| ------------------------------------------- | ------ | ---------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces FAF API |

#### Request Body

| Name                                       | Type   | Description                                                                  |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| metadata<mark style="color:red;">\*</mark> | object | A dictionary with the following keys: "event\_id", "camera\_id", "timestamp" |
| image\_0<mark style="color:red;">\*</mark> | string | frame #1; image file ($binary)                                               |
| image\_1<mark style="color:red;">\*</mark> | string | frame #2; image file ($binary)                                               |
| image\_2<mark style="color:red;">\*</mark> | string | frame #3; image file ($binary)                                               |
| image\_3<mark style="color:red;">\*</mark> | string | frame #4; image file ($binary)                                               |
| image\_4<mark style="color:red;">\*</mark> | string | frame #5; image file ($binary)                                               |

{% tabs %}
{% tab title="200 An example of an API response to an alarm that was triggered by a vehicle with coordinates of moving vehicle on each frame." %}

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.7892204529672106,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        527,
        400,
        827,
        569
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        122,
        399,
        335,
        536
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        202,
        270,
        325,
        337
      ],
      "frame_id": 2,
      "direction": null
    }
  ]
}
```

{% endtab %}

{% tab title="401 Auth data was not provided" %}

```javascript
{
  "code": "INVALID_API_KEY",
  "description": "API key was not recognized"
}
```

{% endtab %}
{% endtabs %}

### **Example** <a href="#id-8y-alarm-responses-examples" id="id-8y-alarm-responses-examples"></a>

An example of a request with 5 frames.

{% tabs %}
{% tab title="Bash" %}

```bash
curl -X POST "https://faf.traces.cloud/api/v1.1/filter-alarm"
 -H "accept: */*"
 -H "x-api-key: YOUR_API_KEY"
 -H "Content-Type: multipart/form-data"
 -F "metadata={ "event_id": "ddf27b34-d3b5-41a5-b2a6-3873a589ec09", "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e", "timestamp": 1585840725 }" -F 
"image_0=@customer_frame0.png;type=image/png" -F "image_1=@customer_frame1.png;type=image/png" -F "image_2=@customer_frame2.png;type=image/png" -F "image_3=@customer_frame3.png;type=image/png" -F "image_4=@customer_frame4.png;type=image/png"
```

{% endtab %}
{% endtabs %}

An example of a request with 12 frames.

```javascript
curl -X POST "https://faf.traces.cloud/api/v1.1/filter-alarm"
 -H "accept: */*"
 -H "x-api-key: YOUR_API_KEY"
 -H "Content-Type: multipart/form-data"
 -F "metadata={ "event_id": "ddf27b34-d3b5-41a5-b2a6-3873a589ec09", "camera_id": "b5271b30-aecd-4897-bc95-ff25c8466b9e", "timestamp": 1585840725 }" 
 -F "image_0=@customer_frame0.png;type=image/png" 
 -F "image_1=@customer_frame1.png;type=image/png"
 -F "image_2=@customer_frame2.png;type=image/png" 
 -F "image_3=@customer_frame3.png;type=image/png" 
 -F "image_4=@customer_frame4.png;type=image/png"
 -F "image_5=@customer_frame5.png;type=image/png"
 -F "image_6=@customer_frame6.png;type=image/png"
 -F "image_7=@customer_frame7.png;type=image/png"
 -F "image_8=@customer_frame8.png;type=image/png"
 -F "image_9=@customer_frame9.png;type=image/png"
 -F "image_10=@customer_frame10.png;type=image/png"
 -F "image_11=@customer_frame11.png;type=image/png"
```

## filter-video-alarm

<mark style="color:green;">`POST`</mark> `https://faf.traces.cloud/api/v1/filter-video-alarm`

Performs alarm filtering and returns alarm type, confidence, and a list of objects that triggered an event with corresponding information. \
This endpoint accepts video files. \
It is recommended to send a video 10-20 seconds long. Sending videos longer than 30 seconds may result in a prolonged response time.

#### Headers

| Name                                        | Type   | Description                                    |
| ------------------------------------------- | ------ | ---------------------------------------------- |
| x-api-key<mark style="color:red;">\*</mark> | string | Authorization API key to access Traces FAF API |

#### Request Body

| Name                                       | Type   | Description                                                                  |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------- |
| video<mark style="color:red;">\*</mark>    | string | video file ($binary)                                                         |
| metadata<mark style="color:red;">\*</mark> | object | A dictionary with the following keys: "event\_id", "camera\_id", "timestamp" |

{% tabs %}
{% tab title="200 An example of an API response to an alarm that was triggered by a vehicle with coordinates of moving vehicle on each frame. " %}

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.7892204529672106,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        527,
        400,
        827,
        569
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        122,
        399,
        335,
        536
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        202,
        270,
        325,
        337
      ],
      "frame_id": 2,
      "direction": null
    }
  ]
}
```

{% endtab %}

{% tab title="401 " %}

```javascript
{
  "code": "INVALID_API_KEY",
  "description": "API key was not recognized"
}
```

{% endtab %}
{% endtabs %}

## **Examples of Alarm Responses to different motion events** <a href="#id-8y-alarm-responses-examples" id="id-8y-alarm-responses-examples"></a>

### Examples of Alarm Responses for customers on a General tier. <a href="#xz-example-of-false-alarm" id="xz-example-of-false-alarm"></a>

Each trigger includes the following information for each frame: '`object_type`', '`action`', '`bbox`', '`frame_id`', and '`direction`'.&#x20;

If more information is needed, refer to [examples of Alarm Responses on an Advanced tier](#5l-example-of-alarm-triggered-by-person-and-vehicle-1).&#x20;

#### **Example of False Alarm** <a href="#xz-example-of-false-alarm" id="xz-example-of-false-alarm"></a>

Input data

![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/n9SVMcTXNFMXc_b2edvPl_false-alarm.png?auto=format\&ixlib=react-9.1.1\&h=109\&w=968)

FAF Response

```javascript
{
  "alarm_confirmed": false,
  "alarm_confidence": null,
  "triggered_by": []
}
```

#### **Example of an alarm triggered by a "Person"** <a href="#gm-example-of-alarm-triggered-by-a-person" id="gm-example-of-alarm-triggered-by-a-person"></a>

Input data

![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/0EvWI1O2aL-PwLe8lcUO6_person.png?auto=format\&ixlib=react-9.1.1\&h=364\&w=3224)

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.7866996370706637,
  "triggered_by": [
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        621,
        1051,
        711,
        1269
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        959,
        1100,
        1031,
        1337
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        718,
        1148,
        815,
        1368
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        769,
        977,
        859,
        1233
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        687,
        971,
        771,
        1189
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        940,
        983,
        1026,
        1217
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        983,
        875,
        1059,
        1086
      ],
      "frame_id": 2,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        833,
        886,
        894,
        1121
      ],
      "frame_id": 2,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        738,
        871,
        816,
        1080
      ],
      "frame_id": 2,
      "direction": null
    }
  ]
}
```

#### **Example of an alarm triggered by "Vehicle"** <a href="#qa-example-of-alarm-triggered-by-vehicle" id="qa-example-of-alarm-triggered-by-vehicle"></a>

Input data

![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/WDZ51A2rUH7tjeYT2EPLY_vehicle.png?auto=format\&ixlib=react-9.1.1\&h=361\&w=3227)

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.7540868690800507,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        2084,
        604,
        2420,
        774
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        1433,
        456,
        1723,
        588
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        805,
        514,
        1104,
        699
      ],
      "frame_id": 2,
      "direction": null
    }
  ]
}
```

#### **Example of an alarm triggered by both "Person" and "Vehicle"** <a href="#id-5l-example-of-alarm-triggered-by-person-and-vehicle" id="id-5l-example-of-alarm-triggered-by-person-and-vehicle"></a>

Input data

![Click to Zoom](https://archbee.imgix.net/bLFGjdFdIY6MzXs3Kd3G8/008t9UW4ZE-QOGk1Wuhsd_personandvehicle.png?auto=format\&ixlib=react-9.1.1\&h=362\&w=3224)

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.6292241402835548,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        677,
        486,
        925,
        653
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        447,
        195,
        496,
        269
      ],
      "frame_id": 0,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        673,
        466,
        923,
        653
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "person",
      "action": "moving",
      "bbox": [
        588,
        393,
        624,
        495
      ],
      "frame_id": 1,
      "direction": null
    },
    {
      "object_type": "vehicle",
      "action": "moving",
      "bbox": [
        584,
        468,
        814,
        620
      ],
      "frame_id": 2,
      "direction": null
    }
  ]
}
```

### Examples of Alarm Responses for customers on an Advanced tier. <a href="#example-of-false-alarm-advanced" id="example-of-false-alarm-advanced"></a>

Customers on the Advanced tier will receive comprehensive alarm responses that contain all the information from the General tier, as well as additional data fields such as `object_class` and `object_color`. These fields provide additional context and insights into the alarm event, enabling customers to quickly and effectively respond to any issues with their system.

> The newly introduced `object_class` field provides supplementary information regarding the specific class of a vehicle that has triggered an alarm. The supported vehicle classes within our API solution include four distinct categories: "car", "truck", "bus", and "motorbike".

> The recently added <mark style="background-color:blue;">`object_color`</mark> field outlines the color of a vehicle that has triggered an alarm. Our library comprises 147 distinct colors for this purpose. The `object_color` value is computed for each bounding box associated with a vehicle trigger. It is important to note that factors such as varying lighting conditions and shadows may influence the accuracy of the detected color.

Below are some examples of input data and their corresponding responses with updated structure. These examples showcase the latest changes and improvements to the response format, enabling customers to better understand and utilize our API's features.

#### **Examples of an alarm triggered by both "Vehicle" with extended details.** <a href="#id-5l-example-of-alarm-triggered-by-person-and-vehicle" id="id-5l-example-of-alarm-triggered-by-person-and-vehicle"></a>

Example 1.

Input data

<figure><img src="https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FwEYlBxSfF29SCSF09poy%2Fforcolors_event_1.gif?alt=media&#x26;token=ed69e47b-8a0b-460c-ab68-0ec14701c9b4" alt=""><figcaption></figcaption></figure>

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.8125502391157845,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        520,
        352,
        714,
        512
      ],
      "frame_id": 0,
      "direction": null,
      "object_color": "slategray"
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        413,
        345,
        574,
        472
      ],
      "frame_id": 1,
      "direction": null,
      "object_color": "slategray"
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        392,
        322,
        511,
        450
      ],
      "frame_id": 2,
      "direction": null,
      "object_color": "slategray"
    }
  ]
}
```

Example 2.

Input data

<figure><img src="https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2FYVSWjh183iOqJMXQUzdB%2Fforcolors_event_2.gif?alt=media&#x26;token=c2ca9a92-516a-4224-a928-ae1b0c09031f" alt=""><figcaption></figcaption></figure>

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.7021554756882509,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        588,
        332,
        672,
        371
      ],
      "frame_id": 0,
      "direction": null,
      "object_color": "darkslateblue"
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        628,
        319,
        709,
        361
      ],
      "frame_id": 1,
      "direction": null,
      "object_color": "darkslateblue"
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        727,
        313,
        826,
        347
      ],
      "frame_id": 2,
      "direction": null,
      "object_color": "darkslateblue"
    }
  ]
}
```

Example 3.

Input data

<figure><img src="https://2748832723-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-McYmA310oN--gaDwXjq%2Fuploads%2Fr720SZhOg9xVAT69hMJP%2Fforcolors_event_3.gif?alt=media&#x26;token=726b0d40-9773-46b9-92cd-ee1c2feab831" alt=""><figcaption></figcaption></figure>

FAF Response

```javascript
{
  "alarm_confirmed": true,
  "alarm_confidence": 0.694689647096008,
  "triggered_by": [
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        1537,
        77,
        1627,
        167
      ],
      "frame_id": 0,
      "direction": null,
      "object_color": "darkslategray"
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        1475,
        137,
        1579,
        238
      ],
      "frame_id": 1,
      "direction": null,
      "object_color": "darkslategray"
    },
    {
      "object_type": "person",
      "object_class": "person",
      "action": "moving",
      "bbox": [
        451,
        482,
        490,
        585
      ],
      "frame_id": 1,
      "direction": null,
      "object_color": null
    },
    {
      "object_type": "vehicle",
      "object_class": "car",
      "action": "moving",
      "bbox": [
        1379,
        201,
        1515,
        316
      ],
      "frame_id": 2,
      "direction": null,
      "object_color": "darkslategray"
    },
    {
      "object_type": "person",
      "object_class": "person",
      "action": "moving",
      "bbox": [
        456,
        476,
        497,
        575
      ],
      "frame_id": 2,
      "direction": null,
      "object_color": null
    }
  ]
}
```

## **EventMetadata** <a href="#tm-eventmetadata" id="tm-eventmetadata"></a>

<table><thead><tr><th>Key</th><th width="150">Type</th><th width="344">Example</th><th>Description </th></tr></thead><tbody><tr><td>camera_id*</td><td>str</td><td>"b5271b30-aecd-4897-bc95-ff25c8466b9e"</td><td>A unique ID number of the video camera. Used for AI auto training pipeline, consensus algorithm, and billing.</td></tr><tr><td>timestamp*</td><td> <a href="https://en.m.wikipedia.org/wiki/ISO_8601"></a>int</td><td>1585840725</td><td>A timestamp in seconds since the epoch</td></tr><tr><td>event_id*</td><td>str</td><td>"ddf27b34-d3b5-41a5-b2a6-3873a589ec09"</td><td><p>A unique ID of the event.</p><p>Used for synchronization and AI auto training pipeline</p></td></tr><tr><td>motion_masks</td><td>list</td><td><p></p><pre><code>[((0, 0), (900, 0),
 (900, 130), (0, 580)), 
 ((1920, 1090), (1920, 500),
 (1000, 1090))]
</code></pre></td><td>List of motion mask coordinates. See<a data-mention href="../best-practices#motion-masks">#motion-masks</a> for more details</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.traces.cloud/faf-api/api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.