AskYourPDF API Documentation
Introducing the AskYourPDF API
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 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.
Successful Response
Validation Error
GET /v1/api/download_pdf?url=text HTTP/1.1
Host:
X-API-Key: YOUR_API_KEY
Accept: */*
{
"docId": "text"
}
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 Responsedoc_id
(string
): The document ID of the uploaded document.
{ "doc_id": "6e60e87c-6154-4dff-8e62-ff10d8ed16dd" }
Examples:
curl -X GET
'https://api.askyourpdf.com/v1/api/download_pdf?url=https://www.example.com/document.pdf'
-H 'x-api-key: YOUR_API_KEY'
import requests
headers = {
'x-api-key': 'YOUR_API_KEY'
}
response = requests.get('https://api.askyourpdf.com/v1/api/download_pdf',
headers=headers,
params={'url': 'https://www.example.com/document.pdf'})
if response.status_code == 201:
print(response.json())
else:
print('Error:', response.status_code)
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
axios.get('https://api.askyourpdf.com/v1/api/download_pdf', {
headers: headers,
params: {
url: 'https://www.example.com/document.pdf'
}
})
.then((response) => {
if (response.status === 201) {
console.log(response.data);
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
2. Adding Document via File 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 Responsedoc_id
(string
): The document ID of the uploaded document.
{ "doc_id": "6e60e87c-6154-4dff-8e62-ff10d8ed16dd" }
Examples:
curl -X POST
-H 'x-api-key: YOUR_API_KEY'
-F "file=@/path/to/yourfile.pdf" https://api.askyourpdf.com/v1/api/upload
import requests
headers = {
'x-api-key': 'YOUR_API_KEY'
}
file_data = open('/path/to/yourfile.pdf', 'rb')
response = requests.post('https://api.askyourpdf.com/v1/api/upload', headers=headers,
files={'file': file_data})
if response.status_code == 201:
print(response.json())
else:
print('Error:', response.status_code)
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
let form = new FormData();
form.append('file', fs.createReadStream('/path/to/yourfile.pdf'));
axios.post('https://api.askyourpdf.com/v1/api/upload', form, {
headers: {
...headers,
...form.getHeaders()
}
})
.then((response) => {
if (response.status === 201) {
console.log(response.data);
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
3. Chat Endpoint
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 isfalse
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
temeperature (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 beUser
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 Responsequestion
: 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.
Chunk: This
Chunk: document
Chunk: talks
Chunk: about
Chunk: AI
Example when stream = False:
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}
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)
const axios = require('axios');
const headers = {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
};
const data = [
{
"sender": "User",
"message": "What does this document say?"
}
];
axios.post('https://api.askyourpdf.com/v1/chat/{YOUR_DOC_ID}', data, {headers: headers})
.then((response) => {
if (response.status === 200) {
console.log(response.data);
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
Example when stream = True:
import requests
import json
headers = {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
}
data = [
{
"sender": "User",
"message": "What does this document say?"
}
]
try:
response = requests.post(
'https://api.askyourpdf.com/v1/chat/YOUR_DOC_ID?stream=True',
headers=headers, data=json.dumps(data))
response.raise_for_status()
for chunk in response.iter_content(chunk_size=24):
chunk_str = chunk.decode('utf-8')
print("Chunk:", chunk_str)
except requests.exceptions.RequestException as error:
print("Error:", error)
const fetch = require('node-fetch');
const Readable = require('stream').Readable;
const headers = {
'Content-Type': 'application/json',
'x-api-key': 'YOUR_API_KEY'
}
const data = [
{
"sender": "User",
"message": "What does this document say?"
}
]
fetch('https://api.askyourpdf.com/v1/chat/YOUR_DOC_ID?stream=True', {
method: 'POST',
headers: headers,
body: JSON.stringify(data)
})
.then(response => {
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return response.body;
})
.then(stream => {
const reader = Readable.from(stream);
reader.on('data', chunk => {
console.log("Chunk:", chunk.toString('utf-8'));
});
})
.catch(error => {
console.log("Error:", error);
});
4. Chat with multiple documents
This endpoint allows a user to chat with more than one docuemt.
POST /v1/api/knowledge_base_chat
Query paramters
stream
(boolean
, optional): Flag for streaming. Default isfalse
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 requests
headers = {
'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)
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
const payload = {
"documents": [
"3c06c3f8-be9f-4f43-ac00-b1a82fd25b30"
],
"messages": [
{
"sender": "user",
"message": "What is the document all about"
}
]
};
const params = {
"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 to1
.page_size (integer, optional): The number of documents to return per page. Defaults to 10.
Response:
200
Successful Responsetotal_pages
(Integer): The total number of pages available for queryingdocuments
(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 -X GET
-H 'x-api-key: YOUR_API_KEY'
'https://api.askyourpdf.com/v1/api/documents?page=1&page_size=10'
import requests
headers = {
'x-api-key': 'YOUR_API_KEY'
}
params = {
'page': 1,
'page_size': 10
}
response = requests.get('https://api.askyourpdf.com/v1/api/documents',
headers=headers, params=params)
if response.status_code == 200:
print(response.json())
else:
print('Error:', response.status_code)
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
const params = {
'page': 1,
'page_size': 10
};
axios.get('https://api.askyourpdf.com/v1/api/documents',
{headers: headers, params: params})
.then((response) => {
if (response.status === 200) {
console.log(response.data);
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
6. Single Document Retrieval Endpoint
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 Responsename
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 -X GET
-H 'x-api-key: YOUR_API_KEY'
'https://api.askyourpdf.com/v1/api/documents/{YOUR_DOC_ID}'
import requests
headers = {
'x-api-key': 'YOUR_API_KEY'
}
response = requests.get('https://api.askyourpdf.com/v1/api/documents/{YOUR_DOC_ID}',
headers=headers)
if response.status_code == 200:
print(response.json())
else:
print('Error:', response.status_code)
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
axios.get('https://api.askyourpdf.com/v1/api/documents/{YOUR_DOC_ID}',
{headers: headers})
.then((response) => {
if (response.status === 200) {
console.log(response.data);
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
7. Delete Document Endpoint
Allows users to delete a single document
Path Parameters:
doc_id
(string
, required): The ID of the document to be deleted.
Response:
200
Successful Response
{"message": "Document deleted successfully"}
Examples:
curl -X DELETE
-H 'x-api-key: YOUR_API_KEY'
'https://api.askyourpdf.com/v1/api/documents/DOC_ID'
import requests
headers = {
'x-api-key': 'YOUR_API_KEY'
}
response = requests.delete('https://api.askyourpdf.com/v1/api/documents/DOC_ID', headers=headers)
if response.status_code == 200:
print('Document deleted successfully')
else:
print('Error:', response.status_code)
const axios = require('axios');
const headers = {
'x-api-key': 'YOUR_API_KEY'
};
axios.delete('https://api.askyourpdf.com/v1/api/documents/DOC_ID', {headers: headers})
.then((response) => {
if (response.status === 200) {
console.log('Document deleted successfully');
} else {
console.log('Error:', response.status);
}
})
.catch((error) => {
console.error(error);
});
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.
GET /api/knowledge
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
{
"total_pages": 0,
"knowledge_bases": [
{
"knowledge_base_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c",
"name": "Johns knowledgebase",
"document_details": [
{
"doc_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c",
"name": "new_docs.pdf"
}
],
"date_time": "2024-08-21T12:38:07.085Z"
}
]
}
422 : Validation Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Examples
curl -H "x-api-key: YOUR_API_KEY"
-X GET "https://api.askyourpdf.com/v1/api/knowledge"
9. Create Knowledge Base
This endpoint enables a user to create a knowlege base from the list of document IDs
Returns: KnowledgeBaseResponse: The response containing the knowledge base ID.
Body
name * (string, required) : The name of the knowledgebase
document_ids * (array, required) : The documents Ids to be included in the knowledgebase
{
"name": "Johns knowledgebase",
"document_ids": [
"b2cb7d2c-5922-4dad-94b5-65b657e02a9c"
]
}
POST /api/knowledge
Response
201 : Successful Response
KnowlegeBaseResponse : A dictionary of knowledge_base_id created
{
"knowledge_base_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c"
}
422: Validation Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Examples
curl -X POST 'https://api.askyourpdf.com/v1/api/knowledge' -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' -d '{ "name": "string", "document_ids": [ "string" ] }'
10. Get KnowledgeBase
This endpoint enables a user to retrieve a single knowledge base
Args: knowledge_base_id: The ID of the knowledge base to retrieve
Returns: KnowledgeDetailedResponse: The response containing the updated knowledge base.
Path parameter
knowledge_base_id * (string, required)
GET /api/knowledge/{knowledge_base_id}
Response
200 : Succesful Response
{
"knowledge_base_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c",
"name": "askyourpdf",
"document_details": [
{
"doc_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c",
"name": "docs_name.pdf"
}
],
"date_time": "2024-08-22T15:41:56.723Z"
}
422 : Validator Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
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
Args: knowledge_base_id: The ID of the knowledge base to update.
Returns: KnowledgeDetailedResponse: The response containing the updated knowledge base.
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
{
"name": "new knowledgbebase name",
"document_ids": [
"b2cb7d2c-5922-4dad-94b5-65b657e02a9c"
]
}
PUT /api/knowledge/{knowledge_base_id}
Response
200 : Successful Response
{
"knowledge_base_id": "d2cb3e2c-5922-4dad-94b5-65b657e12a9c",
"name": "KB1",
"document_details": [
{
"doc_id": "b2cb7d2c-5922-4dad-94b5-65b657e02a9c",
"name": "wolf_of_wallstreet.pdf"
}
],
"date_time": "2024-08-22T17:50:12.964Z"
}
422 : Validator Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Examples
curl -X PUT 'https://api.askyourpdf.com/v1/api/knowledge/YOUR_KNOWLEDGE_BASE_ID' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"name": "string",
"document_ids": [
"string"
]
}'
12. Delete Knowledge Base
This endpoint enables a user to delete a knowledge base
Args: knowledge_base_id: The ID of the knowledge base to delete
Returns: dict: The response containing a success message
Path parameter
knowledge_base_id* (string, required)
DELETE /api/knowledge/{knowledge_base_id}
Response
200 : Successful Response
{"message": "Knowledge base deleted successfully"}
Examples
curl -X DELETE 'https://api.askyourpdf.com/v1/api/knowledge/YOUR_KNOWLEDGE_BASE_ID' -H 'x-api-key: YOUR_API_KEY'
13. Search Knowledge Base
This endpoint retrieves a list of knowledgebases based on a user's query
Args: query: The search query is used to filter knowledgebases by name
Returns: KnowledgeBase: A list of knowledges matching the query
Query parameter
query* (string, required)
GET /api/search/knowledge
Response
200 : Successful Response
[
{
"knowledge_base_id": "string",
"name": "string",
"document_details": [
{
"doc_id": "string",
"name": "string"
}
],
"date_time": "2024-08-22T19:27:28.485Z"
}
]
422 : Validator Error
{
"detail": [
{
"loc": [
"string",
0
],
"msg": "string",
"type": "string"
}
]
}
Examples
curl -X GET 'https://api.askyourpdf.com/v1/api/search/knowledge?query=YOUR_QUERY' -H 'x-api-key: YOUR_API_KEY'
Last updated