Skip to content

reference.md

Latest commit

 

History

History
2381 lines (1642 loc) · 46 KB

reference.md

File metadata and controls

2381 lines (1642 loc) · 46 KB
Raw

Reference

client.extract(...) -> ExtractResponse

📝 Description

The primary endpoint for the Pulse API. Parses uploaded documents or remote file URLs and returns rich markdown content with optional structured data extraction based on user-provided schemas and extraction options.

Set async: true to return immediately with a job_id for polling via GET /job/{jobId}. Otherwise processes synchronously.

To process many files at once, see Batch Extract or the Batch Processing guide.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.extract(
    file="example_file",
)

⚙️ Parameters

file: typing.Optional[core.File] — Document to upload directly. Required unless fileUrl is provided.

file_url: typing.Optional[str] — Public or pre-signed URL that Pulse will download and extract. Required unless file is provided.

model: typing.Optional[ExtractRequestModel] — Extraction model to use. When set to pulse-ultra-2, routes the request through Pulse Ultra 2 (self-hosted VPC model) instead of the default cloud-based service. If omitted or set to default, the default model is used.

extraction_config_id: typing.Optional[str] — UUID of a saved extraction configuration (a "preset"). When provided, the server loads the saved configuration and applies its options on top of any inline parameters supplied in this request. Inline parameters always take precedence over preset values for the same field. Saved configs are managed via the platform UI or the input_extractions admin endpoints.

pages: typing.Optional[str] — Page range filter supporting segments such as 1-2 or mixed ranges like 1-2,5.

figure_processing: typing.Optional[ExtractRequestFigureProcessing] — Settings that control how figures and embedded visuals are processed. Applies to both PDFs/images (where figures are detected from layout) and spreadsheets (where charts and embedded images are read directly from the workbook). These options affect the markdown output and the bounding_boxes.Images[] array; they do not produce additional output fields elsewhere in the response.

extensions: typing.Optional[ExtractRequestExtensions] — Settings that enable additional processing passes or alternate output formats. Each enabled extension produces a corresponding output field under response.extensions.*.

spreadsheet: typing.Optional[ExtractRequestSpreadsheet] — Settings for Excel/spreadsheet extraction. Controls handling of hidden rows, columns, and sheets, whether numeric cells are rendered using their display format or underlying raw value, and optional trimming of empty phantom rows/columns past the last data-bearing cell. Applies to .xlsx, .xlsm, and .xls files. Accepts both camelCase and snake_case field names.

storage: typing.Optional[ExtractRequestStorage] — Options for persisting extraction artifacts. When enabled (default), artifacts are saved to storage and a database record is created.

async: typing.Optional[bool] — If true, returns immediately with a job_id for polling via GET /job/{jobId}. Otherwise processes synchronously.

structured_output: typing.Optional[ExtractRequestStructuredOutput] — ⚠️ DEPRECATED — Use the /schema endpoint after extraction instead. Pass the extraction_id from the extract response to /schema with your schema_config. This parameter still works for backward compatibility but will be removed in a future version.

schema: typing.Optional[ExtractRequestSchema] — (Deprecated) JSON schema describing structured data to extract. Use structuredOutput instead. Accepts either a JSON object or a stringified JSON representation.

schema_prompt: typing.Optional[str] — (Deprecated) Natural language prompt for schema-guided extraction. Use structuredOutput.schemaPrompt instead.

custom_prompt: typing.Optional[str] — (Deprecated) Custom instructions that augment the default extraction behaviour. Use figureProcessing or extensions instead.

chunking: typing.Optional[str] — ⚠️ DEPRECATED — Use extensions.chunking.chunkTypes instead. Comma-separated list of chunking strategies to apply (for example semantic,header,page,recursive). Still accepted for backward compatibility.

chunk_size: typing.Optional[int] — ⚠️ DEPRECATED — Use extensions.chunking.chunkSize instead. Override for maximum characters per chunk when chunking is enabled.

extract_figure: typing.Optional[bool] — ⚠️ DEPRECATED — Toggle to enable figure extraction in results.

