skills/ycloud-custom-events/references/openapi.md

<!-- Generated by scripts/build_openapi_skill_references.py; do not edit. -->
# OpenAPI contract: Custom events

## Provenance

- Source: `ycloud-api-v2.yaml` (pinned release snapshot).
- Source SHA-256: `8592bd4cc37186655a480dd86ce6bac6731543727327a2871d9103a0b8ed9e81`
- OpenAPI version: `3.0.0`
- API info.version: `v2`
- This derived reference does not replace the upstream API Owner's canonical source.
- Generated deterministically from normalized JSON; do not edit this file by hand.

## Scope and handoff

- These seven operations cover event definitions, property definitions, and ingestion. Definition lifecycle and accepted event ingestion remain separate.
- Operation coverage: `7`

## Operations

### `POST /event/definitions` — `custom_events-create-definition`

- Summary: Create an event definition
- Description:
  > Creates a custom event definition.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/CustomEventDefinitionCreateRequest`
    - `$ref`: `#/components/schemas/CustomEventDefinitionCreateRequest`
- Responses:
  - `200`: Successfully created an event definition.
    - `application/json`: `#/components/schemas/CustomEventDefinition`
      - `$ref`: `#/components/schemas/CustomEventDefinition`

### `POST /event/definitions/{name}/properties` — `custom_events-create-property-definition`

- Summary: Create an event property definition
- Description:
  > Defines a new property for the event definition.
- Parameters:
  - `name` (path, required): `string`
    > Name of the custom event.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"
- Request body: required
  - `application/json`: `#/components/schemas/CustomEventDefinitionPropertyCreateRequest`
    - `$ref`: `#/components/schemas/CustomEventDefinitionPropertyCreateRequest`
- Responses:
  - `200`: Successfully created an event property.
    - `application/json`: `#/components/schemas/CustomEventDefinitionProperty`
      - `$ref`: `#/components/schemas/CustomEventDefinitionProperty`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `GET /event/definitions/{name}` — `custom_events-retrieve-definition`

- Summary: Retrieve an event definition
- Description:
  > Retrieves a custom event definition you previously created.
- Parameters:
  - `name` (path, required): `string`
    > Name of the custom event.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"
- Request body: none
- Responses:
  - `200`: Successfully retrieved the event definition.
    - `application/json`: `#/components/schemas/CustomEventDefinition`
      - `$ref`: `#/components/schemas/CustomEventDefinition`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `POST /event/events` — `custom_events-send-event`

- Summary: Send an event
- Description:
  > Sends an event.
- Parameters: none
- Request body: required
  - `application/json`: `#/components/schemas/CustomEventSendRequest`
    - `$ref`: `#/components/schemas/CustomEventSendRequest`
- Responses:
  - `200`: Successfully sent the event.

### `PATCH /event/definitions/{name}` — `custom_events-update-definition`

- Summary: Update an event definition
- Description:
  > Updates an event definition's label and description.
- Parameters:
  - `name` (path, required): `string`
    > Name of the custom event.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"
- Request body: required
  - `application/json`: `#/components/schemas/CustomEventDefinitionUpdateRequest`
    - `$ref`: `#/components/schemas/CustomEventDefinitionUpdateRequest`
- Responses:
  - `200`: Successfully updated the event definition.
    - `application/json`: `#/components/schemas/CustomEventDefinition`
      - `$ref`: `#/components/schemas/CustomEventDefinition`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `DELETE /event/definitions/{name}/properties/{propertyName}` — `custom_events_delete-property-definition`

- Summary: Delete an event property definition
- Description:
  > Deletes a property of the event definition.
- Parameters:
  - `name` (path, required): `string`
    > Name of the custom event.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"
  - `propertyName` (path, required): `string`
    > Name of the custom event property.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_property_name"
- Request body: none
- Responses:
  - `200`: Successfully deleted the event property definition.
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

### `PATCH /event/definitions/{name}/properties/{propertyName}` — `custom_events_update-property-definition`

- Summary: Update an event property definition
- Description:
  > Updates an event property definition's label and description.
