Skip to main content
POST
/
v1
/
files
/
blueprints
from retab import Retab

client = Retab()

blueprint = client.files.create_blueprint(
    file_id="file_a1b2c3d4e5f6",
    mode="reasoning",
    intent="Identify the statement fields and transaction table",
    background=True,
)

print(blueprint.id)

{
  "id": "<string>",
  "file": {
    "id": "<string>",
    "filename": "<string>",
    "mime_type": "<string>"
  },
  "object": "file.blueprint",
  "intent": "<string>",
  "output": {},
  "status": "pending",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "created_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z"
}

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 a document blueprint for an uploaded file. 
from retab import Retab

client = Retab()

blueprint = client.files.create_blueprint(
    file_id="file_a1b2c3d4e5f6",
    mode="reasoning",
    intent="Identify the statement fields and transaction table",
    background=True,
)

print(blueprint.id)

Authorizations

​
Api-Key
string
header
required

Body

application/json

Public create-file-blueprint request body.

​
file_id
string
required

File id to analyze.

​
mode
enum<string> | null

Optional analysis depth override. Omit to let Retab choose.

Available options:
instant,
reasoning
​
intent
string | null

Optional user intent used to guide the blueprint analysis.

​
background
boolean
default:false

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.

Response

Successful Response

A document blueprint generated from an uploaded file.

​
id
string
required

Unique identifier of the file blueprint.

​
file
FileRef · object
required

Information about the analyzed file.

​
object
string
default:file.blueprint
Allowed value: "file.blueprint"
​
mode
enum<string> | null

Analysis depth used or requested.

Available options:
instant,
reasoning
​
intent
string | null

User intent supplied with the blueprint request.

​
output
Output · object

The generated Document Blueprint payload.

​
status
enum<string>
default:pending

Lifecycle status. The synchronous path returns 'completed'. Background runs progress pending -> queued -> in_progress -> completed | failed | cancelled.

Available options:
pending,
queued,
in_progress,
completed,
failed,
cancelled
​
error
PrimitiveError · object

Error details when a background run fails; null otherwise. Always present so consumers can read it without an existence check.

​
created_at
string<date-time> | null
​
started_at
string<date-time> | null
​
completed_at
string<date-time> | null