figure_description: typing.Optional[bool] — ⚠️ DEPRECATED — Use figureProcessing.description instead. Toggle to generate descriptive captions for extracted figures.

show_images: typing.Optional[bool] — ⚠️ DEPRECATED — Use figureProcessing.showImages instead. Embed base64-encoded images inline in figure tags in the output. Increases response size.

return_html: typing.Optional[bool] — ⚠️ DEPRECATED — Use extensions.altOutputs.returnHtml instead. Whether to include HTML representation alongside markdown in the response.

thinking: typing.Optional[bool] — (Deprecated) Enables expanded rationale output for debugging.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.extract_async(...) -> AsyncSubmissionResponse

📝 Description

Deprecated: Use /extract with async: true instead.

Starts an asynchronous extraction job. The request mirrors the synchronous options but returns immediately with a job identifier that clients can poll for completion status.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.extract_async(
    file="example_file",
)

⚙️ Parameters

file: typing.Optional[core.File] — Document to upload directly. Required unless fileUrl is provided.

file_url: typing.Optional[str] — Public or pre-signed URL that Pulse will download and extract. Required unless file is provided.

model: typing.Optional[ExtractAsyncRequestModel] — Extraction model to use. When set to pulse-ultra-2, routes the request through Pulse Ultra 2 (self-hosted VPC model) instead of the default cloud-based service. If omitted or set to default, the default model is used.

extraction_config_id: typing.Optional[str] — UUID of a saved extraction configuration (a "preset"). When provided, the server loads the saved configuration and applies its options on top of any inline parameters supplied in this request. Inline parameters always take precedence over preset values for the same field. Saved configs are managed via the platform UI or the input_extractions admin endpoints.

pages: typing.Optional[str] — Page range filter supporting segments such as 1-2 or mixed ranges like 1-2,5.

figure_processing: typing.Optional[ExtractAsyncRequestFigureProcessing] — Settings that control how figures and embedded visuals are processed. Applies to both PDFs/images (where figures are detected from layout) and spreadsheets (where charts and embedded images are read directly from the workbook). These options affect the markdown output and the bounding_boxes.Images[] array; they do not produce additional output fields elsewhere in the response.

extensions: typing.Optional[ExtractAsyncRequestExtensions] — Settings that enable additional processing passes or alternate output formats. Each enabled extension produces a corresponding output field under response.extensions.*.

spreadsheet: typing.Optional[ExtractAsyncRequestSpreadsheet] — Settings for Excel/spreadsheet extraction. Controls handling of hidden rows, columns, and sheets, whether numeric cells are rendered using their display format or underlying raw value, and optional trimming of empty phantom rows/columns past the last data-bearing cell. Applies to .xlsx, .xlsm, and .xls files. Accepts both camelCase and snake_case field names.

storage: typing.Optional[ExtractAsyncRequestStorage] — Options for persisting extraction artifacts. When enabled (default), artifacts are saved to storage and a database record is created.

async: typing.Optional[bool] — If true, returns immediately with a job_id for polling via GET /job/{jobId}. Otherwise processes synchronously.

structured_output: typing.Optional[ExtractAsyncRequestStructuredOutput] — ⚠️ DEPRECATED — Use the /schema endpoint after extraction instead. Pass the extraction_id from the extract response to /schema with your schema_config. This parameter still works for backward compatibility but will be removed in a future version.

schema: typing.Optional[ExtractAsyncRequestSchema] — (Deprecated) JSON schema describing structured data to extract. Use structuredOutput instead. Accepts either a JSON object or a stringified JSON representation.

schema_prompt: typing.Optional[str] — (Deprecated) Natural language prompt for schema-guided extraction. Use structuredOutput.schemaPrompt instead.

custom_prompt: typing.Optional[str] — (Deprecated) Custom instructions that augment the default extraction behaviour. Use figureProcessing or extensions instead.

chunking: typing.Optional[str] — ⚠️ DEPRECATED — Use extensions.chunking.chunkTypes instead. Comma-separated list of chunking strategies to apply (for example semantic,header,page,recursive). Still accepted for backward compatibility.

chunk_size: typing.Optional[int] — ⚠️ DEPRECATED — Use extensions.chunking.chunkSize instead. Override for maximum characters per chunk when chunking is enabled.

