> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runpulse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart Guide

> Get up and running with Pulse API in 5 minutes

## Prerequisites

Before you begin, make sure you have:

<CardGroup cols={2}>
  <Card title="API Key" icon="key">
    Get your API key from the [Platform](https://platform.runpulse.com)
  </Card>

  <Card title="SDK or HTTP Client" icon="code">
    Install the official SDK or use curl/fetch
  </Card>
</CardGroup>

## Step 1: Install the SDK

<CodeGroup>
  ```bash Python theme={null}
  pip install pulse-python-sdk
  ```

  ```bash TypeScript theme={null}
  npm install pulse-ts-sdk
  ```
</CodeGroup>

## Step 2: Basic Document Extraction

Extract content from a document URL:

<CodeGroup>
  ```python Python theme={null}
  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://www.impact-bank.com/user/file/dummy_statement.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}")
  ```

  ```typescript TypeScript theme={null}
  import { PulseClient } from 'pulse-ts-sdk';

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

  const response = await client.extract({
      fileUrl: "https://www.impact-bank.com/user/file/dummy_statement.pdf",
      figureProcessing: { description: true },
      extensions: { altOutputs: { returnHtml: true } }
  });

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

  ```bash curl theme={null}
  curl -X POST https://api.runpulse.com/extract \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "file_url": "https://www.impact-bank.com/user/file/dummy_statement.pdf",
      "figureProcessing": {"description": true},
      "extensions": {"altOutputs": {"returnHtml": true}}
    }'
  ```
</CodeGroup>

## Step 3: Uploading Files Directly

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

<CodeGroup>
  ```python Python theme={null}
  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}")
  ```

  ```typescript TypeScript theme={null}
  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}`);
  ```

  ```bash curl theme={null}
  # 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"
  ```
</CodeGroup>

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

## Step 4: Asynchronous Processing for Large Documents

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

<CodeGroup>
  ```python Python theme={null}
  import time
  from pulse import Pulse

  client = Pulse(api_key="YOUR_API_KEY")

  # Submit async extraction
  submission = client.extract(
      file_url="https://www.impact-bank.com/user/file/dummy_statement.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)
  ```

  ```typescript TypeScript theme={null}
  import { PulseClient } from 'pulse-ts-sdk';

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

  // Submit async extraction
  const submission = await client.extract({
      fileUrl: "https://www.impact-bank.com/user/file/dummy_statement.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));
  }
  ```

  ```bash curl theme={null}
  # 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://www.impact-bank.com/user/file/dummy_statement.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"
  ```
</CodeGroup>

<Note>
  `POST /extract_async` is **deprecated**. Use `POST /extract` with `async: true` instead. See [Async Processing](/api-reference/async-processing) for details.
</Note>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Invoice Processing">
    Extract structured data from invoices:

    <CodeGroup>
      ```python Python theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      )

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

      ```typescript TypeScript theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      });

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

  <Accordion title="Contract Analysis">
    Extract key terms from contracts:

    <CodeGroup>
      ```python Python theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      )

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

      ```typescript TypeScript theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      });

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

  <Accordion title="Research Paper Processing">
    Extract structured content from academic papers:

    <CodeGroup>
      ```python Python theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      )

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

      ```typescript TypeScript theme={null}
      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://www.impact-bank.com/user/file/dummy_statement.pdf"
      });

      // Step 2: Apply schema
      const schemaResult = await client.schema({
          extraction_id: response.extraction_id,
          schema_config: { input_schema: schema }
      });
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Schema Extraction" icon="code" href="/api-reference/endpoint/schema">
    Apply schemas to extracted documents
  </Card>

  <Card title="Large Documents" icon="file-lines" href="/api-reference/large-documents">
    Best practices for big files
  </Card>

  <Card title="Async Processing" icon="clock" href="/api-reference/async-processing">
    Async flag, polling, and webhooks
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore all endpoints
  </Card>
</CardGroup>