AskYourPDF is a cutting-edge solution revolutionizing document interactions. Our API empowers developers with the ability to programmatically extract valuable information from PDF files and leverage it to create custom chatbots. By providing seamless access to the content within PDF documents, developers can build powerful applications that enable users to navigate, search, and engage with data effortlessly. This comprehensive guide will walk you through the API's features, pricing, authentication methods, and usage guidelines, opening up endless possibilities to enhance productivity and knowledge retrieval for your applications. Harness the potential of AskYourPDF API and embark on an innovative journey of intelligent document analysis and interactive experiences.
Uploading A Document
To upload a document, choose between generating a document ID on our website or using the API endpoint. We support various document formats, including '.pdf', '.txt', '.ppt', '.pptx', '.csv', '.epub', and '.rtf'. Additionally, you can upload PDFs using links. Moreover, the API enables interaction with any blog post or website by providing the link to the post.
Authentication
Authentication is required for all our API endpoints. To access them, you must generate API keys on your AskYourPDF account. These API keys need to be set in your request header as "x-api-key." It is essential to treat your API key as a secret and ensure its protection.
headers: {"x-api-key":"ask_xxxxx" }
1. Adding Document via URL
Query Parameters:
url (required): The link to the document. It could be a link to a PDF or a post on a website
Response:
201 Successful Response
doc_id (string): The document ID of the uploaded document.
Endpoint for initiating a chat with a document. This endpoint requires API Key Header authentication.
Path Parameters:
doc_id (string, required): The ID of the document for the conversation.
Query Parameters:
stream (boolean, optional): Flag for streaming. Default is false
model_name (string, optional) : The model the user chooses to use, model choices includes CLAUDE1, CLAUDE2, GPT3, GPT4, GPT4O_MINI. Default model is GPT4O_MINI
cite_source (boolean, optional) : Flag for cite_source. Default if false
temperature (float, optional) : Flag for temperature. Default is 0.7
language (string, optional) : The language the user chooses to chat with, language choices include ENGLISH, ARABIC, CHINESE, JAPANESE, FRENCH , GERMAN, SPANISH, KOREAN, PORTUGESE. Default language is ENGLISH.
length (string, optional) : This option allows you to choose the desired length of the response. Choices includes LONG and SHORT. Default value is SHORT
Request body:
sender (required): The sender of the chat message. The sender should be User
message (required): The chat message content.
The request body to ask a single question.
[ {"sender":"User","message":"What does this document say?" }]
To ask a follow-up question and provide the model with context you can send your previous questions and responses in the following format.
[ { "sender":"user","message":"What does the document say?" }, {"sender":"bot","message":"The document consists of words in different languages expressing gratitude" }, {"sender":"user","message":"What is the word expressing gratitude in Spanish?" }]
Response:
The response when the query parameter stream = False
200 Successful Response
question: The question posed by the user, with sender, message, and type.
sender
message
type
answer: The answer provided by the AI, with sender, message, and type.
sender
message
type
created (string): The time the chat was created.
{"question": {"sender":"user","message":"What does this document say?","type":"question" },"answer": {"sender":"bot","message":"This document talks about AI","type":"response" },"created":"2023-07-20T11:14:55.928Z"}
By setting the query parameter stream = True, you can receive the response as a stream of token. An example of the response can be seen below.
This endpoint allows a user to chat with more than one docuemt.
Query paramters
stream (boolean, optional): Flag for streaming. Default is false
model_name (string, optional) : The model the user chooses to use, model choices includes CLAUDE1, CLAUDE2, GPT3, GPT4, GPT4O_MINI. Default model is GPT4O_MINI
cite_source (boolean, optional) : Flag for cite_sources. Default if false
temperature (float, optional) : Flag for temperature. Default is 0.7
language (string, optional) : The language the user chooses to chat with, language choices include ENGLISH, ARABIC, CHINESE, JAPANESE, FRENCH , GERMAN, SPANISH, KOREAN, PORTUGESE. Default language is ENGLISH.
length (string, optional) : This option allows you to choose the desired length of the response. Choices includes LONG and SHORT. Default value is SHORT
Body
{"documents": ["3c06c3f8-be9f-4f43-ac00-b1a82fd25b30" ],"messages": [ {"sender":"user","message":"What is the document all about" } ]}
Response:
200 : Successful Response
question : A dict of information directed to the model
sender : The sender of the question,
message : The question asked
type : Has a value of "question"
answer : A dict of response information from the model
sender : The sender of the response
message : The exact answer a user requested
type : Has a value of "response"
{"question": {"sender":"user","message":"What is the document all about","type":"question" },"answer": {"sender":"bot","message":"The document simply describes the applications of motions","type":"response" },"created":"2024-08-23T11:01:46.204541"}
Examples
curl -X POST 'https://api.askyourpdf.com/v1/api/knowledge_base_chat?model_name=GPT3&stream=false&length=LONG&language=ARABIC&temperature=0.7' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"documents": [
"3c06c3f8-be9f-4f43-ac00-b1a82fd25b30"
],
"messages": [
{
"sender": "user",
"message": "What is the document all about"
}
]
}'
import requestsheaders ={'x-api-key':'YOUR_API_KEY'}payload ={"documents": ["3c06c3f8-be9f-4f43-ac00-b1a82fd25b30" ],"messages": [{"sender":"user",code"message":"What is the document all about"} ]}params ={"model_name":"GPT3","stream":False,"length":"LONG","language":"ARABIC","temperaature":0.7}response = requests.post('https://api.askyourpdf.com/v1/api/knowledge_base_chat', headers=headers, json=payload, params = params)if response.status_code ==200:print(response.json())else:print('Error:', response.status_code)
constaxios=require('axios');constheaders= {'x-api-key':'YOUR_API_KEY'};constpayload= {"documents": ["3c06c3f8-be9f-4f43-ac00-b1a82fd25b30" ],"messages": [ {"sender":"user","message":"What is the document all about" } ]};constparams= {"model_name":"GPT3","stream":false,"length":"LONG","language":"ARABIC","temperature":0.7};axios.post('https://api.askyourpdf.com/v1/api/knowledge_base_chat', payload, { headers: headers, params: params}).then(response => {console.log(response.data); }).catch(error => {console.error('Error:',error.response ?error.response.status :error.message); });
5. Documents Retrieval Endpoint
This endpoint allows users to retrieve a paginated list of their uploaded documents.
Query Parameters:
page (integer, optional): The page to return. Defaults to 1.
page_size (integer, optional): The number of documents to return per page. Defaults to 10.
Response:
200 Successful Response
total_pages (Integer): The total number of pages available for querying
documents (Array): A list of document details belonging to the user.
name
doc_id
summary
language
pages
shareable
date_time
{"total_pages":1,"documents": [ {"name":"Nature.pdf","doc_id":"6e60e87c-6154-4dff-8e62-ff10d8ed16dd","summary":"This is a document about nature","language":"en","pages":10,"shareable":true,"date_time":"2023-07-21T06:18:18.891Z" } ]}
Examples:
cURL
curl -X GET
-H 'x-api-key: YOUR_API_KEY'
'https://api.askyourpdf.com/v1/api/documents?page=1&page_size=10'
This endpoint allows users to retrieve a single document.
Path Parameters:
doc_id (string, required): The ID of the document for the conversation.
Response:
200 Successful Response
name
doc_id
summary
language
pages
shareable
date_time
{"name":"Nature.pdf","doc_id":"6e60e87c-6154-4dff-8e62-ff10d8ed16dd","summary":"This is a document about nature","language":"en","pages":10,"shareable":true,"date_time":"2023-07-21T06:18:18.891Z" }
Examples:
cURL
curl -X GET
-H 'x-api-key: YOUR_API_KEY'
'https://api.askyourpdf.com/v1/api/documents/{YOUR_DOC_ID}'
Knowledgebase endpoints are used when a user wants to chat or interact with multiple documents
8. Get Knowledge Bases
This endpoint enables an authenticated user to retrieve paginated knowledgebases
Returns:
PaginatedKnowledgeBase: The response containing the updated knowledge base.
Query parameters
page (integer, optional)
page_size (integer, optional)
order (string optional)
Response
200 Successful Response
total_pages (Integer): The total number of pages available for querying
knowledge_bases : An array of knowledges bases being queried
This endpoint enables a user converse with multiple documents by using a single knowledgebase id
Query parameters
stream (boolean, optional): Flag for streaming. Default is false
model_name (string, optional) : The model the user chooses to use, model choices includes CLAUDE1, CLAUDE2, GPT3, GPT4, GPT4O_MINI. Default model is GPT4O_MINI
cite_source (boolean, optional) : Flag for cite_sources. Default if false
temperature (float, optional) : Flag for temperature. Default is 0.7
language (string, optional) : The language the user chooses to chat with, language choices include ENGLISH, ARABIC, CHINESE, JAPANESE, FRENCH , GERMAN, SPANISH, KOREAN, PORTUGESE. Default language is ENGLISH.
length (string, optional) : This option allows you to choose the desired length of the response. Choices includes LONG and SHORT. Default value is SHORT
Request body:
messages: A list of dictionaries with key value of
sender (required): The sender of the chat message. The sender should be user
message (required): The chat message content.
The request body to ask a single question.
{"messages":[ {"sender":"user","message":"What does this document say?" } ]}
To ask a follow-up question and provide the model with context you can send your previous questions and responses in the following format.
[ { "sender":"user","message":"What does the document say?" }, {"sender":"bot","message":"The document consists of words in different languages expressing gratitude" }, {"sender":"user","message":"What is the word expressing gratitude in Spanish?" }]
Response
200 : Successful Response
{"question": {"sender":"user","message":"What is the document all about","type":"question" },"answer": {"sender":"bot","message":"The document simply describes the applications of motions","type":"response" },"created":"2024-08-23T11:01:46.204541"}
Args:
knowledge_base_id: The ID of the knowledge base to delete.
user: The user making the request.
Returns:
dict: The response containing a success message
DELETE/v1/api/knowledge/{knowledge_base_id}
Authorization
Path parameters
knowledge_base_id*Knowledge Base Id
Response
Successful Response
Body
any
Request
Response
Delete Document
Delete a document belonging to the authenticated user.
Args:
user: The user who is deleting the file.
doc_id: The document ID to delete.
Returns:
dict: A success message.
DELETE/v1/api/documents/{doc_id}
Authorization
Path parameters
doc_id*Doc Id
Response
Successful Response
Body
Response Delete Document V1 Api Documents Doc Id Delete
Request
Response
Upload Pdf
Upload a PDF file and save it to the database.
Args:
user: The user who is uploading the file.
file: The PDF file to upload.
Returns:
dict: The document ID of the uploaded file.
POST/v1/api/upload
Authorization
Body
file*File
Response
Successful Response
Body
docId*Docid
Request
Response
Search Knowledge Bases
Search knowledge bases
Args:
query: The search query
user: The user making the request.
Returns:
PaginatedKnowledgeBase: The response containing the updated knowledge base.
GET/v1/api/search/knowledge
Authorization
Query parameters
Response
Successful Response
Body
knowledge_base_id*Knowledge Base Id
name*Name
document_details*Document Details
date_timeDate Time
Request
Response
Download Pdf
Download a PDF file from a URL and save it to the database.
Args:
user: The user who is uploading the file.
url: The URL of the PDF file to download.
Returns:
dict: The document ID of the downloaded file.
GET/v1/api/download_pdf
Authorization
Query parameters
Response
Successful Response
Body
docId*Docid
Request
Response
Create Knowledge Base
Create a knowledge base from a list of document IDs.
Args:
knowledge_base: The knowledge base to create.
user: The user making the request.
Returns:
KnowledgeBaseResponse: The response containing the knowledge base ID.
POST/v1/api/knowledge
Authorization
Body
name*Name
document_ids*Document Ids
Response
Successful Response
Body
knowledge_base_id*Knowledge Base Id
Request
Response
Update Knowledge Base
Update a knowledge base from a list of document IDs.
Args:
knowledge_base_id: The ID of the knowledge base to update.
knowledge_base: The items to update in the knowledge base.
user: The user making the request.
Returns:
KnowledgeDetailedResponse: The response containing the updated knowledge base.
PUT/v1/api/knowledge/{knowledge_base_id}
Authorization
Path parameters
knowledge_base_id*Knowledge Base Id
Body
nameName
document_ids*Document Ids
Response
Successful Response
Body
knowledge_base_id*Knowledge Base Id
name*Name
document_details*Document Details
date_timeDate Time
Request
Response
Fetch Document
Fetch a user's documents using the doc_id.
Returns:
dict: A single document.
GET/v1/api/documents/{doc_id}
Authorization
Path parameters
doc_id*Doc Id
Response
Successful Response
Body
name*Name
doc_id*Doc Id
summarySummary
languageLanguage
pagesPages
shareableShareable
date_timeDate Time
Request
Response
Get Knowledge Base
Get knowledge base
Args:
knowledge_base_id: The ID of the knowledge base to retrieve.
user: The user making the request.
Returns:
KnowledgeDetailedResponse: The response containing the updated knowledge base.
GET/v1/api/knowledge/{knowledge_base_id}
Authorization
Path parameters
knowledge_base_id*Knowledge Base Id
Response
Successful Response
Body
knowledge_base_id*Knowledge Base Id
name*Name
document_details*Document Details
date_timeDate Time
Request
Response
Chat With Multiple Documents
Chat with multiple document.
Args:
knowledge_base: The knowledge base request payload containing the list of documents and messages.
model_name: The model name.
temperature: The model temperature max value is 1.5 and min value is 0.1.
stream: Whether to stream the response or not.
cite_source: Whether to cite the source or not.
language: The language to respond in.
length: The length of the response
user: The current user.
Returns:
ChatSerializer: The chat response.
POST/v1/api/knowledge_base_chat
Authorization
Query parameters
Body
documents*Documents
messages*Messages
Response
Successful Response
Body
question*ChatResponse
ChatResponse response schema.
answer*ChatResponse
ChatResponse response schema.
createdCreated
Request
Response
Chat With Multiple Documents
Chat with multiple document.
Args:
knowledge_base: The knowledge base request payload containing the list of documents and messages.
model_name: The model name.
temperature: The model temperature max value is 1.5 and min value is 0.1.
stream: Whether to stream the response or not.
cite_source: Whether to cite the source or not.
language: The language to respond in.
length: The length of the response
user: The current user.
Returns:
ChatSerializer: The chat response.
POST/v1/api/knowledge_base_chat
Authorization
Query parameters
Body
documents*Documents
messages*Messages
Response
Successful Response
Body
question*ChatResponse
ChatResponse response schema.
answer*ChatResponse
ChatResponse response schema.
createdCreated
Request
Response
Fetch Documents
Fetch all documents for the current user.
Returns:
dict: A list of documents.
GET/v1/api/documents
Authorization
Query parameters
Response
Successful Response
Body
total_pagesTotal Pages
documents*Documents
Request
Response
Chat With Doc Endpoint
Chat with a single document.
Args:
doc_id: The document id.
model_name: The model name.
messages: The list of messages.
cite_source: Whether to cite the source or not.
temperature: The model temperature max value is 1.5 and min value is 0.1.
language: The language to respond in.
length: The length of the response
stream: Whether to stream the response or not.
user: The current user.