extract_figure: typing.Optional[bool] — ⚠️ DEPRECATED — Toggle to enable figure extraction in results.

figure_description: typing.Optional[bool] — ⚠️ DEPRECATED — Use figureProcessing.description instead. Toggle to generate descriptive captions for extracted figures.

show_images: typing.Optional[bool] — ⚠️ DEPRECATED — Use figureProcessing.showImages instead. Embed base64-encoded images inline in figure tags in the output. Increases response size.

return_html: typing.Optional[bool] — ⚠️ DEPRECATED — Use extensions.altOutputs.returnHtml instead. Whether to include HTML representation alongside markdown in the response.

thinking: typing.Optional[bool] — (Deprecated) Enables expanded rationale output for debugging.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.split(...) -> SplitResponse

📝 Description

Identify which pages of a document contain each topic/section. Takes an existing extraction and a list of topics, then uses AI to identify which PDF pages contain content related to each topic.

The result is persisted with a split_id that can be used with the /schema endpoint (split mode) for targeted schema extraction on specific page groups.

Set async: true to return immediately with a job_id for polling.

To split many extractions at once, see Batch Split or the Batch Processing guide.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.split(
    extraction_id="extraction_id",
)

⚙️ Parameters

extraction_id: str — ID of the saved extraction to split.

split_config: typing.Optional[SplitConfig] — Inline split configuration with topics. Required if split_config_id is not provided.

split_config_id: typing.Optional[str] — Reference to a saved split configuration. Use this instead of providing split_config inline.

async: typing.Optional[bool] — If true, returns immediately with a job_id for polling via GET /job/{jobId}. Otherwise processes synchronously.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.schema(...) -> SchemaResponse

📝 Description

Apply schema extraction to a previously saved extraction. The mode is inferred from the input:

Single mode — Provide extraction_id + schema_config (or schema_config_id) to apply one schema to the entire document.

Multi-extraction mode — Provide a batch extract ID as extraction_id (auto-detected) or an explicit extraction_ids list. The content from all extractions is combined and the schema is applied to the composite. Citations use extraction_id-bb_id format to disambiguate across source documents.

Split mode — Provide split_id + split_schema_config to apply different schemas to different page groups from a prior /split call. Each topic can have its own schema, prompt, and effort setting.

Creates a versioned schema record that can be retrieved later. Set async: true to return immediately with a job_id for polling.

To apply schemas across many extractions or splits at once, see Batch Schema or the Batch Processing guide.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.schema()

⚙️ Parameters

extraction_id: typing.Optional[str] — ID of a saved extraction OR a batch extract job. When a batch extract ID is provided, the system auto-detects it and combines all completed child extractions into a single schema application.

extraction_ids: typing.Optional[typing.List[str]] — Explicit list of extraction IDs to combine. The markdown and bounding boxes from all extractions are merged and the schema is applied to the composite content. Citations use extraction_id-bb_id format to disambiguate across source documents.

split_id: typing.Optional[str] — ID of saved split (from a prior /split call). Use for split-mode schema extraction.

schema_config: typing.Optional[SchemaConfig] — Inline schema configuration for single mode. Required (with extraction_id) if schema_config_id is not provided.

schema_config_id: typing.Optional[str] — Reference to a saved schema configuration for single mode. Use this instead of providing schema_config inline.

split_schema_config: typing.Optional[typing.Dict[str, TopicSchemaConfig]] — Per-topic schema configurations for split mode. Keys must match the topic names from the split. Each topic provides either inline schema or schema_config_id.

async: typing.Optional[bool] — If true, returns immediately with a job_id for polling via GET /job/{jobId}. Otherwise processes synchronously.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.tables(...) -> TablesResponse

📝 Description

Extract tables from a previously completed extraction. Processes the extraction's document content and returns structured table data.

Requires the tables_endpoint feature flag to be enabled for your organization.

Set async: true to return immediately with a tables_id for polling via GET /job/{tables_id}.

To extract tables from many extractions at once, see Batch Tables or the Batch Processing guide.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.tables(
    extraction_id="extraction_id",
)

