Getting Started

Quick Start

Smole is a document extraction API that converts documents to Markdown and extracts structured data using AI. Get started in minutes with just a few API calls. See Configuration for details on how the pipeline works.

Prefer to start in your browser? Upload one or more files in the Playground, review the extracted fields and tables, and download Excel, CSV or JSON. Available document text can also be saved as Markdown. These views and downloads use the completed result at no extra charge. The API returns JSON; spreadsheet downloads are available in the Playground. See Guides for output formats and batch downloads.

1. Get your API key

Sign up for an account and create an API key from your dashboard. Your API key starts with ak_. See Security for best practices on storing your keys.

2. Register a schema

Create a JSON schema that defines the structure of data you want to extract. See Schemas for a complete guide on schema structure, supported types, and best practices.

curl -X POST https://api.smole.tech/api/schemas \
  -H "X-API-Key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Schema",
    "jsonSchema": {
      "type": "object",
      "properties": {
        "invoiceNumber": { "type": "string" },
        "total": { "type": "number" },
        "date": { "type": "string" }
      },
      "required": ["invoiceNumber", "total"]
    }
  }'

Save the returned id - you'll use it for extraction jobs.

3. Upload a document

Send a document file with your schema ID to start extraction:

curl -X POST https://api.smole.tech/api/pipeline/file \
  -H "X-API-Key: ak_your_api_key" \
  -F "file=@invoice.pdf" \
  -F "schemaId=your_schema_id"

4. Poll for results

The pipeline returns a job ID. Poll the status endpoint until the job completes:

curl https://api.smole.tech/api/pipeline/{job_id} \
  -H "X-API-Key: ak_your_api_key"

When status is "completed", the result field contains your extracted JSON data.

Run a Workflow

A workflow saves a schema together with how documents are prepared, so every run of that kind of document is processed the same way. In the app, open Workflows, choose New workflow, pick a schema and the settings, then send it documents from your system. The workflow page shows the request with the workflow's ID filled in, lists every run and exports the results.

With the API, use a file key for your workspace with the workflows:write, runs:submit and documents:read scopes. Create the workflow, then run a file with its id instead of a schema ID:

# Your workspace ID
curl https://api.smole.tech/v1/workspaces \
  -H "X-API-Key: your_file_key"

# Create the workflow (version 1)
curl -X POST https://api.smole.tech/v1/workspaces/{workspace_id}/workflows \
  -H "X-API-Key: your_file_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoices (scans)",
    "description": "",
    "schemaId": "your_schema_id",
    "definition": {
      "contractVersion": 2,
      "preparation": { "forceOcr": true, "preserveTables": true, "preserveLinks": true, "maxPages": null }
    }
  }'

# Run a document with the workflow
curl -X POST https://api.smole.tech/api/pipeline/file \
  -H "X-API-Key: your_file_key" \
  -F "file=@invoice.pdf" \
  -F "workflowId=your_workflow_id"

Poll the run as in step 4. The workflow supplies the schema and settings, so send no processing options with workflowId. Workflow runs are billed like any other document: each one uses 1 document unit. See API Reference for every workflow endpoint.

Send documents to a workflow

A workflow gets its documents from your system, with the API. Each one uses the workflow's current version and appears under Results on the workflow page.

A connected source, a watched Google Drive folder or an email inbox, sends it new files by itself: see Connected sources and outputs.

From your system. Send one request per document to POST /api/pipeline/file with the workflow's workflowId. Use a file key with the runs:submit scope: in Account, API keys, choose New file key, open Advanced access and tick Submit processing. Reading results with the API needs the Read documents (documents:read) scope, which a new key has by default. The workflow page shows this request with the workflow's ID already filled in.

curl -X POST https://api.smole.tech/api/pipeline/file \
  -H "X-API-Key: your_file_key" \
  -H "Idempotency-Key: invoice-0001.pdf" \
  -F "file=@invoice-0001.pdf" \
  -F "workflowId=your_workflow_id"

Use a new Idempotency-Key for each document you send to a workflow, such as the file's name: repeating a key returns the same run, so a retry is safe; a key already used for another workflow is refused. To get results out, export them from the workflow page, or add a webhook to the workflow to have each result sent to your system.

Tutorials

Dive deeper with step-by-step guides: