---
title: "Create User Event"
method: POST
path: "/user_events"
tags: ["user-events"]
---

# Create User Event

`POST /user_events`

Create or update a user's association with an event.

- **Catalog attach** (``event_id`` provided): looks up the existing
  ``Event`` and attaches via ``UserEvent.attach``.
- **Prefilled attach** (no ``event_id``): materializes an
  ``Event(data_quality=prefilled)`` from the prefilled payload,
  attaches, and dispatches a ``DiscoverySession(prefilled_confirm)``
  so the discovery worker enriches it asynchronously.

``replace_existing`` (default ``True``) preserves the legacy
single-goal flow that old mobile builds depend on — every other
planned/active row is cancelled before the new one is inserted.
Calendar-aware clients send ``False`` to append.

## Query parameters

- `user_id` string, nullable

## Request body

- UserEventCreateRequest — Request schema for creating/updating a user event. Two payload shapes share this endpoint: - **Catalog attach** (``event_id`` provided): the user picked a race we already have indexed. Backend looks up the ``Event`` and attaches via ``UserEvent.attach``. - **Prefilled attach** (``event_id`` omitted, ``name`` + ``city`` + ``country`` + ``approximate_date`` provided): the user picked a non-catalog recommendation. Backend materializes an ``Event(data_quality=prefilled)``, attaches, and enqueues ``confirm_prefilled_event`` to enrich it via web discovery.
  - `event_id` string, nullable
  - `discipline_name` string, required
  - `distance_km` number, required
  - `sport_type` string, required
  - `elevation_gain_m` integer, nullable
  - `start_time` string, nullable
  - `intent` string, nullable
  - `replace_existing` boolean
  - `name` string, nullable
  - `city` string, nullable
  - `country` string, nullable
  - `approximate_date` string, date, nullable
  - `description` string, nullable

## Response `200`

Successful Response

- object

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/imperfect/apis/imperfect-api.md) · [All operations](https://skmtc.dev/imperfect/apis/imperfect-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/imperfect/imperfect-api/revisions/cc2293a44257/schema)