# Create an alert subscription

`POST /v3/alerts`

Creates an owner-scoped subscription: selector + one trigger +
delivery cadence + explicit destination ids. Destinations are
provisioned in product Settings and referenced here by id. Chat
cadence defaults to `hourly`; `instant` is subject to a per-day
platform safety ceiling. The 50-subscription owner cap and
selector list bounds (20 values per list) are enforced. An account
holds at most one `rank.entered` subscription; creating a second
while one exists fails with `invalid_request`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AlertCreate"
      },
      "examples": {
        "materialIntel": {
          "summary": "Material intel on followed Projects",
          "value": {
            "trigger": "intelligence.material",
            "selector": {
              "followedProjects": true,
              "qualifiers": {
                "grades": [
                  "polished",
                  "flawless"
                ]
              }
            },
            "cadence": "hourly",
            "destinationIds": [
              "66a10a2b1c9d440000aa0001"
            ]
          }
        },
        "rankEntry": {
          "summary": "Rank entry into the top 10",
          "value": {
            "trigger": "rank.entered",
            "rankThreshold": 10,
            "selector": {
              "qualifiers": {
                "categories": [
                  "modular-blockchains"
                ]
              }
            },
            "cadence": "instant",
            "destinationIds": [
              "66a10a2b1c9d440000aa0002"
            ]
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "201": {
    "description": "Created subscription.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Alert"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Created",
            "value": {
              "data": {
                "id": "66a10a2b1c9d440000d1e2f4",
                "status": "active",
                "trigger": "rank.entered",
                "rankThreshold": 10,
                "selector": {
                  "qualifiers": {
                    "categories": [
                      "modular-blockchains"
                    ]
                  }
                },
                "cadence": "instant",
                "destinationIds": [
                  "66a10a2b1c9d440000aa0002"
                ],
                "createdAt": "2026-08-05T05:00:00Z",
                "updatedAt": "2026-08-05T05:00:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

## Referenced schemas

```json
{
  "AlertCreate": {
    "type": "object",
    "required": [
      "trigger",
      "selector",
      "destinationIds"
    ],
    "properties": {
      "trigger": {
        "$ref": "#/components/schemas/AlertTrigger"
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Required when `trigger` is `rank.entered`."
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ],
        "default": "trend",
        "description": "Ranking watched by `rank.entered`."
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AlertCadence"
          }
        ],
        "default": "hourly"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      }
    }
  },
  "AlertTrigger": {
    "type": "string",
    "enum": [
      "intelligence.material",
      "rank.entered"
    ],
    "description": "The set of launch triggers."
  },
  "AlertSelector": {
    "type": "object",
    "additionalProperties": false,
    "description": "What the subscription watches: the owner's followed Projects, the\ncurrently ranked cohort, a normalized keyword, or a qualifier-only cohort.\nExplicit per-Project and per-Topic id lists are not yet supported\nand will join additively.\n",
    "properties": {
      "followedProjects": {
        "type": "boolean",
        "description": "Only the owner's followed Projects. Mutually exclusive with the ranked Project scopes."
      },
      "trendingProjects": {
        "type": "boolean",
        "description": "Only Projects in the current Trend ranking. Mutually exclusive with `followedProjects`."
      },
      "keyword": {
        "type": "string",
        "minLength": 2,
        "maxLength": 64,
        "description": "Normalized once at save time; matched case-insensitively against source-derived text."
      },
      "qualifiers": {
        "$ref": "#/components/schemas/AlertQualifiers"
      }
    }
  },
  "AlertQualifiers": {
    "type": "object",
    "description": "Filter qualifiers; each list holds at most 20 values.\n`grades`, `sentiments`, `clusterIds`, `maxRank`, and\n`hasOfficialSource` qualify `intelligence.material` subscriptions;\n`chains` qualifies `rank.entered`; `categories` and `assetTypes`\nqualify both.\n",
    "properties": {
      "categories": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "grades": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Grade"
        }
      },
      "sentiments": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "assetTypes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "clusterIds": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "chains": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "maxRank": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Only intel on Projects at or above this rank in the Trend cohort."
      },
      "hasOfficialSource": {
        "type": "boolean"
      }
    }
  },
  "Grade": {
    "type": "string",
    "enum": [
      "chipped",
      "flawed",
      "cut",
      "polished",
      "flawless"
    ],
    "description": "Evidence grade of an Intel item, lowest to highest. Grades describe\nthe shape of the evidence, never the truth of the claim.\n"
  },
  "AlertCadence": {
    "type": "string",
    "enum": [
      "instant",
      "hourly",
      "every_12h",
      "daily"
    ],
    "description": "Chat delivery cadence. First event in a window delivers immediately;\nthe window bundles the rest. `instant` is subject to a per-day\nplatform safety ceiling.\n"
  },
  "Alert": {
    "type": "object",
    "required": [
      "id",
      "status",
      "trigger",
      "selector",
      "cadence",
      "destinationIds",
      "createdAt",
      "updatedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      },
      "trigger": {
        "$ref": "#/components/schemas/AlertTrigger"
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Top-N boundary; present only with `rank.entered`."
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ],
        "default": "trend",
        "description": "Ranking watched by `rank.entered`; omitted stored rows mean Trend."
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "$ref": "#/components/schemas/AlertCadence"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      },
      "createdAt": {
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "Meta": {
    "type": "object",
    "description": "Response metadata. Empty when nothing applies.",
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryMeta"
      },
      "versions": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Named component versions that shaped this response."
      }
    }
  },
  "HistoryMeta": {
    "type": "object",
    "description": "The history window applied to this response. Both fields are null when the account has no history limit.",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "earliestAvailableAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).