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
Download Pdf
get
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.
Authorizations
X-API-KeystringRequired
Query parameters
urlstringRequired
Responses
201
Successful Response
application/json
422
Validation Error
application/json
get
/v1/api/download_pdf
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.
Examples:
2. Adding Document via File Upload.
Upload Pdf
post
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.
Authorizations
X-API-KeystringRequired
Body
filestring · binaryRequired
Responses
201
Successful Response
application/json
422
Validation Error
application/json
post
/v1/api/upload
Request body:
The request body should be sent as a form of data with the name file (see example).
file (required): The raw bytes of the file to be uploaded.
Response:
201 Successful Response
doc_id (string): The document ID of the uploaded document.
Examples:
3. Chat Endpoint
Endpoint for initiating a chat with a document. This endpoint requires API Key Header authentication.
Chat With Doc Endpoint
post
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. agent_mode: Whether to use agent mode or not. user: The current user.
Returns: ChatSerializer: The chat response.
Authorizations
X-API-KeystringRequired
Path parameters
doc_idstringRequired
Query parameters
model_nameall ofOptionalDefault: GPT5_2
undefined · enumOptional
An enumeration.
Possible values:
streambooleanOptionalDefault: false
cite_sourcebooleanOptionalDefault: false
temperaturenumberOptionalDefault: 0.7
languageall ofOptionalDefault: DEFAULT
undefined · enumOptional
An enumeration.
Possible values:
lengthall ofOptionalDefault: LONG
undefined · enumOptional
An enumeration.
Possible values:
agent_modebooleanOptionalDefault: true
Bodyobject · ChatRequest[]
ChatRequest response schema.
senderstringRequired
messagestringRequired
Responses
200
Successful Response
application/json
422
Validation Error
application/json
post
/v1/chat/{doc_id}
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 GPT5_2, GPT5, GPT5_MINI, GPT5_NANO, GEMINI_FLASH, CLAUDE1, CLAUDE2, GPT4, GPT5, GEMINI_PRO, GPT4O_MINI. Default model is GPT5_2
agent_mode (boolean, optional) : Enabled by default. This flag determines whether the system uses our agent to answer your question. When set to True, responses may take slightly longer but are generally more accurate and higher quality than those generated in normal mode.
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 or (systemIf you want to specify a custom system prompt)
message (required): The chat message content.
The request body to ask a single question.
To ask a follow-up question and provide the model with context you can send your previous questions and responses in the following format.
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.
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.
Example when stream = False:
Example when stream = True:
4. Chat with multiple documents
This endpoint allows a user to chat with more than one document.
Deprecated
Chat With Multiple Documents
post
[DEPRECATED] Chat with multiple documents using knowledgebase Id. Please use /api/knowledge/{knowledge_base_id}/chat instead.
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 agent_mode: Whether to use agent mode or not. user: The current user.
Returns: ChatSerializer: The chat response.
Authorizations
X-API-KeystringRequired
Query parameters
model_nameall ofOptionalDefault: GPT5_MINI
undefined · enumOptional
An enumeration.
Possible values:
streambooleanOptionalDefault: false
cite_sourcebooleanOptionalDefault: false
temperaturenumberOptionalDefault: 0.7
languageall ofOptionalDefault: DEFAULT
undefined · enumOptional
An enumeration.
Possible values:
lengthall ofOptionalDefault: LONG
undefined · enumOptional
An enumeration.
Possible values:
agent_modebooleanOptionalDefault: true
Body
KnowledgeChatRequest response schema.
documentsstring[]Required
Responses
200
Successful Response
application/json
422
Validation Error
application/json
post
/v1/api/knowledge_base_chat
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 GPT5_2, GPT5, GPT5_MINI, GPT5_NANO, GEMINI_FLASH, CLAUDE1, CLAUDE2, GPT4, GPT5, GEMINI_PRO, GPT4O_MINI. Default model is GPT5_2
agent_mode (boolean, optional) : Enabled by default. This flag determines whether the system uses our agent to answer your question. When set to True, responses may take slightly longer but are generally more accurate and higher quality than those generated in normal mode.
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
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"
Examples
5. Documents Retrieval Endpoint
This endpoint allows users to retrieve a paginated list of their uploaded documents.
doc_id (string, required): The ID of the document to be deleted.
Response:
200 Successful Response
Examples:
KnowledgeBase Endpoints
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
422 : Validation Error
Examples
9. Create Knowledge Base
This endpoint enables a user to create a knowlege base from the list of document IDs
Create Knowledge Base
post
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.
Authorizations
X-API-KeystringRequired
Body
namestringRequired
document_idsstring[]Required
Responses
201
Successful Response
application/json
422
Validation Error
application/json
post
/v1/api/knowledge
Body
name * (string, required) : The name of the knowledgebase
document_ids * (array, required) : The documents Ids to be included in the knowledgebase
Authorization
API Key
Response
201 : Successful Response
KnowlegeBaseResponse : A dictionary of knowledge_base_id created
This endpoint enables a user converse with multiple documents by using a single knowledgebase id
Chat With Knowledgebase
post
Chat with multiple documents using knowledgebase Id.
Args: knowledge_base_chat_request : The knowledge base chat request payload containing the messages. knowledge_base_id: The knowledge id is id of the knowledgebase documents you want to chat with. 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 agent_mode: Whether to use agent mode or not. user: The current user.
Returns: ChatSerializer: The chat response.
Authorizations
X-API-KeystringRequired
Path parameters
knowledge_base_idstringRequired
Query parameters
model_nameall ofOptionalDefault: GPT5_2
undefined · enumOptional
An enumeration.
Possible values:
streambooleanOptionalDefault: false
temperaturenumberOptionalDefault: 0.7
languageall ofOptionalDefault: DEFAULT
undefined · enumOptional
An enumeration.
Possible values:
lengthall ofOptionalDefault: LONG
undefined · enumOptional
An enumeration.
Possible values:
cite_sourcebooleanOptionalDefault: false
agent_modebooleanOptionalDefault: true
Body
KnowledgeBaseIDChatRequest response schema.
Responses
200
Successful Response
application/json
422
Validation Error
application/json
post
/v1/api/knowledge/{knowledge_base_id}/chat
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 GPT4O_MINI, GEMINI_FLASH, CLAUDE1, CLAUDE2, GPT4, GPT5_NANO, GPT5, GEMINI_PRO. 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 should be user or (systemIf you want to specify a custom system prompt)
message (required): The chat message content.
The request body to ask a single question.
To ask a follow-up question and provide the model with context you can send your previous questions and responses in the following format.
Response
200 : Successful Response
422 : Validation Error
10. Get KnowledgeBase
This endpoint enables a user to retrieve a single knowledge base
Get Knowledge Base
get
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.
Authorizations
X-API-KeystringRequired
Path parameters
knowledge_base_idstringRequired
Responses
200
Successful Response
application/json
422
Validation Error
application/json
get
/v1/api/knowledge/{knowledge_base_id}
Path parameter
knowledge_base_id * (string, required)
Authorization
API Key
Response
200 : Succesful Response
422 : Validator Error
Examples
curl -X GET 'https://api.askyourpdf.com/v1/api/knowledge/YOUR_KNOWLEDGE_BASE_ID'
-H 'x-api-key: YOUR_API_KEY'
11. Update Knowledge Base
This endpoint enables a user to update a knowledge base
Update Knowledge Base
put
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.
Authorizations
X-API-KeystringRequired
Path parameters
knowledge_base_idstringRequired
Body
namestringOptional
document_idsstring[]Required
Responses
200
Successful Response
application/json
422
Validation Error
application/json
put
/v1/api/knowledge/{knowledge_base_id}
Path parameter
knowledge_base_id* (string, required)
Body
name (string) : A new name for your knowledge base
document_ids: (string) An array of documents IDs you wish to update your knowledgebase with
Authorization
API Key
Response
200 : Successful Response
422 : Validator Error
Examples
12. Delete Knowledge Base
This endpoint enables a user to delete a knowledge base
Delete Knowledge Base
delete
Delete knowledge base
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
Authorizations
X-API-KeystringRequired
Path parameters
knowledge_base_idstringRequired
Responses
200
Successful Response
application/json
Responseany
422
Validation Error
application/json
delete
/v1/api/knowledge/{knowledge_base_id}
No content
Args:
knowledge_base_id: The ID of the knowledge base to delete
Returns: dict: The response containing a success message
// Example of a request asking a question along with a system prompt
[
{
"sender": "system",
"message": "Reply to my question in json format"
},
{
"sender": "user",
"message": "What does this document say?"
}
]
// Example of a request asking a question without a system prompt
[
{
"sender": "user",
"message": "What does this document say?"
}
]
[
{
"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?"
}
]
{
"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"
}
Chunk: This
Chunk: document
Chunk: talks
Chunk: about
Chunk: AI
cURL
curl -X POST
-H 'Content-Type: application/json'
-H 'x-api-key: YOUR_API_KEY'
-d '[{"sender": "User","message": "What does this document say?"}]'
https://api.askyourpdf.com/v1/chat/{YOUR_DOC_ID}
Python
import requests
import json
headers = {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
}
data = [
{
"sender": "User",
"message": "What does this document say?"
}
]
response = requests.post('https://api.askyourpdf.com/v1/chat/{YOUR_DOC_ID}',
headers=headers, data=json.dumps(data))
if response.status_code == 200:
print(response.json())
else:
print('Error:', response.status_code)
{
"documents": [
"3c06c3f8-be9f-4f43-ac00-b1a82fd25b30"
],
"messages": [
// Optional system prompt that can be sent (can be used to specify custom prompts)
{
"sender": "system",
"message": "Reply to my question in two sentences"
},
// Compulsory user message that must be sent in the request
{
"sender": "user",
"message": "What are the documents all about?"
}
]
}
{
"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"
}
curl -X POST 'https://api.askyourpdf.com/v1/api/knowledge_base_chat?model_name=GPT4O_MINI&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"
}
]
}'
{
"messages":[
// Optional system prompt that can be sent (can be used to specify custom prompts)
{
"sender": "system",
"message": "Reply to my question in five sentences"
},
// Compulsor user message that must be sent in the request
{
"sender": "user",
"message": "What do the documents in the knowledgebase talk about?"
}
]
}
[
{
"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?"
}
]
{
"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"
}