from retab import Retab
from pathlib import Path
client = Retab()
# Create an upload session for a local file.
invoice_path = Path("invoice.pdf")
session = client.files.create_upload(
filename=invoice_path.name,
size_bytes=invoice_path.stat().st_size,
content_type="application/pdf",
)
mime_data = session.mime_data
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const mimeData = await client.files.complete_upload((await client.files.create_upload("invoice.pdf", 1024, "application/pdf")).fileId);
console.log(`Filename: ${mimeData.filename}`);
console.log(`URL: ${mimeData.url}`);
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)
}
session, err := client.Files.CreateUpload(ctx, &retab.FilesCreateUploadParams{
Filename: "invoice.pdf",
ContentType: ptr("application/pdf"),
SizeBytes: 1024,
})
if err != nil {
log.Fatal(err)
}
mimeData := session.MIMEData
fmt.Printf("Filename: %s\n", mimeData.Filename)
fmt.Printf("URL: %s\n", mimeData.URL)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
bytes = File.binread('invoice.pdf')
session = client.files.create_upload(
filename: 'invoice.pdf',
size_bytes: bytes.bytesize,
content_type: 'application/pdf',
)
puts "Filename: #{session.mime_data.filename}"
puts "URL: #{session.mime_data.url}"
use retab::models::UploadFileRequest;
use retab::resources::files::CreateUploadParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let bytes = std::fs::read("invoice.pdf")?;
let session = client
.files()
.create_upload(CreateUploadParams::new(UploadFileRequest {
filename: "invoice.pdf".into(),
content_type: Some("application/pdf".into()),
size_bytes: bytes.len() as i64,
sha_256: None,
}))
.await?;
let mime_data = session.mime_data.expect("upload session should include mime data");
println!("Filename: {}", mime_data.filename);
println!("URL: {}", mime_data.url);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->files()->createUpload(
filename: 'value',
sizeBytes: 10,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Files.CreateUploadAsync(
new FilesCreateUploadOptions
{
Filename = "invoice.pdf",
ContentType = "application/pdf",
SizeBytes = 12345,
}
);
Console.WriteLine(result);
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.files().createUpload("invoice.pdf", "application/pdf", 10L, "abc123");
System.out.println(result);
}
}
SESSION=$(curl -s -X POST \
'https://api.retab.com/v1/files/upload' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size_bytes": 12345
}')
UPLOAD_URL=$(echo "$SESSION" | jq -r '.uploadUrl')
FILE_ID=$(echo "$SESSION" | jq -r '.fileId')
curl -X PUT "$UPLOAD_URL" \
-H 'Content-Type: application/pdf' \
--data-binary '@invoice.pdf'
curl -X POST \
"https://api.retab.com/v1/files/upload/$FILE_ID/complete" \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
{
"fileId": "file_a1b2c3d4e5f6",
"uploadUrl": "https://storage.googleapis.com/...",
"uploadMethod": "PUT",
"uploadHeaders": {
"Content-Type": "application/pdf"
},
"mimeData": {
"filename": "invoice.pdf",
"url": "https://storage.retab.com/file_a1b2c3d4e5f6"
},
"expiresAt": "2026-04-24T12:00:00Z"
}
Upload
Upload File
Start a file upload.
Reserves a file record for the given filename, content_type, and
size_bytes, and returns a short-lived signed upload_url the client uses
to PUT the file content directly. Call the complete-upload endpoint with
the returned file_id once the bytes have been uploaded.
POST
/
v1
/
files
/
upload
from retab import Retab
from pathlib import Path
client = Retab()
# Create an upload session for a local file.
invoice_path = Path("invoice.pdf")
session = client.files.create_upload(
filename=invoice_path.name,
size_bytes=invoice_path.stat().st_size,
content_type="application/pdf",
)
mime_data = session.mime_data
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const mimeData = await client.files.complete_upload((await client.files.create_upload("invoice.pdf", 1024, "application/pdf")).fileId);
console.log(`Filename: ${mimeData.filename}`);
console.log(`URL: ${mimeData.url}`);
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)
}
session, err := client.Files.CreateUpload(ctx, &retab.FilesCreateUploadParams{
Filename: "invoice.pdf",
ContentType: ptr("application/pdf"),
SizeBytes: 1024,
})
if err != nil {
log.Fatal(err)
}
mimeData := session.MIMEData
fmt.Printf("Filename: %s\n", mimeData.Filename)
fmt.Printf("URL: %s\n", mimeData.URL)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
bytes = File.binread('invoice.pdf')
session = client.files.create_upload(
filename: 'invoice.pdf',
size_bytes: bytes.bytesize,
content_type: 'application/pdf',
)
puts "Filename: #{session.mime_data.filename}"
puts "URL: #{session.mime_data.url}"
use retab::models::UploadFileRequest;
use retab::resources::files::CreateUploadParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let bytes = std::fs::read("invoice.pdf")?;
let session = client
.files()
.create_upload(CreateUploadParams::new(UploadFileRequest {
filename: "invoice.pdf".into(),
content_type: Some("application/pdf".into()),
size_bytes: bytes.len() as i64,
sha_256: None,
}))
.await?;
let mime_data = session.mime_data.expect("upload session should include mime data");
println!("Filename: {}", mime_data.filename);
println!("URL: {}", mime_data.url);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->files()->createUpload(
filename: 'value',
sizeBytes: 10,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Files.CreateUploadAsync(
new FilesCreateUploadOptions
{
Filename = "invoice.pdf",
ContentType = "application/pdf",
SizeBytes = 12345,
}
);
Console.WriteLine(result);
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.files().createUpload("invoice.pdf", "application/pdf", 10L, "abc123");
System.out.println(result);
}
}
SESSION=$(curl -s -X POST \
'https://api.retab.com/v1/files/upload' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size_bytes": 12345
}')
UPLOAD_URL=$(echo "$SESSION" | jq -r '.uploadUrl')
FILE_ID=$(echo "$SESSION" | jq -r '.fileId')
curl -X PUT "$UPLOAD_URL" \
-H 'Content-Type: application/pdf' \
--data-binary '@invoice.pdf'
curl -X POST \
"https://api.retab.com/v1/files/upload/$FILE_ID/complete" \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
{
"fileId": "file_a1b2c3d4e5f6",
"uploadUrl": "https://storage.googleapis.com/...",
"uploadMethod": "PUT",
"uploadHeaders": {
"Content-Type": "application/pdf"
},
"mimeData": {
"filename": "invoice.pdf",
"url": "https://storage.retab.com/file_a1b2c3d4e5f6"
},
"expiresAt": "2026-04-24T12:00:00Z"
}
Create a direct-to-storage upload session. Upload the file bytes to the returned signed
Signed object-storage URLs are bearer URLs controlled by you; keep them time-limited and scoped to the single document being processed.
uploadUrl, then call POST /v1/files/upload/{file_id}/complete. The completed file is returned as MIMEData and can be passed directly to extractions, workflows, and other operations.
from retab import Retab
from pathlib import Path
client = Retab()
# Create an upload session for a local file.
invoice_path = Path("invoice.pdf")
session = client.files.create_upload(
filename=invoice_path.name,
size_bytes=invoice_path.stat().st_size,
content_type="application/pdf",
)
mime_data = session.mime_data
print(f"Filename: {mime_data.filename}")
print(f"URL: {mime_data.url}")
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const mimeData = await client.files.complete_upload((await client.files.create_upload("invoice.pdf", 1024, "application/pdf")).fileId);
console.log(`Filename: ${mimeData.filename}`);
console.log(`URL: ${mimeData.url}`);
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)
}
session, err := client.Files.CreateUpload(ctx, &retab.FilesCreateUploadParams{
Filename: "invoice.pdf",
ContentType: ptr("application/pdf"),
SizeBytes: 1024,
})
if err != nil {
log.Fatal(err)
}
mimeData := session.MIMEData
fmt.Printf("Filename: %s\n", mimeData.Filename)
fmt.Printf("URL: %s\n", mimeData.URL)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
bytes = File.binread('invoice.pdf')
session = client.files.create_upload(
filename: 'invoice.pdf',
size_bytes: bytes.bytesize,
content_type: 'application/pdf',
)
puts "Filename: #{session.mime_data.filename}"
puts "URL: #{session.mime_data.url}"
use retab::models::UploadFileRequest;
use retab::resources::files::CreateUploadParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let bytes = std::fs::read("invoice.pdf")?;
let session = client
.files()
.create_upload(CreateUploadParams::new(UploadFileRequest {
filename: "invoice.pdf".into(),
content_type: Some("application/pdf".into()),
size_bytes: bytes.len() as i64,
sha_256: None,
}))
.await?;
let mime_data = session.mime_data.expect("upload session should include mime data");
println!("Filename: {}", mime_data.filename);
println!("URL: {}", mime_data.url);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$result = $client->files()->createUpload(
filename: 'value',
sizeBytes: 10,
);
print_r($result);
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Files.CreateUploadAsync(
new FilesCreateUploadOptions
{
Filename = "invoice.pdf",
ContentType = "application/pdf",
SizeBytes = 12345,
}
);
Console.WriteLine(result);
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.files().createUpload("invoice.pdf", "application/pdf", 10L, "abc123");
System.out.println(result);
}
}
SESSION=$(curl -s -X POST \
'https://api.retab.com/v1/files/upload' \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size_bytes": 12345
}')
UPLOAD_URL=$(echo "$SESSION" | jq -r '.uploadUrl')
FILE_ID=$(echo "$SESSION" | jq -r '.fileId')
curl -X PUT "$UPLOAD_URL" \
-H 'Content-Type: application/pdf' \
--data-binary '@invoice.pdf'
curl -X POST \
"https://api.retab.com/v1/files/upload/$FILE_ID/complete" \
-H "Authorization: Bearer $RETAB_API_KEY" \
-H 'Content-Type: application/json' \
-d '{}'
{
"fileId": "file_a1b2c3d4e5f6",
"uploadUrl": "https://storage.googleapis.com/...",
"uploadMethod": "PUT",
"uploadHeaders": {
"Content-Type": "application/pdf"
},
"mimeData": {
"filename": "invoice.pdf",
"url": "https://storage.retab.com/file_a1b2c3d4e5f6"
},
"expiresAt": "2026-04-24T12:00:00Z"
}
Use the uploaded file in later requests
For large documents, prefer an object-storage URL first. Retab fetches the file server-side, avoiding inline/base64 request bodies that can trigger413 Request Entity Too Large. Use a time-limited signed URL when the object is private.
Supported remote URL hosts include Azure Blob Storage (*.blob.core.windows.net), Google Cloud Storage (storage.googleapis.com), Amazon S3 (amazonaws.com), and Cloudflare R2 (*.r2.cloudflarestorage.com and *.r2.dev). Custom domains are not fetched by default; contact support if you need one allowlisted.
If you do not have an object-storage URL available, upload the file to Retab first. The SDK returns a durable MIMEData reference. You can pass that object directly, or pass its Retab storage URL.
from retab import Retab
client = Retab(api_key="YOUR_RETAB_API_KEY")
schema = {
"type": "object",
"properties": {
"invoice_number": {"type": "string"},
"total_amount": {"type": "number"},
},
}
# Option 1: object-storage URL
azure_blob_url = "https://<account>.blob.core.windows.net/<container>/large_document.pdf?<sas_token>"
extraction = client.extractions.create(
document=azure_blob_url,
model="retab-small",
json_schema=schema,
)
# Option 2: Retab upload session, then reuse the returned URL
session = client.files.create_upload(
filename="large_document.pdf",
size_bytes=12345,
content_type="application/pdf",
)
mime_ref = session.mime_data
extraction = client.extractions.create(
document=mime_ref.url,
model="retab-small",
json_schema=schema,
)
# This also works:
extraction = client.extractions.create(
document=mime_ref,
model="retab-small",
json_schema=schema,
)
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const schema = {
type: "object",
properties: {
invoice_number: { type: "string" },
total_amount: { type: "number" },
},
};
// Option 1: object-storage URL
const cloudflareR2Url = "https://<public-id>.r2.dev/large_document.pdf";
const extractionFromR2 = await client.extractions.create(cloudflareR2Url, schema, "retab-small");
// Option 2: Retab upload, then reuse the returned URL
const mimeRef = await client.files.complete_upload((await client.files.create_upload("large_document.pdf", 1024, "application/pdf")).fileId);
const extraction = await client.extractions.create(mimeRef.url, schema, "retab-small");
// This also works:
const sameExtraction = await client.extractions.create(mimeRef, schema, "retab-small");
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("YOUR_RETAB_API_KEY")
if err != nil {
log.Fatal(err)
}
schema := map[string]any{
"type": "object",
"properties": map[string]any{
"invoice_number": map[string]any{"type": "string"},
"total_amount": map[string]any{"type": "number"},
},
}
// Option 1: object-storage URL
cloudflareR2URL := "https://<public-id>.r2.dev/large_document.pdf"
extractionFromR2, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: cloudflareR2URL,
Model: ptr("retab-small"),
JSONSchema: schema,
})
if err != nil {
log.Fatal(err)
}
_ = extractionFromR2
// Option 2: Retab upload, then reuse the returned URL
session, err := client.Files.CreateUpload(ctx, &retab.FilesCreateUploadParams{
Filename: "large_document.pdf",
ContentType: ptr("application/pdf"),
SizeBytes: 1024,
})
if err != nil {
log.Fatal(err)
}
mimeRef := session.MIMEData
extraction, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: mimeRef.URL,
Model: ptr("retab-small"),
JSONSchema: schema,
})
if err != nil {
log.Fatal(err)
}
// This also works:
sameExtraction, err := client.Extractions.Create(ctx, &retab.ExtractionsCreateParams{
Document: mimeRef,
Model: ptr("retab-small"),
JSONSchema: schema,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(extraction.ID, sameExtraction.ID)
}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
schema = {
'type' => 'object',
'properties' => {
'invoice_number' => { 'type' => 'string' },
'total_amount' => { 'type' => 'number' },
},
}
# Option 1: object-storage URL
azure_blob_url = 'https://<account>.blob.core.windows.net/<container>/large_document.pdf?<sas_token>'
extraction = client.extractions.create(
document: azure_blob_url,
model: 'retab-small',
json_schema: schema,
)
# Option 2: Retab upload, then reuse the returned MimeData
file_bytes = File.binread('large_document.pdf')
upload = client.files.create_upload(
filename: 'large_document.pdf',
size_bytes: file_bytes.bytesize,
content_type: 'application/pdf',
)
# PUT the file bytes to upload.upload_url, then finalize:
mime_ref = client.files.complete_upload(file_id: upload.id)
extraction = client.extractions.create(
document: mime_ref,
model: 'retab-small',
json_schema: schema,
)
use retab::resources::extractions::CreateParams;
use retab::Retab;
use serde_json::json;
use std::collections::HashMap;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let schema = HashMap::from([
("type".to_string(), json!("object")),
("properties".to_string(), json!({
"invoice_number": { "type": "string" },
"total_amount": { "type": "number" }
})),
]);
let url = "https://<public-id>.r2.dev/large_document.pdf";
let mut params = CreateParams::new(url, schema);
params.body.model = Some("retab-small".into());
let extraction = client.extractions().create(params).await?;
println!("{:?}", extraction.id);
Ok(())
}
<?php
require 'vendor/autoload.php';
use Retab\Client;
$client = new Client(apiKey: getenv('RETAB_API_KEY'));
$schema = [
'type' => 'object',
'properties' => [
'invoice_number' => ['type' => 'string'],
'total_amount' => ['type' => 'number'],
],
];
$extraction = $client->extractions()->create(
document: 'https://<public-id>.r2.dev/large_document.pdf',
jsonSchema: $schema,
model: 'retab-small',
);
print_r($extraction);
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var extraction = await client.Extractions.CreateAsync(
new ExtractionsCreateOptions
{
Document = MimeData.FromUrl(new Uri("https://<public-id>.r2.dev/large_document.pdf")),
JsonSchema = new Dictionary<string, object>
{
["type"] = "object",
["properties"] = new Dictionary<string, object>
{
["invoice_number"] = new Dictionary<string, object> { ["type"] = "string" },
["total_amount"] = new Dictionary<string, object> { ["type"] = "number" },
},
},
Model = "retab-small",
}
);
Console.WriteLine(extraction.Id);
import com.retab.RetabClient;
public final class Example {
public static void main(String[] args) throws Exception {
RetabClient client = new RetabClient(System.getenv("RETAB_API_KEY"));
var result = client.files().createUpload("invoice.pdf", "application/pdf", 10L, "abc123");
System.out.println(result);
}
}
https://storage.retab.com/file_... URLs are opaque Retab references, not public download links. Retab resolves them against the authenticated caller’s organization before processing.Authorizations
Body
application/json
Body to start a file upload: the filename, expected size_bytes, and optional content type and checksum.
Response
Successful Response
Instructions for uploading file content to a reserved file record.
Returned when starting a file upload. Carries the new file_id, a
short-lived signed upload_url with the HTTP method and headers to use,
a durable reference to the file, and the URL's expires_at time.