> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retab.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Streaming Extraction
> Run a structured extraction on a document and stream partial results as they are produced.
Run a structured extraction on a document and stream partial results as they are
produced, instead of waiting for the full `Extraction` to be persisted. The
request body is identical to [`POST /v1/extractions`](/api-reference/extractions/create);
the response is a stream of `application/stream+json` chunks, each carrying the
latest partial `output` as the model fills the schema.
```python Python theme={null}
from retab import MIMEData, Retab
client = Retab()
document = MIMEData(
filename="Invoice.pdf",
url="https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
)
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
}
result = client.extractions.create_stream(
document=document,
json_schema=schema,
model="retab-small",
)
print(result)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const document = {
filename: "Invoice.pdf",
url: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
};
const result = await client.extractions.create_stream(
document,
{ type: "object", properties: {} },
"retab-small",
);
console.log(result);
```
```go Go theme={null}
package main
import (
"context"
"fmt"
"log"
retab "github.com/retab-dev/retab/clients/go"
)
func ptr[T any](v T) *T { return &v }
func main() {
ctx := context.Background()
client, err := retab.NewClient("")
if err != nil {
log.Fatal(err)
}
document := retab.MIMEData{
Filename: "Invoice.pdf",
URL: "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
}
if err := client.Extractions.CreateStream(ctx, &retab.ExtractionsCreateStreamParams{
Document: document,
JSONSchema: map[string]any{"type": "object", "properties": map[string]any{}},
Model: ptr("retab-small"),
}); err != nil {
log.Fatal(err)
}
fmt.Println("streaming extraction started")
}
```
```java Java theme={null}
import com.retab.RetabClient;
import com.retab.models.MimeData;
import java.net.URI;
import java.util.List;
import java.util.Map;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
MimeData document =
MimeData.fromUrl(
URI.create("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
Map jsonSchema =
Map.of(
"type", "object",
"properties",
Map.of(
"invoice_number", Map.of("type", "string"),
"total", Map.of("type", "number")),
"required", List.of("invoice_number", "total"));
Object result =
client
.extractions()
.createStream(
document, jsonSchema, "retab-small", null, 1L, Map.of("source", "docs"),
null, null, null, null, null);
System.out.println(result);
}
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
document = {
filename: 'Invoice.pdf',
url: 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
}
schema = {
type: 'object',
properties: {
invoice_number: { type: 'string' },
total: { type: 'number' },
},
required: ['invoice_number', 'total'],
}
result = client.extractions.create_stream(
document: document,
json_schema: schema,
model: 'retab-small',
)
puts result
```
```rust Rust theme={null}
use retab::resources::extractions::CreateStreamParams;
use retab::{MimeData, Retab};
use serde_json::json;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let schema = json!({
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"},
},
"required": ["invoice_number", "total"],
});
let schema_map = schema.as_object().unwrap().clone().into_iter().collect();
let document = MimeData::new(
"Invoice.pdf",
"https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf",
);
let mut params = CreateStreamParams::new(document, schema_map);
params.body.model = Some("retab-small".into());
client.extractions().create_stream(params).await?;
println!("streaming extraction started");
Ok(())
}
```
```php PHP theme={null}
extractions()->createStream(
document: [
'filename' => 'Invoice.pdf',
'url' => 'https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf',
],
jsonSchema: ['type' => 'object', 'properties' => []],
);
print_r($result);
```
```csharp C# theme={null}
using Retab;
using System;
using System.Collections.Generic;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var document = MimeData.FromUrl(
new Uri("https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"));
await client.Extractions.CreateStreamAsync(new ExtractionsCreateStreamOptions
{
Document = document,
JsonSchema = new Dictionary
{
["type"] = "object",
["properties"] = new Dictionary(),
},
Model = "retab-small",
});
Console.WriteLine("streaming extraction started");
```
```curl cURL theme={null}
curl -N -X POST \
'https://api.retab.com/v1/extractions/stream' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/stream+json' \
-d '{
"document": {
"filename": "Invoice.pdf",
"url": "https://my-bucket.s3.us-east-1.amazonaws.com/documents/Invoice.pdf"
},
"model": "retab-small",
"json_schema": {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total": {"type": "number"}
},
"required": ["invoice_number", "total"]
}
}'
```
```json 200 theme={null}
{
"id": "extr_01G34H8J2K",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "Invoice.pdf",
"mime_type": "application/pdf"
},
"model": "retab-small",
"output": {
"invoice_number": "INV-2024-0042",
"total": 1234.56
},
"created_at": "2024-03-15T10:30:00Z"
}
```
## OpenAPI
````yaml POST /v1/extractions/stream
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/extractions/stream:
post:
tags:
- Extractions
summary: Create Extraction Stream
description: >-
Run a structured extraction on a document and stream partial results as
they are produced.
operationId: create_extraction_stream
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateExtractionRequest'
required: true
responses:
'200':
description: Streaming extraction chunks
content:
application/stream+json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
CreateExtractionRequest:
properties:
document:
$ref: '#/components/schemas/MIMEData'
json_schema:
additionalProperties: true
type: object
title: Json Schema
description: JSON schema describing the structured output
model:
type: string
title: Model
description: The model to use for the extraction
default: retab-small
instructions:
anyOf:
- type: string
- type: 'null'
title: Instructions
description: >-
Free-form instructions appended to the system prompt to steer the
extraction.
n_consensus:
type: integer
title: N Consensus
description: >-
Number of consensus extraction runs to perform. Uses deterministic
single-pass when set to 1.
default: 1
metadata:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Metadata
description: User-defined metadata to associate with this extraction
additional_messages:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Additional Messages
description: Additional chat messages forwarded to the extraction model.
bust_cache:
type: boolean
title: Bust Cache
description: If true, skip the LLM cache and force a fresh completion
default: false
stream:
type: boolean
title: Stream
default: false
background:
type: boolean
title: Background
description: >-
If true, run asynchronously: returns immediately with status
'queued' and an empty output. Poll GET /v1//{id} until
status is terminal. Mutually exclusive with stream.
default: false
deep_extraction:
type: boolean
title: Deep Extraction
description: >-
Optimizes for accuracy over latency in documents with very large
arrays.
default: false
type: object
required:
- document
- json_schema
title: CreateExtractionRequest
description: >-
Request to run a structured extraction on a single document.
Extends the base extraction request with the `document` to process
(either
inline content or a reference to a previously uploaded file) and a
`stream`
flag that controls whether results are returned incrementally.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
MIMEData:
properties:
filename:
type: string
title: Filename
description: The filename of the file
examples:
- file.pdf
- image.png
- data.txt
url:
type: string
title: Url
description: The URL of the file in base64 format
examples:
- data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA...
additionalProperties: false
type: object
required:
- filename
- url
title: MIMEData
description: A file represented by its `filename` and a base64 data `url`.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
default: null
ctx:
type: object
title: Context
default: {}
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````