⚙️ Parameters

extraction_id: str — ID of a completed extraction to extract tables from.

tables_config: typing.Optional[TablesConfig] — Table extraction configuration. If omitted, defaults are used (merge: false, table_format: "html").

async: typing.Optional[bool] — When true, returns immediately with a job ID. Poll GET /job/{tables_id} for the result.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Form

client.form.detect(...) -> FormResult

📝 Description

Run cell detection on a PDF and return the detected form_fields along with a reusable form_id. No LLM matching, no fill, no clear — this is the OCR / layout step that /form/fill and /form/clear would otherwise run internally.

The returned form_id references the uploaded PDF and its detected layout, and can be passed back to a subsequent /form/fill, /form/clear, or /form/detect call as the single input source — Pulse will skip detection on the fast path and reuse the cached cells.

Input modes — provide exactly one of:

  • form_id — re-detect cells on a previously stored PDF. Useful when callers want to refresh layout after editing or when chaining detect calls.
  • file_url — public or pre-signed URL Pulse will download.
  • file — direct binary upload of the PDF.

All three input modes ride on the same multipart/form-data request body. (Callers sending Content-Type: application/json with form_id / file_url are still accepted server-side for backward compatibility, but the SDKs only model the multipart form.)

Optional page_range (alias pages, e.g. "1-3,5") restricts the operation to a subset of pages.

Synchronous by default — returns the detected layout inline. Set async: true to receive {job_id, status: "pending"} immediately and poll GET /job/{jobId}.

Billed at 1 credit per page. Requires the form_filler feature flag to be enabled for your organization.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.form.detect(
    file="example_file",
)

⚙️ Parameters

file: typing.Optional[core.File] — Direct binary upload of the PDF. Mutually exclusive with file_url and form_id.

file_url: typing.Optional[str] — Public or pre-signed URL of a PDF Pulse will download. Mutually exclusive with file and form_id.

form_id: typing.Optional[str] — Reference to a previously processed form. Mutually exclusive with file / file_url.

page_range: typing.Optional[str] — Restrict the operation to a subset of pages, e.g. "1-3,5".

async: typing.Optional[str] — Set to "true" to run asynchronously and receive {job_id, status} immediately.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.form.fill(...) -> FormResult

📝 Description

Fill the fields of a PDF form with values inferred from a natural language instructions prompt. Works on both AcroForm PDFs (true form fields are written) and flat/scanned PDFs (values are rendered as an overlay using detected cells from OCR).

Input modes — provide exactly one of:

  • form_id — reuse a previously processed form from a prior /form/detect, /form/fill, or /form/clear call. Skips re-detection (fast path); the cached form_fields are reused.
  • file_url — public or pre-signed URL of a PDF Pulse will download.
  • file — direct binary upload of the PDF. Pulse runs cell detection internally before filling.

All three input modes ride on the same multipart/form-data request body. (Callers sending Content-Type: application/json with form_id / file_url are still accepted server-side for backward compatibility, but the SDKs only model the multipart form.)

Optional form_fields lets callers supply or edit the detected cells before filling. Optional page_range (alias pages, e.g. "1-3,5") restricts the operation to a subset of pages.

Synchronous by default — returns the filled FormResult inline (including a pdf_url you can GET to download the PDF binary). Set async: true to receive {job_id, status: "pending"} and poll GET /job/{jobId}.

Billed at 3 credits per page. Requires the form_filler feature flag to be enabled for your organization.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.form.fill(
    file="example_file",
    instructions="instructions",
)

⚙️ Parameters

instructions: str — Required natural-language fill prompt.

file: typing.Optional[core.File] — Direct binary upload of the PDF. Mutually exclusive with file_url and form_id.

file_url: typing.Optional[str] — Public or pre-signed URL of a PDF Pulse will download. Mutually exclusive with file and form_id.

form_id: typing.Optional[str] — Reference to a previously processed form. Mutually exclusive with file / file_url.

form_fields: typing.Optional[str] — Optional JSON-encoded array of FormCell objects to override detected cells. Multipart bodies must serialise this field as a string.

