> For the complete documentation index, see [llms.txt](https://help.twise.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.twise.ai/collections-api-events.md). # Collections API - Events You’ll need to first obtain an API key using [instructions here.](/other/api-guide.md#api-key-management) #### Authentication For all endpoints, when making API requests, add the following auth headers: ``` Twise-Auth-Provider: cli Twise-Auth-Payload: {“token”:””} ``` ## Uploading events **Endpoint** `POST https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents` (tip: you can find the twise\_id in Integrations -> Zapier -> Twise ID) **Request payload fields** This endpoint consumes application/json. | Field | Type | Required | Description | | -------------- | ------------ | -------- | ------------------------------- | | document\_type | boolean | Yes | Should be ‘event’ | | document | Event object | Yes | ‘Event’ object documented below | **Event model** | Field | Type | Required | Description | | -------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | No | If not provided, will automatically generate one. | | title | string | Yes | Event title | | description | string | Yes | Event description | | venue | string | No | Venue name | | url | string | No | URL for event details page | | phone\_number | string (in E.164 format) | No | Contact phone number (in E.164 format) | | contact\_email | string | No | Contact email | | address | string | No | Address | | city | string | No | City (e.g. “Dubai”) | | category | string | No | Category | | date\_start | ISO date string | No | When the event happens/starts. | | date\_end | ISO date string | No |

When the event ends.


date\_end cannot be defined if date\_start is not defined

| | price | string (decimal) | No |

Event ticket price (e.g. “100.50”).


Has to be provided together with currency.

| | currency | string (ISO 4217, 3-letter currency code) | No |

ISO 4217, 3-letter currency code (e.g. “AED”).


Has to be provided together with price.

| | media | List\[string] | No | List of URLs pointing to event images | | price\_range | PriceRange | No | A price range for tickets an event. If provided, product cards will show a price range instead of the price provided in `price`and `currency`fields. | #### Request body example ```json { "document_type": "event", "document": { "id": "event-id-2458", "title": "Desert Safari Adventure with Dinner", "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.", "venue": "Arabian Desert Adventures", "url": "https://desertsafari.ae/evening-adventure", "phone_number": "+97155987654", "contact_email": "bookings@desertsafari.ae", "address": "Pickup from any hotel in Dubai", "city": "Dubai", "category": "Outdoor Adventures", "date_start": "2024-06-15T00:00:00", "date_end": "2025-09-30T00:00:00", "price": "199.0", "currency": "AED", "price_range": { "min_variant_price": { "amount": "199.0", "currency_code": "AED" }, "max_variant_price": { "amount": "349.0", "currency_code": "AED" } }, "media": [ "https://example.com/images/desert-safari-sunset.jpg", "https://example.com/images/desert-safari-dinner.jpg" ] } } ``` **Response Example** ```json { "_id": "67bc6c89e02d505067148ad5", "type": "event", "document_id": "event-id-2458", "document": { "id": "event-id-2458", "title": "Desert Safari Adventure with Dinner", "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.", "venue": "Arabian Desert Adventures", "url": "https://desertsafari.ae/evening-adventure", "phone_number": "+97155987654", "contact_email": "bookings@desertsafari.ae", "address": "Pickup from any hotel in Dubai", "city": "Dubai", "category": "Outdoor Adventures", "date_start": "2024-06-15T00:00:00", "date_end": "2025-09-30T00:00:00", "price": "199.0", "currency": "AED", "price_range": { "min_variant_price": { "amount": "199.0", "currency_code": "AED" }, "max_variant_price": { "amount": "349.0", "currency_code": "AED" } }, "media": [ "https://example.com/images/desert-safari-sunset.jpg", "https://example.com/images/desert-safari-dinner.jpg" ], "display_price": "199.0 AED", "price_float": 199.0 }, "personality_id": "67ab4c6df78156bf40dc813e", "id_suffix": "148ad5", "updated_at": "2025-02-24T12:56:41.028000Z", "uploaded_at": "2025-02-24T12:56:41.028000Z", "twin_feed_sync_id": null } ``` ## Get events **Endpoint** `GET https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents` (tip: you can find the twise\_id in Integrations -> Zapier -> Twise ID) **Request URL params fields** | Field | Type | Required | Description | | -------------- | ------- | -------- | ----------------------------------- | | document\_type | string | Yes | ‘event’ | | per\_page | int | No | number of events to return per page | | is\_featured | boolean | No | gets only ‘featured’ events | | sort | string | No | key to sort by: ‘updated\_at’ | **Response Example** ```json { "total_count": 114, "next_page": 2, "prev_page": null, "results": [ { ... }, ] } ``` ## Update events **Endpoint** `PUT https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents/{_id}` (tip: you can find the twise\_id in Integrations -> Zapier -> Twise ID) **Request payload fields** This endpoint consumes application/json. | Field | Type | Required | Description | | -------- | ------------ | -------- | ------------------------------- | | document | Event object | Yes | ‘Event’ object documented below | | Field | Type | Required | Description | | -------------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | title | string | No | Event title | | description | string | No | Event description | | venue | string | No | Venue name | | url | string | No | URL for event details page | | phone\_number | string (in E.164 format) | No | Contact phone number (in E.164 format) | | contact\_email | string | No | Contact email | | address | string | No | Address | | city | string | No | City (e.g. “Dubai”) | | category | string | No | Category | | date\_start | ISO date string | No | When the event happens/starts. | | date\_end | ISO date string | No |

When the event ends.


date\_end cannot be defined if date\_start is not defined

| | price | string (decimal) | No |

Event ticket price (e.g. “100.50”).


Has to be provided together with currency.

| | currency | string (ISO 4217, 3-letter currency code) | No |

ISO 4217, 3-letter currency code (e.g. “AED”).


Has to be provided together with price.

| | media | List\[string] | No | List of URLs pointing to event images | **Request body example** ```json { "document": { "city": "Abu Dhabi", "address": "Pickup from any hotel in Abu Dhabi" } } ``` **Response example** ```json { "_id": "67bc6c89e02d505067148ad5", "type": "event", "document_id": "event-id-2458", "document": { "id": "event-id-2458", "title": "Desert Safari Adventure with Dinner", "description": "Experience the thrill of dune bashing in a 4x4 vehicle across the golden sands of the Arabian desert. This 6-hour adventure includes camel riding, sandboarding, and a traditional BBQ dinner under the stars with live entertainment featuring belly dancing and tanoura shows. Capture stunning sunset photos and get a henna tattoo as a souvenir of your desert experience.", "venue": "Arabian Desert Adventures", "url": "https://desertsafari.ae/evening-adventure", "phone_number": "+97155987654", "contact_email": "bookings@desertsafari.ae", "address": "Pickup from any hotel in Abu Dhabi", "city": "Abu Dhabi", "category": "Outdoor Adventures", "date_start": "2024-06-15T00:00:00", "date_end": "2025-09-30T00:00:00", "price": "199.0", "currency": "AED", "price_range": { "min_variant_price": { "amount": "199.0", "currency_code": "AED" }, "max_variant_price": { "amount": "349.0", "currency_code": "AED" } }, "media": [ "https://example.com/images/desert-safari-sunset.jpg", "https://example.com/images/desert-safari-dinner.jpg" ], "display_price": "199.0 AED", "price_float": 199.0 }, "personality_id": "67ab4c6df78156bf40dc813e", "id_suffix": "148ad5", "updated_at": "2025-02-24T13:32:40.081000Z", "uploaded_at": "2025-02-24T12:56:41.028000Z", "twin_feed_sync_id": null } ``` ## Delete events #### **Endpoint** `DELETE https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents/{_id}` (tip: you can find the twise\_id in Integrations -> Zapier -> Twise ID) Returns 204 No Content on a successful deletion. ### **Delete events (batch)** You are also able to batch delete documents using: `DELETE https://api3.twise.ai/personalities/{twise_id}/twin/vector_documents` **Usage example** ```sh curl --location --request DELETE 'https://api3.twise.ai/personalities/{twise_id}/twin/documents' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \ --header 'Content-Type: application/json' \ --data '{ "ids": ["67ab248f6ec29515563aec51"] }' ``` **Response example** ```json { "success": true, "num_deleted": 1, "errors": [] } ```