Core Concepts

The Data API is the primary way to send objects to SafetyKit. You can use it for products, users, messages, transactions, media, or any custom object type that fits your operational workflow.

Most integrations follow a predictable pattern: define a namespace, ingest objects with stable IDs, configure schema, and consume object-level outputs via webhook or request polling.

Typical integration flow

1. Choose a namespace for the object type you want to review.
2. Send objects to POST /v1/data/{namespace}.
3. Configure namespace schema with PUT /v1/data/{namespace}/settings.
4. Receive object-level decisions through webhooks.
5. Optionally retrieve request outputs from GET /v1/data/{namespace}/requests/{requestId}.

Namespace

A namespace is a logical container for one object type and review workflow (for example: products, users, or messages). Alphanumeric (0-9, a-z), underscore (_), and dashes (-) are supported, and namespace names are case-sensitive.

• You ingest data into a namespace.
• Rules and outputs are configured per namespace.
• Schema is configured per namespace, which in turn control behavior and UI presentation.
• Namespace-level consistency matters because model behavior and workflow outputs are tuned to the patterns you send over time.

Multi-namespace pattern

Many integrations send the same entity to multiple namespaces when they need separate workflows. For example, one product can be sent to both prohibited_items and counterfeit_risk, or one user can be sent to both abuse and fraud.

Use this pattern when:

• each review surface has different rules or ownership
• downstream systems need independent outputs per workflow
• you want to iterate policies independently without coupling all decisions

Recommended handling:

• reuse the same object id across namespaces when it refers to the same entity
• persist one requestId per namespace submission
• process outputs per namespace independently
• define deterministic precedence in your system when namespace decisions conflict

Object

An object is one JSON record in your data payload.

• Every object must include an id.
• The id should be stable for that entity in your system.
• Sending the same id again updates and re-processes that object.
• You can include any additional fields you need, and SafetyKit will preserve useful context for downstream decisions.

Request

A request is one ingest submission to a namespace. It returns a requestId immediately and is processed asynchronously.

{
  "status": "accepted",
  "requestId": "req_01h2m7qdmdjckc30e1mnq6xqfd"
}

Asynchronous processing model

Data API is asynchronous:

1. You submit data.
2. SafetyKit queues and processes each object.
3. You receive per-object outputs via webhook.
4. You can also poll request-level status and results.

This asynchronous model lets you ingest quickly without blocking your application on moderation or risk analysis latency.

Outputs

A completed object can include:

• output.actions: recommended actions from configured rules
• output.labels: applied labels
• output.fields: optional structured fields

For payload examples and handler patterns, see Receiving Results. For endpoint-level details, see the API Reference.