page_range: typing.Optional[str] — Restrict the operation to a subset of pages, e.g. "1-3,5".

async: typing.Optional[str] — Set to "true" to run asynchronously and receive {job_id, status} immediately.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.form.clear(...) -> FormResult

📝 Description

Remove user-entered data from a PDF form, leaving the blank form template intact. Erases handwritten entries, typed values, and unchecks selected checkboxes — printed labels, field titles, section headers, and other static template content are preserved.

Input modes — provide exactly one of:

  • form_id — reuse a previously processed form from a prior /form/detect, /form/fill, or /form/clear call (fast path; cached layout reused).
  • file_url — public or pre-signed URL of a PDF Pulse will download.
  • file — direct binary upload of the PDF.

All three input modes ride on the same multipart/form-data request body. (Callers sending Content-Type: application/json with form_id / file_url are still accepted server-side for backward compatibility, but the SDKs only model the multipart form.)

instructions is optional. When omitted, Pulse clears every user-filled field deterministically (no LLM call) on AcroForm PDFs, eliminating any chance of hallucinated content. Provide a natural language prompt to clear only specific fields (e.g. "clear only the address fields"); targeted clears go through the LLM matcher with a delete-only filter.

Optional form_fields and page_range (alias pages) behave the same as on Form Fill.

Synchronous by default — returns the cleared FormResult inline (including a pdf_url you can GET to download the PDF binary). Set async: true to receive {job_id, status: "pending"} and poll GET /job/{jobId}.

Billed at 3 credits per page. Requires the form_filler feature flag to be enabled for your organization.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.form.clear(
    file="example_file",
)

⚙️ Parameters

file: typing.Optional[core.File] — Direct binary upload of the PDF. Mutually exclusive with file_url and form_id.

file_url: typing.Optional[str] — Public or pre-signed URL of a PDF Pulse will download. Mutually exclusive with file and form_id.

form_id: typing.Optional[str] — Reference to a previously processed form. Mutually exclusive with file / file_url.

instructions: typing.Optional[str] — Optional natural language description of what to clear. When omitted, Pulse clears everything user-filled deterministically.

form_fields: typing.Optional[str] — Optional JSON-encoded array of FormCell objects to override detected cells. Multipart bodies must serialise this field as a string.

page_range: typing.Optional[str] — Restrict the operation to a subset of pages, e.g. "1-3,5".

async: typing.Optional[str] — Set to "true" to run asynchronously and receive {job_id, status} immediately.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Batch

client.batch.extract(...) -> BatchExtractResponse

📝 Description

Process multiple files in parallel. Enumerates files from an input source (S3 prefix, local directory, or URL list), calls Extract for each file, and saves results to an output destination.

Always asynchronous — returns a batch job ID immediately. Poll GET /job/{jobId} for real-time progress including per-file completion status.

See the Extract endpoint for details on extract_options and the Batch Processing guide for an overview of the batch pipeline.

🔌 Usage

from pulse import Pulse, BatchInputSource, BatchOutputDestination
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.batch.extract(
    input=BatchInputSource(),
    output=BatchOutputDestination(),
)

⚙️ Parameters

input: BatchInputSource — Source of files to process.

output: BatchOutputDestination — Where to save extraction result JSON files.

extract_options: typing.Optional[typing.Dict[str, typing.Any]] — Options forwarded to each /extract call (e.g. pages, figureProcessing, extensions).

workers: typing.Optional[int] — Number of parallel workers. Higher values increase throughput but consume more server resources.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch.schema(...) -> BatchSchemaResponse

📝 Description

Apply schema extraction to multiple items in parallel. Mode is inferred from the input:

Single mode — Provide extraction_ids or batch_extract_id with schema_config to apply one schema to each extraction.

Split mode — Provide split_ids or batch_split_id with split_schema_config to apply per-topic schemas to each split.

Each child call goes through the full Schema code path. Poll GET /job/{jobId} for real-time progress.

See the Schema endpoint for details on schema_config and split_schema_config, and the Batch Processing guide for an overview of the batch pipeline.

🔌 Usage

from pulse import Pulse, BatchOutputDestination
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.batch.schema(
    output=BatchOutputDestination(),
)

