ParseHub API Documentation

Welcome to the ParseHub.dev API documentation. This comprehensive guide covers everything you need to know to integrate our document and data processing API into your application.

Getting Started

ParseHub provides a powerful REST API for document and CSV processing. Before you start, make sure you have:

A ParseHub.dev account (or create one with /register)
An API key or JWT token for authentication
A REST client or curl installed

Your First Request

Let's start with a simple health check to verify the API is working:

Curl

curl -X GET https://parsehub.dev/health

You should receive a 200 response indicating the API is healthy. Now let's create an account and get authentication set up.

Register a New Account

Curl

curl -X POST https://parsehub.dev/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'

Response:

JSON

{
  "id": "user_123",
  "email": "[email protected]",
  "created_at": "2024-03-25T10:30:00Z"
}

Get Your Authentication Token

After registering, obtain a JWT token to authenticate future requests:

Curl

curl -X POST https://parsehub.dev/token \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "securepassword123"
  }'

Response:

JSON

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Verify Your Account

Check your current user information using your new token:

Curl

curl -X GET https://parsehub.dev/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Authentication

ParseHub.dev supports two authentication methods: JWT Bearer tokens and API keys. Choose the method that best fits your use case.

JWT Bearer Token

JWT tokens are ideal for user-initiated requests and have an expiration time. Obtain them via the /token endpoint and include in the Authorization header.

Curl with JWT

curl -X GET https://parsehub.dev/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

API Key Authentication

API keys are perfect for server-to-server communication and long-lived integrations. They don't expire and can be managed in your account settings. Include them via the X-API-Key header.

Curl with API Key

curl -X GET https://parsehub.dev/users/me \
  -H "X-API-Key: pk_live_abc123def456..."

Python Example

Here's how to authenticate in Python using the requests library:

Python

import requests

# Using JWT Token
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
response = requests.get(
    "https://parsehub.dev/users/me",
    headers=headers
)

# Or using API Key
headers = {
    "X-API-Key": "pk_live_abc123def456..."
}
response = requests.get(
    "https://parsehub.dev/users/me",
    headers=headers
)

Tip: API keys are recommended for production applications. Store them securely and never commit them to version control.

CSV Processing

Process and analyze CSV files with powerful operations including filtering, sorting, grouping, and data transformation.

Upload a CSV File

Start by uploading a CSV file to ParseHub:

Curl

curl -X POST https://parsehub.dev/csv/upload \
  -H "X-API-Key: pk_live_abc123def456..." \
  -F "[email protected]"

Response:

JSON

{
  "file_path": "uploads/csv/data_abc123.csv",
  "filename": "data.csv",
  "size_bytes": 15240,
  "rows": 150,
  "columns": 8
}

List Uploaded CSVs

View all CSV files you've uploaded:

Curl

curl -X GET https://parsehub.dev/csv/list \
  -H "X-API-Key: pk_live_abc123def456..."

Get CSV Summary & Statistics

Retrieve statistical information about your CSV:

Curl

curl -X GET "https://parsehub.dev/csv/summary/data_abc123.csv" \
  -H "X-API-Key: pk_live_abc123def456..."

Response:

JSON

{
  "shape": [150, 8],
  "columns": ["name", "age", "salary"],
  "dtypes": {
    "name": "object",
    "age": "int64",
    "salary": "float64"
  },
  "stats": {
    "age": {
      "mean": 35.2,
      "median": 34,
      "std": 8.5,
      "min": 22,
      "max": 65
    }
  }
}

Process CSV with Operations

Apply multiple data transformations in a single request:

Curl

curl -X POST https://parsehub.dev/csv/process \
  -H "X-API-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "uploads/csv/data_abc123.csv",
    "operations": [
      {
        "type": "filter",
        "column": "age",
        "operator": ">=",
        "value": 30
      },
      {
        "type": "sort",
        "column": "salary",
        "ascending": false
      },
      {
        "type": "drop_columns",
        "columns": ["internal_id"]
      }
    ]
  }'

Supported CSV Operations

ParseHub supports the following data operations:

