Create Alert

curl --request POST \
  --url https://api.mixpeek.com/v1/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Alerts when new videos match known safety incidents",
  "enabled": true,
  "name": "Safety Incident Detector",
  "notification_config": {
    "channels": [
      {
        "channel_id": "wh_safety_team",
        "channel_type": "webhook"
      }
    ],
    "include_matches": true,
    "include_scores": true
  },
  "retriever_id": "ret_safety_search"
}
'

import requests

url = "https://api.mixpeek.com/v1/alerts"

payload = {
    "description": "Alerts when new videos match known safety incidents",
    "enabled": True,
    "name": "Safety Incident Detector",
    "notification_config": {
        "channels": [
            {
                "channel_id": "wh_safety_team",
                "channel_type": "webhook"
            }
        ],
        "include_matches": True,
        "include_scores": True
    },
    "retriever_id": "ret_safety_search"
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Namespace": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Namespace': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Alerts when new videos match known safety incidents',
    enabled: true,
    name: 'Safety Incident Detector',
    notification_config: {
      channels: [{channel_id: 'wh_safety_team', channel_type: 'webhook'}],
      include_matches: true,
      include_scores: true
    },
    retriever_id: 'ret_safety_search'
  })
};

fetch('https://api.mixpeek.com/v1/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Alerts when new videos match known safety incidents',
    'enabled' => true,
    'name' => 'Safety Incident Detector',
    'notification_config' => [
        'channels' => [
                [
                                'channel_id' => 'wh_safety_team',
                                'channel_type' => 'webhook'
                ]
        ],
        'include_matches' => true,
        'include_scores' => true
    ],
    'retriever_id' => 'ret_safety_search'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Namespace: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/alerts"

	payload := strings.NewReader("{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Namespace", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/alerts")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}"

response = http.request(request)
puts response.read_body

{
  "alert_id": "alt_safety_001",
  "description": "Alerts when new videos match known safety incidents",
  "enabled": true,
  "name": "Safety Incident Detector",
  "notification_config": {
    "channels": [
      {
        "channel_id": "wh_safety_team",
        "channel_type": "webhook"
      }
    ],
    "include_matches": true,
    "include_scores": true
  },
  "retriever_id": "ret_safety_search"
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

Alerts

Create Alert

Create a new alert that monitors document ingestion and sends notifications.

Alerts attach retrievers to collections. When new documents are ingested, the alert runs the retriever and sends notifications if matches are found.

Key Components:

retriever_id: References a retriever that defines query logic (filters, scoring, limits)
notification_config: Defines where to send notifications (webhook, Slack, email)

Note: The retriever owns all query semantics. The alert’s job is simply to run the retriever and notify if results exist.

POST

alerts

Create Alert

curl --request POST \
  --url https://api.mixpeek.com/v1/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Namespace: <api-key>' \
  --data '
{
  "description": "Alerts when new videos match known safety incidents",
  "enabled": true,
  "name": "Safety Incident Detector",
  "notification_config": {
    "channels": [
      {
        "channel_id": "wh_safety_team",
        "channel_type": "webhook"
      }
    ],
    "include_matches": true,
    "include_scores": true
  },
  "retriever_id": "ret_safety_search"
}
'

import requests

url = "https://api.mixpeek.com/v1/alerts"

payload = {
    "description": "Alerts when new videos match known safety incidents",
    "enabled": True,
    "name": "Safety Incident Detector",
    "notification_config": {
        "channels": [
            {
                "channel_id": "wh_safety_team",
                "channel_type": "webhook"
            }
        ],
        "include_matches": True,
        "include_scores": True
    },
    "retriever_id": "ret_safety_search"
}
headers = {
    "Authorization": "Bearer <token>",
    "X-Namespace": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'X-Namespace': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    description: 'Alerts when new videos match known safety incidents',
    enabled: true,
    name: 'Safety Incident Detector',
    notification_config: {
      channels: [{channel_id: 'wh_safety_team', channel_type: 'webhook'}],
      include_matches: true,
      include_scores: true
    },
    retriever_id: 'ret_safety_search'
  })
};

fetch('https://api.mixpeek.com/v1/alerts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.mixpeek.com/v1/alerts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => 'Alerts when new videos match known safety incidents',
    'enabled' => true,
    'name' => 'Safety Incident Detector',
    'notification_config' => [
        'channels' => [
                [
                                'channel_id' => 'wh_safety_team',
                                'channel_type' => 'webhook'
                ]
        ],
        'include_matches' => true,
        'include_scores' => true
    ],
    'retriever_id' => 'ret_safety_search'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Namespace: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mixpeek.com/v1/alerts"

	payload := strings.NewReader("{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("X-Namespace", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.mixpeek.com/v1/alerts")
  .header("Authorization", "Bearer <token>")
  .header("X-Namespace", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.mixpeek.com/v1/alerts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Namespace"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"Alerts when new videos match known safety incidents\",\n  \"enabled\": true,\n  \"name\": \"Safety Incident Detector\",\n  \"notification_config\": {\n    \"channels\": [\n      {\n        \"channel_id\": \"wh_safety_team\",\n        \"channel_type\": \"webhook\"\n      }\n    ],\n    \"include_matches\": true,\n    \"include_scores\": true\n  },\n  \"retriever_id\": \"ret_safety_search\"\n}"

response = http.request(request)
puts response.read_body

{
  "alert_id": "alt_safety_001",
  "description": "Alerts when new videos match known safety incidents",
  "enabled": true,
  "name": "Safety Incident Detector",
  "notification_config": {
    "channels": [
      {
        "channel_id": "wh_safety_team",
        "channel_type": "webhook"
      }
    ],
    "include_matches": true,
    "include_scores": true
  },
  "retriever_id": "ret_safety_search"
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "error": {
    "details": {
      "id": "ns_123",
      "resource": "namespace"
    },
    "message": "Namespace not found",
    "type": "NotFoundError"
  },
  "status": 404,
  "success": false
}

Authorizations

Authorization

string

header

required

Mixpeek API key, sent as Authorization: Bearer mxp_sk_.... Create one in Studio under Settings → API Keys, or with an admin key via POST /v1/organizations/users/{user_email}/api-keys. A missing header returns 403; an invalid or revoked key returns 401.

X-Namespace

string

header

required

Namespace id (ns_...), not the namespace name. This scopes the request rather than authenticating it, and it is required on every operation marked x-mixpeek-namespace-scoped.

Body

application/json

Request model to create an alert.

Creates a new alert that can be attached to collections to monitor for matching content and send notifications when matches are found.

Note: The alert references a retriever that contains all query logic (filters, min_score, limits, collection targeting). The alert's job is simply to run that retriever and notify if results exist.

name

string

required

Human-readable name for the alert

Required string length: 1 - 200

Examples:

"Safety Incident Detector"

"Prohibited Content Alert"

notification_config

AlertNotificationConfig · object

required

How and where to send notifications when alert triggers

Show child attributes

Example:

{
  "channels": [
    {
      "channel_id": "wh_safety_team",
      "channel_type": "webhook"
    },
    {
      "channel_id": "sl_alerts",
      "channel_type": "slack"
    }
  ],
  "include_matches": true,
  "include_scores": true
}

description

string | null

Optional description of what this alert monitors

Maximum string length: 1000

Example:

"Alerts when new videos match known safety incidents"

source

enum<string>

default:retriever

Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)

Available options:

retriever,

system

retriever_id

string | null

ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.

Example:

"ret_safety_search"

trigger_on

enum<string>

default:results

source=retriever: fire on 'results' or 'no_results'

Available options:

results,

no_results

system_condition

SystemCondition · object | null

Built-in data-plane condition to watch (source=system only)

Show child attributes

namespace_selector

NamespaceSelector · object | null

Org-level namespace scoping (all vs selected)

Show child attributes

enabled

boolean

default:true

Whether the alert is active and will execute

metadata

Metadata · object | null

Additional user-defined metadata for the alert

Response

Successful Response

Response model for a single alert.

name

string

required

Human-readable name for the alert

Required string length: 1 - 200

Examples:

"Safety Incident Detector"

"Prohibited Content Alert"

notification_config

AlertNotificationConfig · object

required

How and where to send notifications when alert triggers

Show child attributes

Example:

{
  "channels": [
    {
      "channel_id": "wh_safety_team",
      "channel_type": "webhook"
    },
    {
      "channel_id": "sl_alerts",
      "channel_type": "slack"
    }
  ],
  "include_matches": true,
  "include_scores": true
}

alert_id

string

Unique identifier for the alert

Example:

"alt_abc123xyz789"

namespace_id

string | null

Namespace this alert belongs to

Example:

"ns_production"

description

string | null

Optional description of what this alert monitors

Maximum string length: 1000

Example:

"Alerts when new videos match known safety incidents"

source

enum<string>

default:retriever

Trigger source: 'retriever' (runs a retriever) or 'system' (built-in metric)

Available options:

retriever,

system

retriever_id

string | null

ID of the retriever to execute (source=retriever only). The retriever defines filters, scoring, limits.

Example:

"ret_safety_search"

trigger_on

enum<string>

default:results

For source=retriever: fire on 'results' (matches found) or 'no_results' (retriever went dark).

Available options:

results,

no_results

system_condition

SystemCondition · object | null

Built-in data-plane condition to watch (source=system only)

Show child attributes

namespace_selector

NamespaceSelector · object | null

Org-level namespace scoping (all vs selected). When omitted, the alert is scoped to its own namespace_id.

Show child attributes

enabled

boolean

default:true

Whether the alert is active and will execute

created_at

string<date-time> | null

Timestamp when the alert was created

updated_at

string<date-time> | null

Timestamp when the alert was last updated

metadata

Metadata · object

Additional user-defined metadata for the alert

Namespaces

Buckets

Collections

Feature Extractors

Documents

Retrievers

Enrich & Improve

Automate

Administer

Advanced

Create Alert

Authorizations

Body

Response