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

post

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

Authorizations

Body

urlstring · uriRequired

The URL of the PDF to import.

folder_idstring · uuidRequired

The UUID of the folder to import the PDF into.

Responses

200

Successfully imported the PDF.

application/json

401

Unauthorized access, invalid API key.

application/json

429

Rate limit exceeded.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/import-url HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 97

{
  "url": "https://pdfobject.com/pdf/sample.pdf",
  "folder_id": "e507832b-bdef-4baf-8423-822c1cb68e35"
}

{
  "id": "a8283bc7-02ee-471b-8590-5ef5401afa40"
}

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

get

Retrieve details of a PDF by its ID.

Authorizations

Path parameters

pdf-idstring · uuidRequired

The unique identifier of the PDF.

Responses

200

Details of the PDF.

application/json

401

Unauthorized access, invalid API key.

application/json

404

PDF not found.

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/pdf/{pdf-id} HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Accept: */*

{
  "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": 1,
  "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

post

Creates a new conversation based on the document IDs.

Authorizations

Body

documentIdsstring · uuid[]Required

Responses

200

Successfully created a new conversation.

application/json

401

Unauthorized access, invalid API key.

application/json

429

Rate limit exceeded.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/conversations HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 95

{
  "documentIds": [
    "63ea1432-d6aa-49d4-81ef-07cb1692f2ee",
    "cbec39d9-1e01-409c-9fc2-f19f5d01005c"
  ]
}

{
  "id": "e6d13306-c93d-466e-b239-59ca09058ce9"
}

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

post

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

Authorizations

Body

conversationIdstring · uuidRequired

modelstring · enumRequiredPossible values:

questionstringRequired

selectedAnswerApproachstring · enumOptionalPossible values:

Responses

200

Successfully answered the question.

text/event-stream

Responsestring

401

Unauthorized access, invalid API key.

application/json

429

Rate limit exceeded.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/ask HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 126

{
  "conversationId": "7290fd6b-fe15-4fd3-865e-8010bd8e8a38",
  "model": "gpt-4-turbo-preview",
  "question": "Who is George Washington?"
}

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

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

get

Authorizations

Responses

200

File download successful

application/json

401

Unauthorized, API key is missing or invalid

get

HTTPcURLJavaScriptPython

GET /api/v1/insights/download HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Accept: */*

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

Users

Humata provides a straightforward API solution for organizations to handle user sign-up and login processes.

Create a new user.

post

This endpoint allows organization admins to create new user accounts.

Authorizations

Body

first_namestringRequiredExample: John

last_namestringRequiredExample: Doe

emailstringRequiredExample: [e-mail]

passwordstringRequiredExample: password

bypass_email_verificationbooleanOptionalExample: true

Responses

201

User created successfully.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/users HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "[e-mail]",
  "password": "password",
  "bypass_email_verification": true
}

201

User created successfully.

{
  "id": "9294544b-2b6a-4c93-976c-d1910b8c1423",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[e-mail]"
}

Generate an OTP Token for a User

post

This endpoint allows organization admins to generate a One-Time Password (OTP) token for their users.

Authorizations

Body

emailstringRequiredExample: [e-mail]

providerstringOptionalExample: email

Responses

200

Token generated successfully.

application/json

post

HTTPcURLJavaScriptPython

POST /api/v1/users/token HTTP/1.1
Host: app.humata.ai
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 43

{
  "email": "[e-mail]",
  "provider": "email"
}

200

Token generated successfully.

{
  "token": "fjlgkspwzytqxnh...."
}

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.