⚙️ Parameters

output: BatchOutputDestination — Where to save schema result JSON files.

batch_extract_id: typing.Optional[str] — ID of a prior /batch/extract run (single mode).

extraction_ids: typing.Optional[typing.List[str]] — Explicit list of extraction IDs (single mode).

batch_split_id: typing.Optional[str] — ID of a prior /batch/split run (split mode).

split_ids: typing.Optional[typing.List[str]] — Explicit list of split IDs (split mode).

schema_config: typing.Optional[SchemaConfig] — Schema configuration for single mode. Applied to each extraction.

split_schema_config: typing.Optional[typing.Dict[str, TopicSchemaConfig]] — Per-topic schema configurations for split mode. Keys must match the topic names from the splits.

page_range: typing.Optional[str] — Page range filter for single mode (e.g. 1-5,10).

workers: typing.Optional[int] — Number of parallel workers.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch.tables(...) -> BatchTablesResponse

📝 Description

Extract tables from multiple existing extractions in parallel. Each child call goes through the full Tables code path.

Extractions are identified by either a batch_extract_id (from a prior Batch Extract run) or an explicit list of extraction_ids.

Poll GET /job/{jobId} for real-time progress.

See the Tables endpoint for details on tables_config and the Batch Processing guide for an overview of the batch pipeline.

🔌 Usage

from pulse import Pulse, BatchOutputDestination
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.batch.tables(
    output=BatchOutputDestination(),
)

⚙️ Parameters

output: BatchOutputDestination — Where to save table result JSON files.

batch_extract_id: typing.Optional[str] — ID of a prior /batch/extract run. All completed child extraction IDs will be used.

extraction_ids: typing.Optional[typing.List[str]] — Explicit list of extraction IDs to process.

tables_config: typing.Optional[TablesConfig] — Table extraction configuration forwarded to each /tables call.

workers: typing.Optional[int] — Number of parallel workers.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.batch.split(...) -> BatchSplitResponse

📝 Description

Split multiple existing extractions by topics in parallel. Each child call goes through the full Split code path.

Extractions are identified by either a batch_extract_id (from a prior Batch Extract run) or an explicit list of extraction_ids.

Poll GET /job/{jobId} for real-time progress.

See the Split endpoint for details on split_config and the Batch Processing guide for an overview of the batch pipeline.

🔌 Usage

from pulse import Pulse, BatchOutputDestination, SplitConfig, TopicDefinition
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.batch.split(
    output=BatchOutputDestination(),
    split_config=SplitConfig(
        split_input=[
            TopicDefinition(
                name="name",
            )
        ],
    ),
)

⚙️ Parameters

output: BatchOutputDestination — Where to save split result JSON files.

split_config: SplitConfig — Split configuration with topic definitions. Applied to each extraction.

batch_extract_id: typing.Optional[str] — ID of a prior /batch/extract run. All completed child extraction IDs will be used.

extraction_ids: typing.Optional[typing.List[str]] — Explicit list of extraction IDs to process.

workers: typing.Optional[int] — Number of parallel workers.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Pipeline

client.pipeline.execute(...) -> PipelineExecuteResponse

📝 Description

Chain multiple processing steps (extract, schema, split, tables) into a single request with inline configurations. No saved pipeline required.

The steps object defines what to run and in what order. Outputs flow forward automatically — you never need to pass extraction IDs between steps.

Supported step combinations:

  • extract — extract a single document
  • extract → schema — extract then apply structured schema
  • extract → split — extract then split into topics
  • extract → split → schema — extract, split by topic, apply per-topic schemas
  • extract → tables — extract then extract structured tables
  • batch_extract → schema — extract multiple files, combine into one schema output

Document input:

  • Single file: provide fileUrl in JSON or file via multipart
  • Multiple files (batch_extract): provide fileUrls in JSON or multiple file fields via multipart

Set async: true to return immediately with a job_id for polling via GET /job/{jobId}.

Set autoDelete: true for zero-retention mode — all stored artifacts are deleted immediately after you receive the results. Requires save_extractions to be disabled for your organization.

Requires the enable_adhoc_pipeline feature flag.

