Create alert

POST https://datafa.st/api/v1/admin/websites/{websiteId}/alerts

Create an email alert that fires when a visitor completes a goal. The email goes to the website owner's address unless you customize the template.

Goal names are saved lowercase and trimmed.

Related: Alerts announcement · Custom goals

Request

Path parameters

websiteId

string

Website ObjectId. From List websites (_id field). Example: 665f0b3c4d2e1a0012345678.

Body parameters

name

string

required

Alert label in the dashboard. Example: "New sale". Max 100 chars.

trigger.goalName

string

required

Goal that fires the alert. Example: "purchase". Lowercased when saved. Pick from List tracked goals.

template.message

string

required

Plain-text email body. Min 10, max 2000 characters. Example: "Someone just signed up on your site."

template.subject

string

Optional custom subject. Example: "New signup on example.com". Defaults to a standard alert subject when omitted.

isEnabled

boolean

true (default) sends emails; false creates a disabled alert.

Example request body

{
  "name": "New signup alert",
  "trigger": { "goalName": "signup" },
  "template": {
    "subject": "New signup!",
    "message": "A visitor just completed the signup goal."
  },
  "isEnabled": true
}

Response

Returns a JSON object with status: "success" and endpoint-specific fields in data.

Response fields

data[]._id

string

Alert ObjectId.

data[].websiteId

string

Website ObjectId used by account tokens to choose which website to query or manage.

data[].name

string

Human-readable name for the resource or event. The exact meaning depends on the endpoint.

data[].trigger.type

string

Trigger type. Currently goal.

data[].trigger.goalName

string

Goal watched by the alert.

data[].destination.type

string

Destination type. Currently email.

data[].template.subject

string|null

Custom subject when configured.

data[].template.message

string

Human-readable confirmation or status message for the operation.

data[].isEnabled

boolean

Whether the alert is enabled.

data[].recentLogs

object[]

Recent trigger logs.

Authentication

Use a dft_ account token with alerts:write.

A df_ website API key for the same website can also call this route when the path websiteId matches the key's website. Write access with a df_ key is capped at member level — owner-only actions such as team management require a dft_ token and owner role.

Errors

400 — Invalid alert data (name 1–100 chars, message 10–2000 chars, invalid goal name).

403 — Alert limit reached (max 25 per website).

See API errors for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

✍️ Something missing? Suggest features.

🤖 AI agent or LLM? Read this page as markdown

curl -X POST "https://datafa.st/api/v1/admin/websites/{websiteId}/alerts" \ -H "Authorization: Bearer dft_xxx" \ -H "Content-Type: application/json" \ -d '{"name":"New signup","trigger":{"goalName":"signup"},"template":{"message":"A visitor signed up."},"isEnabled":true}'

{ "status": "success", "data": [{ "_id": "665f0b3c4d2e1a0012345678", "websiteId": "665f0b3c4d2e1a0012345678", "name": "New signup", "trigger": { "type": "goal", "goalName": "signup" }, "destination": { "type": "email" }, "template": { "subject": "New signup", "message": "A visitor signed up." }, "isEnabled": true, "recentLogs": [] }] }