API Quickstart

Prerequisites

Before you begin, make sure you have:

API Key

Get your API key from the Platform

SDK or HTTP Client

Install the official SDK or use curl/fetch

Step 1: Install the SDK

pip install pulse-python-sdk

npm install pulse-ts-sdk

Step 2: Basic Document Extraction

Extract content from a document URL:

from pulse import Pulse
from pulse.types import (
    ExtractRequestFigureProcessing,
    ExtractRequestExtensions,
    ExtractRequestExtensionsAltOutputs,
)

client = Pulse(api_key="YOUR_API_KEY")

# Extract from a URL
response = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    figure_processing=ExtractRequestFigureProcessing(
        description=True,
    ),
    extensions=ExtractRequestExtensions(
        alt_outputs=ExtractRequestExtensionsAltOutputs(
            return_html=True,
        ),
    ),
)

print(f"Markdown: {response.markdown}")
print(f"Extraction ID: {response.extraction_id}")

import { PulseClient } from 'pulse-ts-sdk';

const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

const response = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    figureProcessing: { description: true },
    extensions: { altOutputs: { returnHtml: true } }
});

console.log(`Markdown: ${response.markdown}`);
console.log(`Extraction ID: ${response.extraction_id}`);

curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_url": "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    "figureProcessing": {"description": true},
    "extensions": {"altOutputs": {"returnHtml": true}}
  }'

Step 3: Uploading Files Directly

/extract accepts file uploads directly via multipart/form-data:

from pulse import Pulse
from pulse.types import ExtractRequestFigureProcessing

client = Pulse(api_key="YOUR_API_KEY")

# Upload and extract a local file
with open("invoice.pdf", "rb") as f:
    response = client.extract(
        file=f,
        pages="1-5",  # 1-indexed page range
        figure_processing=ExtractRequestFigureProcessing(
            description=True,
        ),
    )

print(f"Extraction ID: {response.extraction_id}")
print(f"Markdown: {response.markdown}")

import * as fs from 'fs';
import { PulseClient } from 'pulse-ts-sdk';

const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

// Upload and extract a local file
const fileBuffer = fs.readFileSync("invoice.pdf");
const blob = new Blob([fileBuffer], { type: 'application/pdf' });

const response = await client.extract({
    file: blob,
    pages: "1-5",  // 1-indexed page range
    figureProcessing: { description: true }
});

console.log(`Extraction ID: ${response.extraction_id}`);
console.log(`Markdown: ${response.markdown}`);

# Upload a file directly
curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@invoice.pdf" \
  -F "pages=1-5"

Use file for direct uploads or file_url when you have a public/presigned URL.

Step 4: Asynchronous Processing for Large Documents

For documents over 50 pages or when processing multiple files, use async: true on the /extract endpoint:

import time
from pulse import Pulse

client = Pulse(api_key="YOUR_API_KEY")

# Submit async extraction
submission = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    figure_processing=ExtractRequestFigureProcessing(description=True),
    async_=True  # Note: async_ in Python (async is reserved)
)

print(f"Job submitted: {submission.job_id}")

# Poll for completion
job_id = submission.job_id
while True:
    job_status = client.jobs.get_job(job_id=job_id)
    print(f"Status: {job_status.status}")
    
    if job_status.status == "completed":
        print("Job completed!")
        print(f"Result: {job_status.result}")
        break
    elif job_status.status in ["failed", "canceled"]:
        print(f"Job ended: {job_status.status}")
        break
    
    time.sleep(2)

import { PulseClient } from 'pulse-ts-sdk';

const client = new PulseClient({ apiKey: "YOUR_API_KEY" });

// Submit async extraction
const submission = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf",
    async: true
});

console.log(`Job submitted: ${submission.job_id}`);

// Poll for completion
const jobId = submission.job_id;
while (true) {
    const jobStatus = await client.jobs.getJob({ jobId });
    console.log(`Status: ${jobStatus.status}`);
    
    if (jobStatus.status === 'completed') {
        console.log('Job completed!');
        console.log(`Result: ${JSON.stringify(jobStatus.result)}`);
        break;
    } else if (jobStatus.status === 'failed' || jobStatus.status === 'canceled') {
        console.log(`Job ended: ${jobStatus.status}`);
        break;
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
}

# Submit async extraction
curl -X POST https://api.runpulse.com/extract \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf", "async": true}'

# Response: {"job_id": "abc123", "status": "pending", "message": "Document processing started"}

# Poll for results
curl https://api.runpulse.com/job/abc123 \
  -H "x-api-key: YOUR_API_KEY"

POST /extract_async is deprecated. Use POST /extract with async: true instead. See Async Processing for details.

Common Use Cases

Invoice Processing

Extract structured data from invoices:

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "vendor_name": {"type": "string"},
        "total": {"type": "number"},
        "line_items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "description": {"type": "string"},
                    "amount": {"type": "number"}
                }
            }
        }
    }
}

