Available on Enterprise plans.
Enabling storage on a task
Storage is configured when you create or update a task. Set storage.enabled to true to capture files. Set storage.extraction to true to also extract structured data from those files.
POST /v2/tasks
{
"name": "Fetch utility bills",
"agent_id": "agt_a1b2c3d4...",
"input_schema": {
"type": "object",
"properties": {
"start_date": { "type": "string" },
"end_date": { "type": "string" }
}
},
"output_schema": {
"type": "object",
"properties": {
"bill_count": { "type": "integer" }
}
},
"storage": {
"enabled": true,
"extraction": true,
"deduplication": true
}
}
| Field | Type | Description |
|---|
storage.enabled | boolean | Capture files produced during task execution |
storage.extraction | boolean | Parse captured files and extract structured data |
storage.extraction_schema | object | Custom schema to guide what gets extracted |
storage.deduplication | boolean | Skip files that have already been stored from a previous run |
Retrieving storage items
After a task run completes, list the files it produced using the task run storage endpoint.
curl https://api.deck.co/v2/task-runs/trun_a1b2c3d4/storage \
-H "Authorization: Bearer sk_live_your_key_here"
{
"data": [
{
"id": "stor_x1y2z3...",
"object": "storage_item",
"file_name": "statement_jan_2025.pdf",
"file_type": "application/pdf",
"file_size": 245678,
"url": "https://storage.deck.co/...",
"metadata": {},
"fetch_date": "2025-01-15T09:30:00Z",
"extraction": null,
"task_run_id": "trun_a1b2c3d4...",
"created_at": "2025-01-15T09:30:00Z",
"request_id": "req_a1b2c3d4..."
},
{
"id": "stor_a4b5c6...",
"object": "storage_item",
"file_name": "statement_dec_2024.pdf",
"file_type": "application/pdf",
"file_size": 198432,
"url": "https://storage.deck.co/...",
"metadata": {},
"fetch_date": "2025-01-15T09:30:05Z",
"extraction": {
"company_name": "EnergyLink",
"account_number": "58291-44720",
"billing_date": "2024-12-22",
"amount_due": 6925.18,
"currency": "USD"
},
"task_run_id": "trun_a1b2c3d4...",
"created_at": "2025-01-15T09:30:05Z",
"request_id": "req_a1b2c3d4..."
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_f5g6h7..."
}
Storage item fields
Unique identifier, prefixed with stor_.
Original file name as it appeared on the source.
MIME type (application/pdf, image/png, video/mp4, text/csv, etc.).
Source-specific metadata attached by Deck during capture.
When the file was retrieved from the source.
Structured data extracted from the file, if extraction is enabled.
The task run that produced this storage item.
Downloading files
Each storage item includes a url field with a signed download URL. Use it to fetch the raw file.
curl -O "https://storage.deck.co/stor_x1y2z3..."
curl https://api.deck.co/v2/storage/stor_x1y2z3 \
-H "Authorization: Bearer sk_live_your_key_here"
extraction field on each storage item with structured JSON.
Extraction works with common document types including PDFs, spreadsheets, invoices, receipts, and reports. The extracted data depends on the document. A utility bill produces different fields than a hotel receipt.
Use the extraction_schema field on the task’s storage config to define exactly what fields you want extracted. Deck uses this schema to guide parsing.
{
"storage": {
"enabled": true,
"extraction": true,
"extraction_schema": {
"type": "object",
"properties": {
"vendor_name": { "type": "string" },
"total_amount": { "type": "number" },
"invoice_date": { "type": "string", "format": "date" },
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": { "type": "string" },
"amount": { "type": "number" }
}
}
}
}
}
}
}
{
"company_name": "EnergyLink",
"account_number": "58291-44720",
"billing_date": "2025-01-22",
"billing_period": {
"start_date": "2024-12-18",
"end_date": "2025-01-20",
"total_days": 33
},
"amount_due": 8247.41,
"payment_due_date": "2025-02-14",
"currency": "USD",
"service_locations": [
{
"service_type": "Fuel",
"service_address": {
"street": "4421 OAK VIEW LN UNIT 3A",
"city": "CAMBRIDGE",
"state": "MA",
"postal_code": "02140"
},
"total_usage": 5348,
"total_usage_unit": "Therms",
"total_charges": 8214.67
}
]
}
extraction field is null. The raw file is still available for download. Only the extraction step failed.
Common causes:
| Error code | Meaning |
|---|
extraction_failed | The file couldn’t be parsed. Corrupt, unsupported layout, or unreadable content. |
extraction_timeout | Extraction took too long |
Deduplication
Deduplication is off by default. When storage.deduplication is true, Deck compares files against previous runs for the same task and connection. If a file has already been stored, it’s skipped. This is useful for recurring fetch tasks. Run the same task daily and only new files are captured.
Events
Storage items emit events you can subscribe to through event destinations:
| Event | When it fires |
|---|
storage.created | A new file has been captured and is ready for download |
storage.deleted | A storage item was permanently removed |
Deleting storage items
To permanently remove a stored file:
curl -X DELETE https://api.deck.co/v2/storage/stor_x1y2z3 \
-H "Authorization: Bearer sk_live_your_key_here"
{
"id": "stor_x1y2z3...",
"object": "storage_item",
"deleted": true,
"request_id": "req_a1b2c3d4..."
}
Retention
Retention period varies by plan. All files are deleted after 90 days.
