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, TXT, MD, JSON, XML, HTML, YAML, and LOG 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
  • chunk (default: false) — Split document into semantic chunks for RAG
  • chunk_size (default: 600) — Maximum chunk size in tokens
  • chunk_overlap (default: 200) — Overlapping tokens between chunks
  • session_ttl — How long results stay cached, in seconds (default: 1800 / 30 minutes, 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 (up to 200 MB per file):

  • Tabular data: CSV, XLSX, XLS, Parquet — queried using natural language
  • Documents: PDF, DOCX, PPTX, TXT, MD, JSON, XML, HTML, YAML, LOG — 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
}'

How it works:

  • For tabular data, ParseSphere analyzes your data and returns precise answers
  • For documents, it searches relevant passages and synthesizes responses
  • Mixed workspaces? It figures out the best approach automatically

Use the conversation_id from the response to continue the conversation with follow-up questions. Streaming is enabled by default (stream: true); set stream: false for a single JSON response as shown above.

What's Next?

You're all set!

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