# Step 1: Extract the document
response = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
)

# Step 2: Apply schema via /schema endpoint
schema_result = client.schema(
    extraction_id=response.extraction_id,
    schema_config={"input_schema": schema}
)

const schema = {
    type: "object",
    properties: {
        invoice_number: { type: "string" },
        vendor_name: { type: "string" },
        total: { type: "number" }
    }
};

// Step 1: Extract the document
const response = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
});

// Step 2: Apply schema via /schema endpoint
const schemaResult = await client.schema({
    extraction_id: response.extraction_id,
    schema_config: { input_schema: schema }
});

Contract Analysis

Extract key terms from contracts:

schema = {
    "type": "object",
    "properties": {
        "parties": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"}
                }
            }
        },
        "effective_date": {"type": "string"},
        "payment_terms": {"type": "string"}
    }
}

# Step 1: Extract
response = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
)

# Step 2: Apply schema
schema_result = client.schema(
    extraction_id=response.extraction_id,
    schema_config={"input_schema": schema}
)

const schema = {
    type: "object",
    properties: {
        parties: {
            type: "array",
            items: {
                type: "object",
                properties: {
                    name: { type: "string" },
                    role: { type: "string" }
                }
            }
        },
        effective_date: { type: "string" },
        payment_terms: { type: "string" }
    }
};

// Step 1: Extract
const response = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
});

// Step 2: Apply schema
const schemaResult = await client.schema({
    extraction_id: response.extraction_id,
    schema_config: { input_schema: schema }
});

Research Paper Processing

Extract structured content from academic papers:

schema = {
    "type": "object",
    "properties": {
        "title": {"type": "string"},
        "authors": {"type": "array", "items": {"type": "string"}},
        "abstract": {"type": "string"},
        "keywords": {"type": "array", "items": {"type": "string"}}
    }
}

# Step 1: Extract
response = client.extract(
    file_url="https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
)

# Step 2: Apply schema
schema_result = client.schema(
    extraction_id=response.extraction_id,
    schema_config={"input_schema": schema}
)

const schema = {
    type: "object",
    properties: {
        title: { type: "string" },
        authors: { type: "array", items: { type: "string" } },
        abstract: { type: "string" },
        keywords: { type: "array", items: { type: "string" } }
    }
};

// Step 1: Extract
const response = await client.extract({
    fileUrl: "https://platform.runpulse.com/api/examples/637e5678-30b1-45fa-acc4-877f2d636419/pdf"
});

// Step 2: Apply schema
const schemaResult = await client.schema({
    extraction_id: response.extraction_id,
    schema_config: { input_schema: schema }
});

Next Steps

Schema Extraction

Apply schemas to extracted documents

Route by Document Type

Classify mixed intake before extracting

Large Documents

Best practices for big files

Async Processing

Async flag, polling, and webhooks

API Reference

Explore all endpoints

Start Here

Agent Tools

Core Concepts

Security & Compliance

Help

Prerequisites

API Key

SDK or HTTP Client

Step 1: Install the SDK

Step 2: Basic Document Extraction

Step 3: Uploading Files Directly

Step 4: Asynchronous Processing for Large Documents

Common Use Cases

Next Steps

Schema Extraction

Route by Document Type

Large Documents

Async Processing

API Reference

​Prerequisites

API Key

SDK or HTTP Client

​Step 1: Install the SDK

​Step 2: Basic Document Extraction

​Step 3: Uploading Files Directly

​Step 4: Asynchronous Processing for Large Documents

​Common Use Cases

​Next Steps

Schema Extraction

Route by Document Type

Large Documents

Async Processing

API Reference

Prerequisites

Step 1: Install the SDK

Step 2: Basic Document Extraction

Step 3: Uploading Files Directly

Step 4: Asynchronous Processing for Large Documents

Common Use Cases

Next Steps