- Parameters:
  - `name` (path, required): `string`
    > Name of the custom event.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"
  - `propertyName` (path, required): `string`
    > Name of the custom event property.
    - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_property_name"
- Request body: required
  - `application/json`: `#/components/schemas/CustomEventDefinitionPropertyUpdateRequest`
    - `$ref`: `#/components/schemas/CustomEventDefinitionPropertyUpdateRequest`
- Responses:
  - `200`: Successfully updated the event property definition.
    - `application/json`: `#/components/schemas/CustomEventDefinitionProperty`
      - `$ref`: `#/components/schemas/CustomEventDefinitionProperty`
  - `404`: The requested resource does not exist.
    - `application/json`: `#/components/schemas/ErrorResponse`
      - `$ref`: `#/components/schemas/ErrorResponse`

## Referenced schema and parameter shapes

### `name-in_path_for_custom_event`

- Reference: `#/components/parameters/name-in_path_for_custom_event`
- Parameter name: `name`
- Location: `path`
- Required: `true`
- Description:
  > Name of the custom event.
- Schema: `string`
  - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_event_name"

### `name-in_path_for_custom_event_property`

- Reference: `#/components/parameters/name-in_path_for_custom_event_property`
- Parameter name: `propertyName`
- Location: `path`
- Required: `true`
- Description:
  > Name of the custom event property.
- Schema: `string`
  - Constraints: pattern="[a-z0-9_]{1,50}"; example="unique_property_name"

### `CustomEventDefinition`

- Reference: `#/components/schemas/CustomEventDefinition`
- Shape: `object`
  - Description:
    > Represents a custom event definition.
  - Properties:
    - `createTime`: `string (date-time)`
      - Description:
        > The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
      - Constraints: example="2024-08-22T00:00:00.000Z"
    - `description`: `string`
      - Description:
        > The description of the event definition.
      - Constraints: example="Describes this property"
    - `label`: `string`
      - Description:
        > The label of the event definition, used for display purposes.
      - Constraints: maxLength=50; example="Property Label"
    - `name`: `string`
      - Description:
        > The name of the custom event definition.
      - Constraints: example="propertyName"
    - `objectType`: `string`
      - Description:
        > Type of the object that the event will be associated with.
        > - `CONTACT`: Indicates that the object is a `contact`.
      - Constraints: enum=["CONTACT"]; example="CONTACT"
    - `properties`: `array`
      - Description:
        > The list of property definitions for the event definition.
      - Items: `#/components/schemas/CustomEventDefinitionProperty`

### `CustomEventDefinitionCreateRequest`

- Reference: `#/components/schemas/CustomEventDefinitionCreateRequest`
- Shape: `object`
  - Description:
    > Contains the properties of the custom event definition to be created.
  - Required properties: `name`, `label`, `objectType`
  - Properties:
    - `description`: `string`
      - Description:
        > The description of the event.
      - Constraints: maxLength=200; example="Describes this event"
    - `label`: `string` (required)
      - Description:
        > The label of the custom event.
      - Constraints: example="My event label"
    - `name`: `string` (required)
      - Description:
        > The unique name of the custom event.
      - Constraints: maxLength=50; pattern="^[a-z0-9_]{1,50}"; example="unique_event_name"
    - `objectType`: `string` (required)
      - Description:
        > Type of the object that the event will be associated with.
        > - `CONTACT`: Indicates that the object is a `contact`.
      - Constraints: enum=["CONTACT"]; example="CONTACT"
    - `properties`: `array`
      - Description:
        > A list of property definitions for the event.
      - Items: `#/components/schemas/CustomEventDefinitionPropertyCreateRequest`

### `CustomEventDefinitionProperty`

