ParseSphere

Quick Start

Get up and running with ParseSphere in three simple steps.

New to ParseSphere?

This guide will walk you through your first API call. You'll need an API key from the dashboard.

Step 1: Get Your API Key

Create an API key from the dashboard. Your API key starts with ps_ and should be stored securely in environment variables.

Warning

Never commit API keys to source control. Use environment variables or secrets management.

Step 2: Parse a Document

Submit a document for parsing using our API. Optional parameters:

  • process_images (default: true) - Enable OCR for images and scanned documents
  • extract_tables (default: true) - Extract tables into structured format
  • session_ttl (default: 24 hours) - How long results remain cached (in seconds, minimum 60)
POST/v1/parses

Submit a document for text extraction and processing

bash
curl -X POST https://api.parsesphere.com/v1/parses \
-H "Authorization: Bearer sk_your_api_key" \
-F "file=@document.pdf" \
-F "process_images=true" \
-F "extract_tables=true" \
-F "session_ttl=1800"

Step 3: Retrieve Results

Poll the status endpoint to check progress:

GET/v1/parses/{parse_id}

Check processing status and retrieve results

bash
curl https://api.parsesphere.com/v1/parses/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer sk_your_api_key"

Processing States

Queued

Waiting for available worker

Processing

Extracting content

Completed

Results ready

Failed

Error occurred

Polling Best Practices

Production Tip

For production use, provide a webhook_url when creating a parse to receive automatic notifications when processing completes, eliminating the need for polling.

  • Check the status endpoint every 5 seconds while status is queued or processing
  • Stop polling once status is completed or failed
  • The progress field (0-100%) and optional message provide real-time updates during processing
  • Results remain cached for 24 hours by default (configurable via session_ttl parameter, minimum 60 seconds)

Query Tabular Data

ParseSphere also lets you query CSV and Excel files using natural language.

Step 1: Create a Workspace

POST/v1/workspaces

Create a container for organizing related datasets

bash
curl -X POST https://api.parsesphere.com/v1/workspaces \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "name": "Sales Analysis",
  "description": "Q4 sales data"
}'

Step 2: Upload a Dataset

POST/v1/workspaces/{workspace_id}/datasets

Upload a CSV or Excel file to your workspace

bash
curl -X POST https://api.parsesphere.com/v1/workspaces/{workspace_id}/datasets \
-H "Authorization: Bearer sk_your_api_key" \
-F "file=@sales_data.csv"

Information

Processing time varies by file size and complexity. Check status at the status_url returned in the response.

Step 3: Query Your Data

POST/v1/workspaces/{workspace_id}/query

Ask questions about your data in natural language

bash
curl -X POST https://api.parsesphere.com/v1/workspaces/{workspace_id}/query \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "query": "What are the top 5 products by revenue?"
}'

ParseSphere will interpret your question, retrieve the relevant data, and return a natural language answer with structured results.

What's Next?

You're Ready!

You've made your first API call. Now explore advanced features and best practices.

Now that you've made your first API call, explore these resources:

  • Authentication - Learn about API key management and security
  • Document Parsing - Deep dive into extraction options and formats
  • Tabula - Master natural language queries for tabular data
  • Dashboard - Manage your API keys, workspaces, and monitor usage
  • API Reference - Complete API documentation with all endpoints