NAV
shell

Introduction

Welcome to the API documentation for BrainyPDF, a powerful platform that allows users to ask questions based on their uploaded PDF documents.

With the BrainyPDF API, you can seamlessly integrate this functionality into your own applications, enabling users to leverage the AI-powered analysis of their PDFs and obtain accurate responses to their queries.

This documentation provides a comprehensive guide to the available API endpoints and their usage.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "Authorization: Bearer YOUR_API_KEY"

Make sure to replace YOUR_API_KEY with your API key.

BrainyPDF uses API keys to allow access to the API. You can register a new BrainyPDF API key at our Website.

BrainyPDF expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: 'Bearer YOUR_API_KEY'

Documents

Get All Documents

curl "https://app.brainypdf.com/api/v1/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "docs": [
    {
      "id": "6476188363958b5a5bcb8986",
      "name": "bitcoin.pdf",
      "size": "0.18 MB",
      "url": "https://app.brainypdf.com/uploads/document/2023/05/30/bitcoin.pdf",
      "pagesCount": 9,
      "createdAt": "2023-05-30T15:38:43.465Z"
    }
  ],
  "totalDocs": 1,
  "limit": 25,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

This endpoint retrieves all Documents in a paginated format.

HTTP Request

GET https://app.brainypdf.com/api/v1/documents

Query Parameters

Parameter Default Description
page 1 If specified. It will change the cursor of the pagination.

Get a Specific Document

curl "https://app.brainypdf.com/api/v1/documents/<ID>" \
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "document": {
    "id": "6476188363958b5a5bcb8986",
    "name": "bitcoin.pdf",
    "size": "0.18 MB",
    "url": "https://app.brainypdf.com/uploads/document/2023/05/30/bitcoin.pdf",
    "pagesCount": 9,
    "createdAt": "2023-05-30T15:38:43.465Z"
  }
}

This endpoint retrieves a specific Document.

HTTP Request

GET https://app.brainypdf.com/api/v1/documents/<ID>

URL Parameters

Parameter Description
ID The ID of the Document to retrieve

Uplaod Documents

curl " https://app.brainypdf.com/api/v1/documents/upload" \
  -X POST 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -F "documents=@/path/to/your/pdf_file.pdf"

The above command returns JSON structured like this:

{
  "documents": [
    {
      "id": "6476233921bd9e74f81b506c",
      "name": "bitcoin.pdf",
      "size": "0.18 MB",
      "url": "https://app.brainypdf.com/uploads/document/2023/05/30/1685463865451-bitcoin.pdf",
      "pagesCount": 9,
      "createdAt": "2023-05-30T16:24:25.503Z"
    }
  ]
}

This endpoint uploads up to 5 documents at the same time.

HTTP Request

POST https://app.brainypdf.com/api/v1/documents/upload

Body Parameters

Parameter Default Required Description
documents - Yes The PDF files to be uploaded. This should be specified as a form-data field.

Edit Document

curl "https://app.brainypdf.com/api/v1/documents/<ID>" \
  -X PUT \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Edited Bitcoin"
  }'

The above command returns JSON structured like this:

{
  "document": {
    "id": "6476233921bd9e74f81b506c",
    "name": "Edited Bitcoin",
    "size": "0.18 MB",
    "url": "https://app.brainypdf.com/uploads/document/2023/05/30/1685463865451-bitcoin.pdf",
    "pagesCount": 9,
    "createdAt": "2023-05-30T16:24:25.503Z"
  }
}

This endpoint edits a specefic Document.

HTTP Request

PUT https://app.brainypdf.com/api/v1/documents/<ID>

Body Parameters

Parameter Type Default Required Description
name string - Yes The new name of the document.

Ask Question from Document(s)

curl "https://app.brainypdf.com/api/v1/documents/ask" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How does bitcoin work?",
    "lang": "en",
    "documentsIds": [YOUR_DOCUMENT_ID, YOUR_DOCUMENT_ID],
  }'

The above command returns streamed text like this:

Bitcoin works as a purely peer-to-peer electronic cash 
system that allows online payments to be sent directly 
from one party to another without going through a 
financial institution. Digital signatures provide part 
of the solution, but the main benefits are lost if a trusted 
third party is still required to prevent double-spending.
To solve this, Bitcoin proposes a solution to the double-spending 
problem using a peer-to-peer network that timestamps transactions 
by hashing them into an ongoing chain of hash-based proof-of-work, 
forming a record that cannot be changed without redoing the proof-of-work. 
The longest chain not only serves as proof of the sequence of 
events witnessed but proof that it came from the largest pool of CPU power. 
As long as a majority of CPU power is controlled by nodes that 
are not cooperating to attack the network, they'll generate the 
longest chain and outpace attackers. The network itself requires
minimal structure, and nodes can leave and rejoin the network at will, 
accepting the longest proof-of-work chain as proof of what 
happened while they were gone.{"success":true, "sourceDocuments":[]}

The "Ask Question" route allows you to submit a question based on the uploaded documents and retrieve a response using the BrainyPDF API. By making a POST request to this endpoint, you can provide the question, language, documents ID, and chat history (if applicable) in the request payload. The AI-powered analysis will process your question and provide a relevant response based on the content of the specified document.

HTTP Request

POST https://app.brainypdf.com/api/v1/documents/ask

Body Parameters

Parameter Type Default Required Description
question String - Yes The question to ask based on the uploaded document(s).
lang String - No The language of the response (e.g., "en", "fr", "ar").
returnSourceDocuments Boolean - Yes Should return the source documents or not.
documentsIds Array - Yes An array of document IDs to consider for analysis.
chatHistory Array - No An optional array of chat history for context with maximum 6 strings each maximum 2000 characters.

Prompt Message

curl "https://app.brainypdf.com/api/v1/documents/prompt-message" \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Give me four questions about the Bitcoin.",
    "lang": "en",
    "documentsIds": [YOUR_DOCUMENT_ID],
  }'

The above command returns streamed text like this:

1. What is bitcoin and how does it work?
2. What is the problem with double-spending in electronic coins and how does bitcoin propose to solve it?
3. How does the bitcoin network ensure the validity of transactions and prevent attacks?
4. How does the bitcoin system handle the issue of reclaiming disk space and saving storage?{"success":true}

The "Ask Question" route allows you to submit a question based on the uploaded documents and retrieve a response using the BrainyPDF API. By making a POST request to this endpoint, you can provide the question, language, documents ID, and chat history (if applicable) in the request payload. The AI-powered analysis will process your question and provide a relevant response based on the content of the specified document.

HTTP Request

POST https://app.brainypdf.com/api/v1/documents/ask

Body Parameters

Parameter Type Default Required Description
prompt String - Yes The question to ask based on the uploaded document(s).
lang String - No The language of the response (e.g., "en", "fr", "ar").
documentsIds Array - Yes An array of document IDs to consider for analysis.

Delete a Specific Document

curl "https://app.brainypdf.com/api/v1/documents/2" \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

The above command returns JSON structured like this:

{
  "document": { 
    "id": "6476188363958b5a5bcb8986" 
  }
}

This endpoint deletes a specific Document.

HTTP Request

DELETE https://app.brainypdf.com/api/v1/documents/<ID>

URL Parameters

Parameter Description
ID The ID of the Document to delete

Errors

The Kittn API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
shell