- Reference: `#/components/schemas/CustomEventDefinitionProperty`
- Shape: `object`
  - Description:
    > Represents a custom property of a custom event definition.
  - Properties:
    - `createTime`: `string (date-time)`
      - Description:
        > The time at which this object is created, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`.
      - Constraints: example="2024-08-22T00:00:00.000Z"
    - `description`: `string`
      - Description:
        > The description of the property.
      - Constraints: example="Describes this property"
    - `label`: `string`
      - Description:
        > The label of the property, used for display purposes.
      - Constraints: maxLength=50; example="Property Label"
    - `name`: `string`
      - Description:
        > The name of the custom property.
      - Constraints: example="propertyName"
    - `type`: `string`
      - Description:
        > The data type of the property.
        > - `STRING`: Indicates a property that receives plain text strings.
        > - `NUMBER`: Indicates a property that receives numeric values with up to one decimal.
        > - `TIMESTAMP`: Indicates a property that receives epoch millisecond.
        > - `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`.
      - Constraints: enum=["STRING", "NUMBER", "TIMESTAMP", "URL"]

### `CustomEventDefinitionPropertyCreateRequest`

- Reference: `#/components/schemas/CustomEventDefinitionPropertyCreateRequest`
- Shape: `object`
  - Description:
    > Contains the properties of the custom event property definition to be created.
  - Required properties: `name`, `label`, `type`
  - Properties:
    - `description`: `string`
      - Description:
        > The description of the property.
      - Constraints: example="Describes this property"
    - `label`: `string` (required)
      - Description:
        > The label of the property.
      - Constraints: maxLength=50; example="Property Label"
    - `name`: `string` (required)
      - Description:
        > The unique name of the custom property.
      - Constraints: maxLength=50; pattern="^[a-z][a-z0-9_]{1,50}$"; example="unique_property_name"
    - `type`: `string` (required)
      - Description:
        > Type of the property.
        > - `STRING`: Indicates a property that receives plain text strings.
        > - `NUMBER`: Indicates a property that receives numeric values with up to one decimal.
        > - `TIMESTAMP`: Indicates a property that receives epoch millisecond.
        > - `URL`: Indicates a property that receives URLs, formatted as strings starting with `http://` or `https://`.
      - Constraints: enum=["STRING", "NUMBER", "TIMESTAMP", "URL"]; example="STRING"

### `CustomEventDefinitionPropertyUpdateRequest`

- Reference: `#/components/schemas/CustomEventDefinitionPropertyUpdateRequest`
- Shape: `object`
  - Description:
    > Contains the properties of the event property definition to be updated.
  - Properties:
    - `description`: `string`
      - Description:
        > The description of the event property definition.
      - Constraints: example="Describes the event property"
    - `label`: `string`
      - Description:
        > The label of the event property definition.
      - Constraints: example="New label"

### `CustomEventDefinitionUpdateRequest`

- Reference: `#/components/schemas/CustomEventDefinitionUpdateRequest`
- Shape: `object`
  - Description:
    > Contains the properties of the custom event definition to be updated.
  - Properties:
    - `description`: `string`
      - Description:
        > The description of the event definition.
      - Constraints: example="Describes the event definition"
    - `label`: `string`
      - Description:
        > The label of the event definition.
      - Constraints: example="New Label"

### `CustomEventSendRequest`

- Reference: `#/components/schemas/CustomEventSendRequest`
- Shape: `object`
  - Description:
    > Contains the properties of the custom event data to be sent.
  - Required properties: `eventName`
  - Properties:
    - `contactPhoneNumber`: `string`
      - Description:
        > The phone number of the contact for events defined with `objectType` as `CONTACT`.
    - `eventName`: `string` (required)
      - Description:
        > Name of the event.
        > One of the custom event names you previously defined.
      - Constraints: example="unique_event_name"
    - `objectId`: `string`
      - Description:
        > ID of the object that the event is associated with.
        > For events defined with `objectType` as `CONTACT`, the `objectId` should be a `contact` ID. Alternatively, you can use the `contactPhoneNumber` field to specify the contact.
    - `occurTime`: `string (date-time)`
      - Description:
        > The time at which the event occurred, formatted in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339). e.g., `2022-06-01T12:00:00.000Z`,
        > if not provided, the current time will be used.
      - Constraints: example="2022-06-01T12:00:00.000Z"
    - `properties`: `object`
      - Description:
        > The properties of the custom event.
      - Constraints: additionalProperties={"type": "object"}; example={"property1": "value1", "property2": "value2"}

