# 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": [] } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.twise.ai/collections-api-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.