ParseSphereParseSphere

Developer Quick Start

Get up and running with the ParseSphere API in minutes.

For Developers

This guide walks you through your first API calls. For a no-code experience, see the Dashboard Guide.

ParseSphere offers two main capabilities:

  • Document Parsing — Extract text, tables, and metadata from documents
  • Workspaces — Upload files and chat with your data using natural language

Document Parsing

Perfect for extracting content from documents without needing to store them long-term.

Step 1: Get Your API Key

Create an API key from the dashboard. Your key starts with sk_ and should be kept secure.

Warning

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

Step 2: Parse a Document

Submit a document for parsing. We support PDF, DOCX, PPTX, XLSX, CSV, MD and TXT files up to 200MB.

POST/v1/parses

Submit a document for text extraction

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"

Optional parameters:

  • process_images (default: true) — Run OCR on images and scanned pages
  • extract_tables (default: true) — Extract tables as structured data
  • session_ttl — How long results stay cached, in seconds (default: 24 hours, minimum: 60)

Step 3: Retrieve Results

Poll the status endpoint until processing completes:

GET/v1/parses/{parse_id}

Check status and get 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

Skip the polling

Pass a webhook_url when creating a parse to get notified automatically when processing finishes.

Workspaces

Workspaces let you upload files and have conversations with your data. Ask questions in plain English — ParseSphere handles the rest.

Supported file types:

  • Tabular data: CSV, XLSX, XLS, Parquet — queried via SQL under the hood
  • Documents: PDF, DOCX, PPTX, TXT — searched using AI-powered semantic search

Step 1: Create a Workspace

POST/v1/workspaces

Create a workspace to organize your files

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

Step 2: Upload Files

Upload tabular data (CSV, Excel) for SQL-style analysis, or documents (PDF, DOCX) for semantic search.

POST/v1/workspaces/{workspace_id}/files

Upload a file to your workspace

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

The category field tells you how the file will be processed:

  • tabular — CSV, Excel, Parquet files become queryable tables
  • document — PDFs and documents are chunked and indexed for search

Information

Processing time depends on file size. Check the status_url to track progress.

Step 3: Chat with Your Data

Once your files are processed, start asking questions:

POST/v1/workspaces/{workspace_id}/chat

Ask questions about your data

bash
curl -X POST https://api.parsesphere.com/v1/workspaces/{workspace_id}/chat \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
  "message": "What were the top 5 products by revenue last quarter?",
  "stream": false
}'

What happens behind the scenes:

  • For tabular data, ParseSphere generates and runs SQL queries
  • For documents, it searches relevant passages using semantic similarity
  • Mixed workspaces? It figures out the best approach automatically

Use the conversation_id from the response to continue the conversation with follow-up questions.

What's Next?

You're all set!

You've learned the basics. Time to dig deeper.