# Beta

# Events

## 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 Parameters

- `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.

  - `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.

    - `timestamp: string`

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

    - `type: "user_contact"`

      - `"user_contact"`

    - `user_id: string`

      Your stable canonical identifier for the user or account.

    - `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.

      - `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.

          - `"text"`

        - `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"`

          - `url: string`

            URL of the image SafetyKit should compare or analyze.

        - `type: "image"`

          Image content part.

          - `"image"`

        - `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.

      - `string`

      - `number`

      - `boolean`

      - `array of string or number or boolean`

        - `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.

  - `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.

      - `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.

          - `"text"`

        - `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"`

          - `url: string`

            URL of the image SafetyKit should compare or analyze.

        - `type: "image"`

          Image content part.

          - `"image"`

        - `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.

    - `type: "content_uploaded"`

      - `"content_uploaded"`

    - `user_id: string`

      Your stable canonical identifier for the user or account.

    - `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.

      - `string`

      - `number`

      - `boolean`

      - `array of string or number or boolean`

        - `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.

  - `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.

    - `type: "create_account"`

      - `"create_account"`

    - `user_id: string`

      Your stable canonical identifier for the user or account.

    - `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.

      - `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.

          - `"text"`

        - `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"`

          - `url: string`

            URL of the image SafetyKit should compare or analyze.

        - `type: "image"`

          Image content part.

          - `"image"`

        - `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.

      - `string`

      - `number`

      - `boolean`

      - `array of string or number or boolean`

        - `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.

  - `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.

    - `type: "update_account"`

      - `"update_account"`

    - `user_id: string`

      Your stable canonical identifier for the user or account.

    - `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.

      - `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.

          - `"text"`

        - `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"`

          - `url: string`

            URL of the image SafetyKit should compare or analyze.

        - `type: "image"`

          Image content part.

          - `"image"`

        - `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.

      - `string`

      - `number`

      - `boolean`

      - `array of string or number or boolean`

        - `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.

  - `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 }`

    - `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.

      - `timestamp: string`

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

      - `type: "user_contact"`

        - `"user_contact"`

      - `user_id: string`

        Your stable canonical identifier for the user or account.

      - `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.

        - `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.

            - `"text"`

          - `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"`

            - `url: string`

              URL of the image SafetyKit should compare or analyze.

          - `type: "image"`

            Image content part.

            - `"image"`

          - `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.

        - `string`

        - `number`

        - `boolean`

        - `array of string or number or boolean`

          - `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.

    - `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.

        - `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.

            - `"text"`

          - `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"`

            - `url: string`

              URL of the image SafetyKit should compare or analyze.

          - `type: "image"`

            Image content part.

            - `"image"`

          - `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.

      - `type: "content_uploaded"`

        - `"content_uploaded"`

      - `user_id: string`

        Your stable canonical identifier for the user or account.

      - `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.

        - `string`

        - `number`

        - `boolean`

        - `array of string or number or boolean`

          - `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.

    - `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.

      - `type: "create_account"`

        - `"create_account"`

      - `user_id: string`

        Your stable canonical identifier for the user or account.

      - `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.

        - `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.

            - `"text"`

          - `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"`

            - `url: string`

              URL of the image SafetyKit should compare or analyze.

          - `type: "image"`

            Image content part.

            - `"image"`

          - `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.

        - `string`

        - `number`

        - `boolean`

        - `array of string or number or boolean`

          - `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.

    - `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.

      - `type: "update_account"`

        - `"update_account"`

      - `user_id: string`

        Your stable canonical identifier for the user or account.

      - `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.

        - `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.

            - `"text"`

          - `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"`

            - `url: string`

              URL of the image SafetyKit should compare or analyze.

          - `type: "image"`

            Image content part.

            - `"image"`

          - `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.

        - `string`

        - `number`

        - `boolean`

        - `array of string or number or boolean`

          - `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.

### Returns

- `object { event_id, status }`

  - `event_id: string`

    SafetyKit identifier for the event.

  - `status: "ok"`

    Event was accepted.

    - `"ok"`

- `object { event_ids, status }`

  - `event_ids: array of string`

    SafetyKit identifiers for the accepted events, in request order.

  - `status: "ok"`

    Events were accepted.

    - `"ok"`

### Example

```http
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"
          }
        }'
```

#### Response

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

## Domain Types

### Event Create Response

- `EventCreateResponse = object { event_id, status }  or object { event_ids, status }`

  Response returned after SafetyKit accepts one event or an ordered event batch.

  - `object { event_id, status }`

    - `event_id: string`

      SafetyKit identifier for the event.

    - `status: "ok"`

      Event was accepted.

      - `"ok"`

  - `object { event_ids, status }`

    - `event_ids: array of string`

      SafetyKit identifiers for the accepted events, in request order.

    - `status: "ok"`

      Events were accepted.

      - `"ok"`