> ## 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.
# List Edits
> List edits.
Returns a paginated list of edits. Filter by `filename` (case-insensitive
prefix match), `template_id`, and a `from_date`/`to_date` creation range
(each `YYYY-MM-DD`). Page with `before`/`after` cursors, `limit`, and
`order`; an invalid date format responds with `400`.
List persisted edits for your organization, with id-based pagination and optional template filtering.
```python Python theme={null}
from retab import Retab
client = Retab()
edits = client.edits.list(limit=20, order="desc")
for edit in edits.data:
print(f"{edit.id}: {edit.file.filename}")
# Filter by template
edits = client.edits.list(template_id="edittplt_abc123", limit=50)
```
```typescript TypeScript theme={null}
import { Retab } from "@retab/node";
const client = new Retab({ apiKey: process.env.RETAB_API_KEY });
const edits = await client.edits.list({ limit: 20, order: "desc" });
for (const edit of edits.data) {
console.log(`${edit.id}: ${edit.file.filename}`);
}
```
```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)
}
edits, err := client.Edits.List(ctx, &retab.EditsListParams{
PaginationParams: retab.PaginationParams{Limit: ptr(20), Order: ptr("desc")},
})
if err != nil {
log.Fatal(err)
}
for _, edit := range edits.Data {
fmt.Printf("%s: %s\n", edit.ID, edit.File.Filename)
}
// Filter by template
filtered, err := client.Edits.List(ctx, &retab.EditsListParams{
PaginationParams: retab.PaginationParams{Limit: ptr(50)},
TemplateID: ptr("edittplt_abc123"),
})
if err != nil {
log.Fatal(err)
}
fmt.Println(filtered)
}
```
```ruby Ruby theme={null}
require 'retab'
client = Retab::Client.new(api_key: ENV['RETAB_API_KEY'])
edits = client.edits.list(limit: 20, order: 'desc')
edits.data.each do |edit|
puts "#{edit.id}: #{edit.file.filename}"
end
# Filter by template
edits = client.edits.list(template_id: 'edittplt_abc123', limit: 50)
```
```rust Rust theme={null}
use retab::enums::EditsOrder;
use retab::resources::edits::ListParams;
use retab::Retab;
#[tokio::main]
async fn main() -> Result<(), Box> {
let client = Retab::new(std::env::var("RETAB_API_KEY")?);
let edits = client
.edits()
.list(ListParams {
limit: Some(20),
order: Some(EditsOrder::Desc),
..Default::default()
})
.await?;
for edit in &edits.data {
println!("{}: {}", edit.id, edit.file.filename);
}
// Filter by template
let _filtered = client
.edits()
.list(ListParams {
template_id: Some("edittplt_abc123".into()),
limit: Some(50),
..Default::default()
})
.await?;
Ok(())
}
```
```php PHP theme={null}
edits()->list();
print_r($result);
```
```csharp C# theme={null}
using Retab;
using RetabClient = Retab.Retab;
var apiKey = Environment.GetEnvironmentVariable("RETAB_API_KEY")!;
var client = new RetabClient(apiKey);
var result = await client.Edits.ListAsync(new EditsListOptions());
Console.WriteLine(result);
```
```java Java theme={null}
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.edits().list(null, null, 10L, null, "invoice.pdf", "tmpl_abc123", null, null, null);
System.out.println(result);
}
}
```
```curl cURL theme={null}
curl -X GET \
'https://api.retab.com/v1/edits?limit=20&order=desc' \
-H "Authorization: Bearer $RETAB_API_KEY"
# With a template_id filter
curl -X GET \
'https://api.retab.com/v1/edits?template_id=edittplt_abc123' \
-H "Authorization: Bearer $RETAB_API_KEY"
```
```json 200 theme={null}
{
"data": [
{
"id": "edit_01G34H8J2K",
"file": {
"id": "file_6dd6eb00688ad8d1",
"filename": "form.pdf",
"mime_type": "application/pdf"
},
"model": "retab-small",
"template_id": null,
"usage": { "page_count": 1, "credits": 1.0 },
"created_at": "2024-03-15T10:30:00Z"
}
],
"list_metadata": {
"before": null,
"after": "edit_01G34H8J2K"
}
}
```
## OpenAPI
````yaml GET /v1/edits
openapi: 3.1.0
info:
title: FastAPI
version: 0.1.0
servers:
- url: https://api.retab.com
security: []
paths:
/v1/edits:
get:
tags:
- Edits
summary: List Edits
description: >-
List edits.
Returns a paginated list of edits. Filter by `filename`
(case-insensitive
prefix match), `template_id`, and a `from_date`/`to_date` creation range
(each `YYYY-MM-DD`). Page with `before`/`after` cursors, `limit`, and
`order`; an invalid date format responds with `400`.
operationId: list_edits
parameters:
- in: query
name: before
schema:
anyOf:
- type: string
- type: 'null'
title: Before
required: false
- in: query
name: after
schema:
anyOf:
- type: string
- type: 'null'
title: After
required: false
- in: query
name: limit
schema:
type: integer
maximum: 100
minimum: 1
default: 10
title: Limit
required: false
- in: query
name: order
schema:
enum:
- asc
- desc
type: string
default: desc
title: Order
required: false
- in: query
name: filename
schema:
anyOf:
- type: string
- type: 'null'
title: Filename
required: false
- in: query
name: template_id
schema:
anyOf:
- type: string
- type: 'null'
title: Template Id
required: false
- in: query
name: status
schema:
anyOf:
- enum:
- pending
- queued
- in_progress
- completed
- failed
- cancelled
type: string
- type: 'null'
title: Status
required: false
- in: query
name: from_date
schema:
anyOf:
- type: string
- type: 'null'
title: From Date
required: false
- in: query
name: to_date
schema:
anyOf:
- type: string
- type: 'null'
title: To Date
required: false
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EditList'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
components:
schemas:
EditList:
description: >-
A page of `Edit` resources. `data` holds the items and `list_metadata`
carries the `before`/`after` cursors; pass `after` to fetch the next
page.
properties:
data:
items:
$ref: '#/components/schemas/Edit'
type: array
title: Data
list_metadata:
$ref: '#/components/schemas/ListMetadata'
type: object
required:
- data
- list_metadata
title: EditList
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
default: []
type: object
title: HTTPValidationError
Edit:
properties:
id:
type: string
title: Id
description: Unique identifier of the edit.
file:
$ref: '#/components/schemas/FileRef'
description: Information about the source file (input document or template PDF).
model:
type: string
title: Model
description: Model used for the edit operation.
instructions:
anyOf:
- type: string
- type: 'null'
title: Instructions
description: Free-form instructions supplied with the edit request.
config:
$ref: '#/components/schemas/EditConfig'
description: Configuration used for the edit operation.
template_id:
anyOf:
- type: string
- type: 'null'
title: Template Id
description: >-
Template id used when the edit was created from a template; null for
direct-document edits.
output:
$ref: '#/components/schemas/EditResult'
description: >-
The edit result: filled form fields and the rendered PDF. An empty
sentinel until status == 'completed'; gate reads on status.
status:
type: string
enum:
- pending
- queued
- in_progress
- completed
- failed
- cancelled
title: Status
description: >-
Lifecycle status. The synchronous path returns 'completed'.
Background runs progress pending -> queued -> in_progress ->
completed | failed | cancelled.
default: pending
error:
anyOf:
- $ref: '#/components/schemas/PrimitiveError'
- type: 'null'
description: >-
Error details when a background run fails; null otherwise. Always
present so consumers can read it without an existence check.
filled_document_ref:
anyOf:
- $ref: '#/components/schemas/FileRef'
- type: 'null'
description: Durable file reference for the filled document, when materialized.
usage:
anyOf:
- $ref: '#/components/schemas/RetabUsage'
- type: 'null'
description: Usage information for the edit operation.
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
type: object
required:
- config
- file
- id
- model
title: Edit
description: >-
An edit result: form-field values written onto a document or template
PDF.
ListMetadata:
properties:
before:
anyOf:
- type: string
- type: 'null'
title: Before
after:
anyOf:
- type: string
- type: 'null'
title: After
type: object
required:
- after
- before
title: ListMetadata
description: Boundary resource IDs for page navigation.
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
FileRef:
properties:
id:
type: string
title: Id
description: ID of the file
filename:
type: string
title: Filename
description: Filename of the file
mime_type:
type: string
title: Mime Type
description: MIME type of the file
type: object
required:
- filename
- id
- mime_type
title: FileRef
description: Public/shared file reference used across SDK and customer-facing APIs.
EditConfig:
properties:
color:
anyOf:
- type: string
- type: 'null'
title: Color
description: Hex code of the color to use for the filled text.
default: '#000080'
type: object
title: EditConfig
EditResult:
properties:
form_data:
items:
$ref: '#/components/schemas/FormField'
type: array
title: Form Data
description: Filled form fields (positions, descriptions, and filled values).
filled_document:
$ref: '#/components/schemas/MIMEData'
description: PDF with the filled form values rendered in.
type: object
required:
- filled_document
- form_data
title: EditResult
PrimitiveError:
properties:
code:
type: string
title: Code
description: Machine-readable error code.
message:
type: string
title: Message
description: Human-readable error message.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
description: Optional structured error context.
type: object
required:
- code
- message
title: PrimitiveError
RetabUsage:
properties:
credits:
type: number
title: Credits
description: Credits consumed for processing
type: object
required:
- credits
title: RetabUsage
description: Usage information for document processing.
FormField:
properties:
bbox:
$ref: '#/components/schemas/BBox'
description: Position and size of this field on the page.
description:
type: string
title: Description
description: >-
Human-readable description of the field, including label and
instructions.
type:
$ref: '#/components/schemas/FieldType'
description: 'Type of field. Currently supported: ''text'' and ''checkbox''.'
key:
type: string
title: Key
description: Stable key identifying the field in the form data.
value:
anyOf:
- type: string
- type: 'null'
title: Value
description: Filled value of the field as text. Null when no filled value is set.
type: object
required:
- bbox
- description
- key
- type
title: FormField
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`.
BBox:
properties:
left:
type: number
title: Left
description: >-
Left coordinate of the bounding box, relative to page width (0.0 =
left edge, 1.0 = right edge).
top:
type: number
title: Top
description: >-
Top coordinate of the bounding box, relative to page height (0.0 =
top edge, 1.0 = bottom edge).
width:
type: number
title: Width
description: Width of the bounding box, relative to page width (0.0–1.0).
height:
type: number
title: Height
description: Height of the bounding box, relative to page height (0.0–1.0).
page:
type: integer
title: Page
description: 1-based index of the page where this field appears.
type: object
required:
- height
- left
- page
- top
- width
title: BBox
FieldType:
type: string
enum:
- text
- checkbox
title: FieldType
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````