Operation	Description	Example
filter	Filter rows based on column value	`{"type": "filter", "column": "age", "operator": ">=", "value": 30}`
sort	Sort by column (ascending or descending)	`{"type": "sort", "column": "salary", "ascending": false}`
drop_columns	Remove columns from dataset	`{"type": "drop_columns", "columns": ["id", "temp"]}`
rename_columns	Rename columns	`{"type": "rename_columns", "mapping": {"old_name": "new_name"}}`
fill_na	Fill missing values	`{"type": "fill_na", "column": "age", "value": 0}`
drop_na	Remove rows with missing values	`{"type": "drop_na", "columns": ["salary"]}`
group_by	Group and aggregate data	`{"type": "group_by", "column": "dept", "aggregations": {"salary": "mean"}}`

Delete a CSV File

Curl

curl -X DELETE "https://parsehub.dev/csv/data_abc123.csv" \
  -H "X-API-Key: pk_live_abc123def456..."

Document Processing

Upload and process PDF and Word documents to extract text, structure, and metadata.

Upload a Document

Upload a PDF or Word document (.pdf, .docx, .doc):

Curl

curl -X POST https://parsehub.dev/documents/upload \
  -H "X-API-Key: pk_live_abc123def456..." \
  -F "[email protected]" \
  -F "doc_type=general"

Document Types:

general - Standard document (default)
meeting_notes - Meeting minutes or transcript

Response:

JSON

{
  "file_path": "uploads/documents/contract_abc123.pdf",
  "filename": "contract.pdf",
  "doc_type": "general",
  "pages": 8,
  "size_bytes": 245680
}

List Documents

View all uploaded documents:

Curl

curl -X GET https://parsehub.dev/documents/list \
  -H "X-API-Key: pk_live_abc123def456..."

Read Document Content

Extract and retrieve the text content from a document:

Curl

curl -X GET "https://parsehub.dev/documents/read/contract_abc123.pdf" \
  -H "X-API-Key: pk_live_abc123def456..."

Response:

JSON

{
  "file_path": "uploads/documents/contract_abc123.pdf",
  "content": "This Service Agreement is entered into as of...",
  "word_count": 2847,
  "page_count": 8
}

Delete a Document

Curl

curl -X DELETE "https://parsehub.dev/documents/contract_abc123.pdf" \
  -H "X-API-Key: pk_live_abc123def456..."

Meeting Notes Extraction

Automatically extract structured information from meeting transcripts and notes, including attendees, action items, and key topics.

Extract Meeting Notes

For documents uploaded with doc_type: meeting_notes, extract structured data:

Curl

curl -X GET "https://parsehub.dev/documents/meeting-notes/meeting_abc123.pdf" \
  -H "X-API-Key: pk_live_abc123def456..."

Response:

JSON

{
  "file_path": "uploads/documents/meeting_abc123.pdf",
  "title": "Q1 Planning Meeting",
  "date": "2024-03-25",
  "attendees": ["John Smith", "Sarah Johnson"],
  "agenda": ["Review Q4 results", "Q1 priorities"],
  "action_items": [{
    "task": "Financial report",
    "owner": "Sarah Johnson",
    "due_date": "2024-04-01"
  }],
  "key_decisions": ["30% budget increase to product"]
}

Pro Tip: Ensure your meeting documents are clear and well-formatted for best extraction results. The API works best with transcripts or typed notes.

Question & Answer

Ask natural language questions about documents to extract specific information and insights.

Ask Questions About Documents

Submit a question about an uploaded document and receive relevant answers:

Curl

curl -X POST https://parsehub.dev/documents/ask \
  -H "X-API-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "uploads/documents/contract_abc123.pdf",
    "question": "What are the payment terms?"
  }'

Response:

JSON

{
  "question": "What are the payment terms?",
  "answer": "Payment is due net 30 days from invoice.",
  "confidence": 0.95,
  "source_pages": [3, 4]
}

Python Example

Here's a practical example in Python:

Python

import requests

api_key = "pk_live_abc123def456..."
headers = {"X-API-Key": api_key}

response = requests.post(
    "https://parsehub.dev/documents/ask",
    headers=headers,
    json={
        "file_path": "uploads/documents/contract.pdf",
        "question": "What are the payment terms?"
    }
)

data = response.json()
print(f"Answer: {data['answer']}")
print(f"Confidence: {data['confidence']}")

Note: Confidence scores range from 0 to 1. Scores below 0.7 indicate the answer may be uncertain.

Subscriptions & Billing

ParseHub offers flexible pricing plans to suit different needs. Upgrade your account to unlock more features and higher rate limits.

Pricing Plans

Free

$0/month

1 document upload
100 requests/month
5MB max file size
Community support

Monthly Pro

$9/month

