# API Guide ### Introduction Twise transforms uploaded content into Knowledge Cards, enabling advanced Retrieval-Augmented Generation (RAG). These cards are highly controllable units of knowledge that your AI can utilize to answer questions, provide context, and deliver personalized outputs. By uploading content such as PDFs, images, text, or videos, you can train Twise to provide accurate, relevant, and visually engaging responses. Each piece of uploaded content becomes a foundational part of your AI’s “brain,” enhancing its ability to serve your website visitors seamlessly. This guide explains how to interact with Twise’s API, including generating an API key, authenticating requests, and leveraging endpoints for uploading and managing content. ### Before you get started You will need to have created an account with Twise as well as be on the paid Enterprise plan * Sign up for an account here: using the email address that will own billing * Start the paid Enterprise plan here: using a credit card ### API Key Management #### Generating an API key To make requests to the Twise API, you’ll need an API key. Follow these steps to generate one: 1\. Create a test Twise instance in the /admin page: • Use the ‘Create from Website’ or ‘New from Scratch’ options. 2\. Navigate to Settings of your Twise instance: • Go to Edit Twise -> Integrations -> Zapier. • Generate and save your API key. ⚠️ Important: Save your API key securely as it will only be shown once. Generating a new key will invalidate the existing one. ### Authentication When making API requests, include the following authentication headers: ``` Twise-Auth-Provider: cli Twise-Auth-Payload: {“token”:””} ``` ### Creating new content #### Endpoint ``` POST https://api3.twise.ai/personalities/{twise_id}/twin/documents ``` You can find the twise\_id in Integrations -> Zapier -> Twise ID. #### Request payload fields This endpoint consumes multipart/form-data. All form fields should be provided accordingly. At least one of document\_file, text\_content, or url must be provided.

Field	Type	Required	Description	Example value
is_public	boolean	Yes	Should be true. Indicates whether a document is going to be retrievable by the twise.	true
description	string	No	Text describing the nature of the document. For images, ‘description’ field determines the relevance of the document to the answer.	How to Win at Chess
document_file	file	No	The file to upload (PDF, image, text file, etc.). If not provided, text_content or url should be provided.	@”/how-to-win-at-chess.pdf”
text_content	string	No	Raw text content of the document. If not provided, document_file or url should be used.
url	str	No	URL pointing to a Youtube resource. If not provided, document_file or text_content should be used.	https://www.youtube.com/watch?v=dQw4w9WgXcQ
is_downloadable	boolean	No	Specifies whether the document is going to be displayed as part of an answer (e.g. in case of images). Defaults to false	false
extract_text	bool	No	If true, extracts text content from the uploaded document. Defaults to false.	true
extract_answers	bool	No	If true, generates knowledge cards (question-answer pairs) from the document text. Defaults to false.	true
extract_images	bool	No	(Only for html documents) If true, will extract images from the html file. Defaults to false.	false
split_into_slides	bool	No	(Only for PDF files) If true, will extract every PDF page as an image. Defaults to false.	false
describe_slides	bool	No	(Only for PDF files) If true, generates a description for each extracted image from each PDF page. Defaults to false.	false