### `Error`

- Reference: `#/components/schemas/Error`
- Shape: `object`
  - Required properties: `status`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > One of a server-defined error codes. Some `4xx` errors that could be handled programmatically include an error code that briefly explains the error reported.
      - Constraints: example="NOT_FOUND"
    - `docUrl`: `string`
      - Description:
        > A URL to more information about the error.
      - Constraints: example=""
    - `message`: `string`
      - Description:
        > A human-readable representation of the error. It is intended as an aid to developers and is not suitable for exposure to end users.
      - Constraints: example="The requested resource does not exist."
    - `requestId`: `string`
      - Description:
        > Each API request has an associated request ID. It conveys the response header `YCloud-Request-ID` used for the convenience of the consumer.
      - Constraints: example="req_1KjtKI80IKoaJNa6n6p"
    - `status`: `integer (int32)` (required)
      - Description:
        > HTTP status code, [RFC 7231, Section 6](https://datatracker.ietf.org/doc/html/rfc7231#section-6). It conveys the HTTP status code used for the convenience of the consumer.
      - Constraints: pattern="[45]\\d{2}"; example=404
    - `target`: `string`
      - Description:
        > The target of the error.
      - Constraints: example=""
    - `whatsappApiError`: `#/components/schemas/WhatsappApiError`
      - Description:
        > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
        >
        > Note: This field is returned if we tried to request the WhatsApp Business API and got an error response.

### `ErrorResponse`

- Reference: `#/components/schemas/ErrorResponse`
- Shape: `object`
  - Required properties: `error`
  - Properties:
    - `error`: `#/components/schemas/Error` (required)

### `WhatsappApiError`

- Reference: `#/components/schemas/WhatsappApiError`
- Shape: `object`
  - Description:
    > The original error object returned by WhatsApp. See [Handling Errors](https://developers.facebook.com/docs/graph-api/guides/error-handling), [Cloud API Error Codes](https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes).
  - Required properties: `message`, `code`
  - Properties:
    - `code`: `string` (required)
      - Description:
        > An error code.
      - Constraints: example=200002
    - `error_data`: `object`
      - Description:
        > Additional data about the error. A string or map.
        > - For template APIs, this field is a string describing the reason for the error.
        > - For message APIs, this field is a map with property `details` describing the reason for the error.
    - `error_subcode`: `string`
      - Description:
        > Additional code about the error.
      - Constraints: example=2388109
    - `error_user_msg`: `string`
      - Description:
        > The message to display to the user. The language of the message is based on the locale of the API request.
      - Constraints: example="This message template cannot be created."
    - `error_user_title`: `string`
      - Description:
        > The title of the dialog, if shown. The language of the message is based on the locale of the API request.
      - Constraints: example="Message Cannot Be Submitted"
    - `fbtrace_id`: `string`
      - Description:
        > Internal support identifier. When reporting a bug related to a Graph API call, include the fbtrace_id to help us find log data for debugging.
      - Constraints: example="AVGjJ7ia2zJkrHG"
    - `is_transient`: `boolean`
      - Description:
        > Whether the error is transient.
      - Constraints: example=false
    - `message`: `string` (required)
      - Description:
        > A human-readable description of the error.
      - Constraints: example="HSM Template creation failed"
    - `type`: `string`
      - Description:
        > Error type.
      - Constraints: example="OAuthException"

## Codegen interpretation and unknowns

- `operationId` identifies the OpenAPI operation; it is not an SDK method name.
- `allOf` is wire-level schema composition. Response adapters must merge inherited and local properties; generated model inheritance/flattening is only a codegen shape, not additional API behavior.
- `x-group-parameters`, `x-enum-varnames`, and `x-enum-descriptions` are generator hints, not business rules.
- Description-only constraints (including conditional fields, precedence, and endpoint-specific behavior) remain verbatim above.
- This OpenAPI snapshot does not confirm cross-cutting error, retry/`Retry-After`, rate-limit, idempotency, delivery, or webhook-signature behavior. Consult the reviewed `runtime.md`; if neither source confirms a fact, do not fill it in.