Humata API

The Humata API is the programmatic entry-point for your Humata documents, conversations, and answers.

Setup

Here are the 3-steps to use the Humata API after you sign up:

1. Create a Humata API Key on the Developer Settings Page (Admin only)

2. Copy your Document IDs from the Humata Dashboard

1. Make API Requests

Endpoints

Import Document

Humata allows you to import new documents via the API. By passing a publicly available URL (or signed URL) to this endpoint, the document will be downloaded and processed on the Humata server.

Import URL

Imports a PDF from a given URL into the specified folder.

POSThttps://app.humata.ai/api/v2/import-url

Authorization

ApiKeyAuth

Body

application/json

url*string (uri)

The URL of the PDF to import.

folder_id*string (uuid)

The UUID of the folder to import the PDF into.

Response

200401429

Successfully imported the PDF.

Body

application/json

idstring (uuid)

The unique identifier of the imported document.

Request

JavaScriptCurlPython

const response = await fetch('https://app.humata.ai/api/v2/import-url', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "url": "https://pdfobject.com/pdf/sample.pdf",
      "folder_id": "e507832b-bdef-4baf-8423-822c1cb68e35"
    }),
});
const data = await response.json();

Response

200401429

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

GET Pdf

Fetch the information of an already created PDF. Typically this is useful to poll until pdf.read_status == 'SUCCESS' (and not pdf.read_status == 'FAILED') before asking questions against the PDF.

Get PDF

Retrieve details of a PDF by its ID.

GEThttps://app.humata.ai/api/v1/pdf/{pdf-id}

Authorization

ApiKeyAuth

Path parameters

pdf-id*string (uuid)

The unique identifier of the PDF.

Response

200401404

Details of the PDF.

Body

application/json

idstring

Example: "9294544b-2b6a-4c93-976c-d1910b8c1423"

namestring

Example: "example.pdf"

organization_idstring

Example: "fcf6c954-ba68-4e39-a7b5-960dc8274ec0"

created_atstring (date-time)

Example: "2024-12-05T20:18:53.289618+00:00"

updated_atstring (date-time)

Example: "2024-12-05T20:18:55.584786+00:00"

number_of_pagesnullable integer

folder_idstring

Example: "6c702c82-bb8a-4274-8cb6-074e0bf78084"

read_statusstring

Example: "SUCCESS"

created_bystring

Example: "07f5bfc7-72c9-40b7-8151-dcfc2f9613dc"

from_urlnullable string

file_typestring

Example: "PDF"

Request

JavaScriptCurlPython

const response = await fetch('https://app.humata.ai/api/v1/pdf/{pdf-id}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200401404

{
  "id": "9294544b-2b6a-4c93-976c-d1910b8c1423",
  "name": "example.pdf",
  "organization_id": "fcf6c954-ba68-4e39-a7b5-960dc8274ec0",
  "created_at": "2024-12-05T20:18:53.289618+00:00",
  "updated_at": "2024-12-05T20:18:55.584786+00:00",
  "number_of_pages": 0,
  "folder_id": "6c702c82-bb8a-4274-8cb6-074e0bf78084",
  "read_status": "SUCCESS",
  "created_by": "07f5bfc7-72c9-40b7-8151-dcfc2f9613dc",
  "from_url": "text",
  "file_type": "PDF"
}

Conversations

Create a conversation with a set of documents. A conversation must be created before asking questions to documents.

Create Conversation

Creates a new conversation based on the document IDs.

POSThttps://app.humata.ai/api/v1/conversations

Authorization

ApiKeyAuth

Body

application/json

documentIds*array of string (uuid)

Response

200401429

Successfully created a new conversation.

Body

application/json

idstring (uuid)

The unique identifier of the created conversation.

Request

JavaScriptCurlPython

const response = await fetch('https://app.humata.ai/api/v1/conversations', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "documentIds": [
        "63ea1432-d6aa-49d4-81ef-07cb1692f2ee",
        "cbec39d9-1e01-409c-9fc2-f19f5d01005c"
      ]
    }),
});
const data = await response.json();

Response

200401429

{
  "id": "123e4567-e89b-12d3-a456-426614174000"
}

Ask

Humata allows you to chat with your document via the Ask endpoint. Create a conversation and then ask your documents

Ask in a Conversation

Ask a question in a conversation. Response is streamed via server-sent events.

POSThttps://app.humata.ai/api/v1/ask

Authorization

ApiKeyAuth

Body

application/json

conversationId*string (uuid)

model*enum

gpt-4-turbo-preview

question*string

selectedAnswerApproachenum

GroundedBalancedCreative

Response

200401429

Successfully answered the question.

Body

text/event-stream

string

Request

JavaScriptCurlPython

const response = await fetch('https://app.humata.ai/api/v1/ask', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "conversationId": "7290fd6b-fe15-4fd3-865e-8010bd8e8a38",
      "model": "gpt-4-turbo-preview",
      "question": "Who is George Washington?"
    }),
});
const data = await response.json();

Response

200401429

text

Server-Sent Events

The Ask Endpoint returns a stream of server-sent events. Here is a full example of response to the question "Who is George Washington?":

data: { 'content': 'George Washington was ' }
data: { 'content': 'the first ' }
data: { 'content': 'president of the United States[3].' }
data: { 'content': '\n\nReferences - [3]: Page 10 of History of the United States.pdf' }

References

Each answer from Humata will provide references to the parts of the document that our AI used to answer the question. The format of references is subject to change.

Download Data

Humata allows you to download your data via the Download Data endpoint. Simply initiate a request and retrieve your data effortlessly.

Download insights data

GEThttps://app.humata.ai/api/v1/insights/download

Authorization

ApiKeyAuth

Response

200401

File download successful

Body

application/json

successboolean

Example: true

filestring

URL to download the file

Request

JavaScriptCurlPython

const response = await fetch('https://app.humata.ai/api/v1/insights/download', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "success": true,
  "file": "text"
}

FAQ

What is the API rate limit?

By default the API rate limit is 120 requests / minute. This rate limit can be increased by request. Please reach out to [e-mail] to get this limit raised.