**Response example** ``` { "_id": "67593c803df3039e26c15fa6", "id_suffix": "c15fa6", "personality_id": "67593b4fd2c0e595c08b575c", # twise id document belongs to "content_type": "application/pdf", "size": 75435, "is_public": true, "is_downloadable": false, "display_options": { "autoplay": false, "mute": false, "loop": false, "hide_controls": false }, "uploaded_at": "2024-12-11T07:17:20.936000+00:00", "description": "Assignment 2", "text_content": null, "url": null, "twin_crawl_id": null, "source_document_id": null, "filename": "Assignment 2_CSCI115.pdf", "blob_name": "67593b4fd2c0e595c08b575c/Assignment 2_CSCI115.pdf", "extract_answers": true, "download_url": "", "source_document": null, "metadata": null, "indexing": { # document indexing status "status": "submitted", "num_batches": null, "processed_batches_count": 0 } } ``` **Usage example - c**reating a knowledge card You can think of a [knowledge card ](https://help.twise.ai/content/knowledge-cards)as the core way the AI will source its answers. The knowledge cards are question and answer pairs which upon creation can also be edited through the admin. The knowledge card can be a simple answer to a question but it can also contain all the information about for example a product, like the price, location and a link to learn more. ``` curl --location 'http://localhost:8001/personalities//twin/documents' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \ --form 'description="What is the name of our planet?"' \ --form 'text_content="Earth"' --form 'is_public="true"' \ --form 'is_downloadable="false"' \ ``` This creates a knowledge card, a question and answer pair for the Twise to use. **Note**: with all the examples here, you can see new content appearing in Edit Twise -> Content -> Knowledge/Media pages. ### Updating content **Endpoint** ``` PUT https://api3.twise.ai/personalities/{twise_id}/twin/documents/{document_id} ``` **Request payload fields** This endpoint consumes multipart/form-data. All form fields should be provided accordingly. At least one of document\_file, text\_content, or url must be provided. | Field | Type | Required | Description | Example Value | | ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | is\_public | boolean | No | Indicates whether a document is going to be retrievable by the twise. | true | | description | string | No |

Text describing the nature of the document.

For images, ‘description’ field determines the relevance of the document to the answer.

| | url | str | No | URL for a resource. | | | is\_downloadable | boolean | No | Specifies whether the document is going to be displayed as part of an answer (e.g. in case of images). Defaults to false | false | **Response example** ``` { "personality_id": "6757ec1ff471b684b0df0a43", "content_type": "text/plain", "size": 4, "is_public": true, "is_downloadable": false, "display_options": { "autoplay": false, "mute": false, "loop": false, "hide_controls": false }, "uploaded_at": "2024-12-10T07:24:02.149000Z", "description": "What year is it now?", "text_content": "2025", "url": null, "twin_crawl_id": null, "source_document_id": "6757ec2df471b684b0df0a45", "_id": "6757ec92f471b684b0df0b9f", "id_suffix": "df0b9f", "filename": null, "blob_name": null, "extract_answers": false, "download_url": null, "source_document": null, "metadata": null, "indexing": { "status": "submitted", "num_batches": null, "processed_batches_count": 0 } } ``` #### Usage Examples **Updating knowledge card content:** ``` curl --location --request PUT 'https://api3.twise.ai/personalities//twin/documents/' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \ --form 'text_content="2025"' \ --form 'description="What year is it now?"' ``` ### Deleting content **Endpoint** ``` DELETE https://api3.twise.ai/personalities/{twise_id}/twin/documents/{document_id} ``` Returns 204 No Content on a successful deletion. \ **Usage example** ``` curl --location --request DELETE 'https://api3.twise.ai/personalities//twin/documents/' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' ``` ### Batch delete documents You are also able to batch delete documents using: ``` DELETE https://api3.twise.ai/personalities/{twise_id}/twin/documents ``` **Usage example** ``` 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": ["6757ec92f471b684b0df0b9f"] }' ``` \ **Response example** ``` { "success": true, "num_deleted": 1, "errors": [] } ``` ### Adding images Images works like other documents and can be updated or deleted in the same way as knowledge cards. **Example request:** ``` curl --location 'https://api3.twise.ai///twin/documents' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \ --form 'description="Rick Astley - Never Gonna Give You Up"' \ --form 'is_public="true"' \ --form 'is_downloadable="true"' \ --form 'url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"' \ --form 'extract_answers="false"' \ --form 'extract_text="false"' ``` The YouTube video is going to be displayed as part of a Twise answer when relevant. If extract\_text is true, the audio transcript from the YT video is going to be stored as context. If extract\_answers is true, the audio transcript from the video is converted into knowledge cards. #### Uploading a PDF: ``` curl --location 'https://api3.twise.ai/personalities//twin/documents' \ --header 'Twise-Auth-Provider: cli' \ --header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \ --form 'document_file=@"/how-to-win-at-chess.pdf"' \ --form 'description="How to Win At Chess"' \ --form 'is_public="true"' \ --form 'is_downloadable="false"' \ --form 'extract_answers="true"' ```