Unlimited documents
5,000 requests/month
100MB max file size
Email support
Meeting notes extraction

Yearly Pro

$84/year

Unlimited documents
5,000 requests/month
100MB max file size
Priority email support
Meeting notes extraction
30% discount vs monthly

Get Your Subscription Status

Curl

curl -X GET https://parsehub.dev/subscription \
  -H "X-API-Key: pk_live_abc123def456..."

Response:

JSON

{
  "plan": "monthly",
  "status": "active",
  "current_period_start": "2024-02-25T00:00:00Z",
  "current_period_end": "2024-03-25T00:00:00Z",
  "requests_this_month": 1242,
  "requests_limit": 5000
}

Upgrade Your Subscription

Create a checkout session to upgrade to a paid plan via Stripe:

Curl

curl -X POST https://parsehub.dev/create-checkout-session \
  -H "X-API-Key: pk_live_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "plan": "monthly"
  }'

Response:

JSON

{
  "checkout_session_id": "cs_live_abc123def456",
  "checkout_url": "https://checkout.stripe.com/pay/cs_abc123"
}

Cancel Your Subscription

End your paid subscription at any time:

Curl

curl -X POST https://parsehub.dev/cancel-subscription \
  -H "X-API-Key: pk_live_abc123def456..."

API Keys

API keys provide a secure way to authenticate your application with the ParseHub API without exposing user credentials.

Creating API Keys

You can generate API keys from your account settings. API keys come in two types:

Live Keys - For production use (prefixed with pk_live_)
Test Keys - For development and testing (prefixed with pk_test_)

Security: Never share your API keys in public repositories or client-side code. Always use environment variables or secure secret management for production applications.

Using API Keys

Include your API key in the X-API-Key header of every request:

Curl

curl -X GET https://parsehub.dev/documents/list \
  -H "X-API-Key: pk_live_your_api_key_here"

Rotating API Keys

We recommend rotating your API keys periodically for security. You can create new keys and delete old ones from your account dashboard.

Rate Limits

ParseHub implements rate limiting to ensure fair usage and protect our service. Rate limits are applied per user account.

Rate Limit Tiers

Plan	Requests/Month	Burst Limit	Reset Cycle
Free	100	10/minute	Monthly
Monthly Pro	5,000	100/minute	Monthly
Yearly Pro	5,000	100/minute	Monthly

Rate Limit Headers

Every API response includes rate limit information in the headers:

HTTP Headers

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1711324800

Handling Rate Limit Exceeded

When you exceed your rate limit, the API returns a 429 (Too Many Requests) response:

Response

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your monthly request limit",
  "retry_after": 86400
}

The retry_after field indicates the number of seconds until you can make requests again.

Best Practice: Implement exponential backoff when handling 429 responses. This helps distribute load and improves overall reliability.

Complete API Reference

A comprehensive reference of all available ParseHub endpoints.

Authentication Endpoints

Method	Endpoint	Auth	Description
POST	`/register`	None	Register a new user account
POST	`/token`	None	Get JWT authentication token
GET	`/users/me`	Required	Get current user information
GET	`/health`	None	Health check endpoint

CSV Endpoints

Method	Endpoint	Auth	Description
POST	`/csv/upload`	Required	Upload a CSV file
GET	`/csv/list`	Required	List all uploaded CSV files
GET	`/csv/summary/{file_path}`	Required	Get CSV statistics and summary
POST	`/csv/process`	Required	Process CSV with operations
DELETE	`/csv/{file_path}`	Required	Delete a CSV file

Document Endpoints

Method	Endpoint	Auth	Description
POST	`/documents/upload`	Required	Upload PDF or Word document
GET	`/documents/list`	Required	List all uploaded documents
GET	`/documents/read/{file_path}`	Required	Read document content
POST	`/documents/ask`	Required	Ask questions about a document
GET	`/documents/meeting-notes/{file_path}`	Required	Extract meeting notes structure
DELETE	`/documents/{file_path}`	Required	Delete a document

Subscription Endpoints

Method	Endpoint	Auth	Description
GET	`/subscription`	Required	Get subscription status
POST	`/create-checkout-session`	Required	Create Stripe checkout session
POST	`/cancel-subscription`	Required	Cancel active subscription
POST	`/verify-checkout`	Required	Verify checkout session
POST	`/webhook`	Webhook	Stripe webhook handler

Ready to get started? Visit the Getting Started section to make your first API call today.