Concepts / Metadata and actions
Concepts

Metadata and actions

Put your own data on each request, define your own actions, and act from the dashboard's Logs or the API. Your system gets every action by webhook.

On this page

You define your own actions, for example Ban, Approve or Hide, and take them on a request in the dashboard's Logs or through the API. When someone takes one, your system gets a moderation.action webhook and carries it out.

Detectivision never carries out an action itself. It cannot ban a user on your platform. It tells your system which action was chosen, for which request, along with your own data.

A moderator can open a check in the dashboard's Logs and see its flags, your metadata and your actions. Logs lists the checks that were charged and the async checks still waiting. A partial result or an error is free, so it is not listed there.

Your data on a request: metadata#

Send any JSON object as metadata with a request. It is kept as it is and comes back wherever that request shows up: in the answer, in GET /api/v1/moderation/{id}, in Logs and in every webhook about it. Put in it whatever your system needs to act, such as user and comment ids, or a shop or channel name.

curl https://api.detectivision.ai/api/v1/moderation \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "text_moderation", "input": "You are an idiot", "metadata": {"userId": "u_123", "commentId": "c_456"}}'
import os, requests

r = requests.post(
    "https://api.detectivision.ai/api/v1/moderation",
    headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
    json={"type": "text_moderation", "input": "You are an idiot", "metadata": {"userId": "u_123", "commentId": "c_456"}},
    timeout=30,
)
print(r.json()["metadata"])
  • metadata must be a JSON object of at most 16 KB, counted in UTF-8 bytes. Otherwise the answer is 400 invalid_metadata.
  • Live sessions take it too, in POST /api/v1/live/sessions. Each moment the session keeps carries it.
  • We never read it. Field names are yours.

Your actions#

Define them in the dashboard: open a request in Logs and choose Set up actions. Each action has:

Field Meaning
key What your system receives, for example ban. Lowercase letters, digits and _, starting with a letter, at most 40 characters. It cannot change once created.
label What the action's button says, for example Ban user.
color The button's colour.

An account can have up to 20 actions. Templates (Approve / Reject, Ban / Don't ban, Delete / Keep / Warn) create a first set that you can then change. Deleting an action keeps the history of the times it was taken.

Taking an action#

In Logs: open a request; its panel shows your actions. Press one; you can add a note. The dashboard takes up to 600 actions a minute.

Through the API, one request at a time, with a key that has write permission:

curl https://api.detectivision.ai/api/v1/moderation/1042/actions \
  -H "Api-Key: $DETECTIVISION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "ban", "note": "spam account"}'
import os, requests

r = requests.post(
    "https://api.detectivision.ai/api/v1/moderation/1042/actions",
    headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
    json={"action": "ban", "note": "spam account"},
    timeout=30,
)
print(r.status_code, r.json())

The answer is 201 with the recorded action:

{ "id": 77, "key": "ban", "label": "Ban user", "by": { "type": "api", "name": "shop backend" }, "note": "spam account", "at": 1790935200 }
Status error When
400 invalid_request The key is not one of your actions (the message lists the ones you have), or the body is malformed.
403 forbidden The API key has no write permission.
404 not_found The request does not exist, or belongs to another account.
429 too_many_requests More than 60 actions in a minute through the API. Nothing was taken; Retry-After says how many seconds to wait.

GET /api/v1/actions lists your actions (key, label, color). GET /api/v1/moderation/{id} returns a request with:

  • its answer and metadata;
  • state: pending until the first action, then actioned;
  • actions: what was done.

The moderation.action webhook#

Add an endpoint that takes moderation.action on the dashboard's Webhooks page. Every action sends one message:

{
  "type": "moderation.action",
  "timestamp": "2026-10-02T12:00:00.000Z",
  "data": {
    "action": { "key": "ban", "label": "Ban user" },
    "note": "spam account",
    "by": { "type": "user", "name": "Ahmet" },
    "item": {
      "id": 1042,
      "type": "text_moderation",
      "flagged": true,
      "flags": [{ "flag": "insult", "confidence": 0.93 }],
      "metadata": { "userId": "u_123", "commentId": "c_456" },
      "createdAt": "2026-10-02T11:58:10.000Z"
    }
  }
}
  • by.type is user (the dashboard, name is who) or api (name is the API key's label).
  • A request's panel in Logs shows whether each action's message arrived:
    • Delivered: every endpoint answered 2xx.
    • Sending: on its way.
    • Failed: an endpoint refused it. Retries continue on their schedule; Send again sends it now, only to the endpoints that did not take it.
    • Not sent: no endpoint takes moderation.action. The action is still saved.
    • Deliveries are kept for 30 days; after that, or when the endpoint is removed, the action shows no state.

The signature, retries and best practice are the same as for every webhook.

Taking actions and sending their webhooks is free.