API Guide

Training Your AI with Knowledge Cards and Content Integration

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: https://app.twise.ai/signup using the email address that will own billing

• Start the paid Enterprise plan here: https://app.twise.ai/admin/plan 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”:”<your_api_key>”}

Adding 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": "<download url>",
    "source_document": null,
    "metadata": null,
    "indexing": { # document indexing status
        "status": "submitted",
        "num_batches": null,
        "processed_batches_count": 0
    }
}

Usage examples

Creating a knowledge card

You can think of a knowledge card 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/<YOUR_TWISE_ID_HERE>/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.

Uploading a PDF:

curl --location 'https://api3.twise.ai/personalities/<YOUR_TWISE_ID_HERE>/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"'

Uploading an image:

curl --location 'https://api3.twise.ai/<YOUR_TWISE_ID_HERE>/</twin/documents' \
--header 'Twise-Auth-Provider: cli' \
--header 'Twise-Auth-Payload: {"token":"sk_xxx"}' \
--form 'document_file=@"/wine_tasting.jpg"' \
--form 'description="Wine Tasting"' \
--form 'is_public="true"' \
--form 'is_downloadable="true"' \
--form 'extract_answers="false"'

The request will upload an image that will be displayed as part of a Twise answer if the subject of the conversation is about ‘Wine Tasting’.

Adding a YouTube video:

curl --location 'https://api3.twise.ai/personalities/<YOUR_TWISE_ID_HERE>/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.