Create event (Beta)

POST/v1/events

Beta. Send a backend event after a meaningful product action happens in your system. Use events for durable server-side context such as account creation, account updates, user-to-user contact, and content uploads. Do not send browser pageviews, button clicks, or other client-only telemetry through this endpoint.

Body ParametersJSONExpand Collapse

body: object { event_name, target_user_id, timestamp, 5 more } or object { content, event_name, timestamp, 4 more } or object { event_name, timestamp, type, 4 more } or 2 more

Backend event or ordered batch of events to send to SafetyKit. Send events from your server after an action has happened in your product. Do not send these events directly from a browser or mobile client.

One of the following:

UserContactEventRequest object { event_name, target_user_id, timestamp, 5 more }

A user contacts, transacts with, or otherwise interacts with another user.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

target_user_id: string

Your stable canonical identifier for the other user in a user-to-user interaction.

minLength1

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "user_contact"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

ContentUploadedEventRequest object { content, event_name, timestamp, 4 more }

A user posts, uploads, publishes, edits, or replaces content.

content: array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "content_uploaded"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

CreateAccountEventRequest object { event_name, timestamp, type, 4 more }

A user or account is created.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "create_account"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

UpdateAccountEventRequest object { event_name, timestamp, type, 4 more }

A user or account profile, contact detail, payment detail, or public bio changes.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "update_account"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

array of object { event_name, target_user_id, timestamp, 5 more } or object { content, event_name, timestamp, 4 more } or object { event_name, timestamp, type, 4 more } or object { event_name, timestamp, type, 4 more }

One of the following:

UserContact object { event_name, target_user_id, timestamp, 5 more }

A user contacts, transacts with, or otherwise interacts with another user.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

target_user_id: string

Your stable canonical identifier for the other user in a user-to-user interaction.

minLength1

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "user_contact"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

ContentUploaded object { content, event_name, timestamp, 4 more }

A user posts, uploads, publishes, edits, or replaces content.

content: array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "content_uploaded"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

CreateAccount object { event_name, timestamp, type, 4 more }

A user or account is created.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "create_account"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

UpdateAccount object { event_name, timestamp, type, 4 more }

A user or account profile, contact detail, payment detail, or public bio changes.

event_name: string

Stable, low-cardinality product action name. Use snake_case and put dynamic values in typed fields, content, resources_used, or metadata.

timestamp: string

The time the event occurred in your system, as an ISO 8601 datetime string.

formatdate-time

type: "update_account"

user_id: string

Your stable canonical identifier for the user or account.

minLength1

content: optional array of object { text, type, key } or object { source, type, key }

User-authored or user-uploaded content parts. Use this for message bodies, bios, listing text, image URLs, and similar content SafetyKit should compare or analyze.

One of the following:

EventTextContent object { text, type, key }

User-authored text content associated with an event.

text: string

User-authored text SafetyKit should compare or analyze.

type: "text"

Text content part.

key: optional string

Stable field key for this content part.

EventImageContent object { source, type, key }

User-uploaded image content associated with an event.

source: object { type, url }

Image source information.

type: "url"

URL image source.

url: string

URL of the image SafetyKit should compare or analyze.

formaturi

type: "image"

Image content part.

key: optional string

Stable field key for this content part.

metadata: optional map[string or number or boolean or array of string or number or boolean]

Non-PII product context for filtering, segmentation, and debugging. Values may be strings, numbers, booleans, or arrays of those scalar values.

One of the following:

string

number

boolean

array of string or number or boolean

One of the following:

string

number

boolean

resources_used: optional array of object { type, value }

Reusable resources observed during the event. Use this for emails, phone numbers, names, addresses, social handles, URLs, payment identifiers, or similar identifiers.

type: string

Resource family, such as email, phone, name, address, url, instagram, tiktok, youtube, linkedin, or another stable snake_case identifier.

value: string

Resource value used during the event. SafetyKit stores a normalized hash of this value, not the raw value. When type is url, this must be a valid URL.

minLength1

ReturnsExpand Collapse

object { event_id, status }

event_id: string

SafetyKit identifier for the event.

status: "ok"

Event was accepted.

object { event_ids, status }

event_ids: array of string

SafetyKit identifiers for the accepted events, in request order.

status: "ok"

Events were accepted.

Create event (Beta)

curl https://api.safetykit.com/v1/events \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $SAFETYKIT_API_KEY" \
    -d '{
          "event_name": "message_sent",
          "target_user_id": "987654321",
          "timestamp": "2026-05-21T00:15:15.000Z",
          "type": "user_contact",
          "user_id": "123456789",
          "metadata": {
            "conversation_id": "conversation_789",
            "channel": "marketplace_dm"
          }
        }'

{
  "status": "ok",
  "event_id": "01KSR4C8JN1SA9X63T6P368K6W"
}

{
  "status": "ok",
  "event_ids": [
    "01KSR4C8JN1SA9X63T6P368K6W",
    "01KSR4CB1MFVX1TAYM46YQXZ3E"
  ]
}

Returns Examples

{
  "status": "ok",
  "event_id": "01KSR4C8JN1SA9X63T6P368K6W"
}

{
  "status": "ok",
  "event_ids": [
    "01KSR4C8JN1SA9X63T6P368K6W",
    "01KSR4CB1MFVX1TAYM46YQXZ3E"
  ]
}