🔌 Usage

from pulse import Pulse, PipelineSteps
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.pipeline.execute(
    steps=PipelineSteps(),
)

⚙️ Parameters

steps: PipelineSteps — Ordered step definitions. Key order determines execution order.

file_url: typing.Optional[str] — URL of the document to process. Use with extract step.

async: typing.Optional[bool] — If true, returns immediately with a job_id for polling via GET /job/{jobId}.

auto_delete: typing.Optional[bool] — If true, all stored artifacts are deleted immediately after you receive the results. The inline data in the response is unaffected. Requires save_extractions to be disabled for your organization.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Jobs

client.jobs.get_job(...) -> JobStatusResponse

📝 Description

Check the status and retrieve results of an asynchronous job (submitted via any endpoint with async: true).

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.jobs.get_job(
    job_id="jobId",
)

⚙️ Parameters

job_id: str — Identifier returned from an async job submission.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.jobs.cancel_job(...) -> JobCancellationResponse

📝 Description

Attempts to cancel an asynchronous job that is currently pending or processing. Jobs that have already completed will remain unchanged.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.jobs.cancel_job(
    job_id="jobId",
)

⚙️ Parameters

job_id: str — Identifier returned from an async job submission.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Results

client.results.get_pdf(...) -> typing.Iterator[bytes]

📝 Description

Download the PDF binary produced by a /form/detect, /form/fill, or /form/clear job. The pdf_url field on a FormResult points at this endpoint — you can hand it directly to a browser, embed it in an <iframe>, or fetch the bytes from a backend.

Returns 404 for non-form jobs (no PDF was produced) and for form jobs whose PDF artifact is no longer available.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.results.get_pdf(
    job_id="jobId",
)

⚙️ Parameters

job_id: str — Job identifier from a form endpoint.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

client.results.get_image(...) -> typing.Iterator[bytes]

📝 Description

Stream a PNG/JPEG visual image referenced by an extraction response under bounding_boxes.Images[].image_url.

The URL is API-hosted instead of raw S3 — the underlying object store is intentionally not part of the public contract. The host in image_url mirrors the request origin (e.g. a request to a beta deployment returns image URLs on that same host).

Authentication is required. Unlike the legacy single-use /large_results/{jobId} route, visual artifacts are independently-addressable resources — every fetch must present a valid API key for the owning org. There is no anonymous / TTL-based fallback. Use the same x-api-key header you use for /extract.

Fetching an image does not consume the parent extraction's result-delivery slot, so one extraction can produce many image URLs and each can be fetched repeatedly while the artifact is retained.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.results.get_image(
    job_id="jobId",
    filename="filename",
)

⚙️ Parameters

job_id: str — Job identifier — same value used in the image_url returned from /extract.

filename: str — Visual filename — e.g. excel_image_1_1.png. Must be the exact filename segment from the image_url.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

LargeResults

client.large_results.get_large_result(...) -> ExtractResultCore

📝 Description

Download the full result for a large extraction. When /extract or GET /job/{jobId} returns is_url: true, fetch the complete result from the URL provided. The URL is single-use: after a successful download the resource is deleted and subsequent requests return 410 Gone.

For form jobs (/form/detect, /form/fill, /form/clear) you don't need this endpoint at all — GET /job/{jobId} already returns the full FormResult inline under result, and the pdf_url field points at GET /results/{jobId}/pdf for the binary.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.large_results.get_large_result(
    job_id="jobId",
)

⚙️ Parameters

job_id: str — Job identifier from the extraction response.

request_options: typing.Optional[RequestOptions] — Request-specific configuration.

Webhooks

client.webhooks.create_webhook_link() -> CreateWebhookLinkResponse

📝 Description

Generates a temporary link to the Svix webhook portal where users can manage their webhook endpoints and view message logs.

🔌 Usage

from pulse import Pulse
from pulse.environment import PulseEnvironment

client = Pulse(
    api_key="<value>",
    environment=PulseEnvironment.DEFAULT,
)

client.webhooks.create_webhook_link()

⚙️ Parameters

request_options: typing.Optional[RequestOptions] — Request-specific configuration.