> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create file previews in batch
> Create presigned preview URLs for several S3 paths in a single request.
Accepts up to 100 paths in `s3Paths`. Results are returned in
request order, each echoing its `s3Path` so callers can map URLs back to files.
All-or-nothing: if any path is invalid the whole request fails — no partial results.
Use `POST /v1/files/preview` for a single path.
Create presigned preview URLs for several S3 paths in a single request, instead
of calling [`POST /files/preview`](/api-reference/endpoint/create-a-file-preview)
once per file.
## Request Parameters
### Request Body
| Property | Type | Required | Description |
| -------- | ----- | -------- | ------------------------------------------------ |
| s3Paths | array | Yes | S3 paths to sign. Between 1 and 100 per request. |
```json theme={null}
{
"s3Paths": [
"s3://orion.com/649e2d2d2d2d2d2d2d2d2d2d",
"s3://orion.com/649e2d2d2d2d2d2d2d2d2d2e"
]
}
```
## Response
`previews` contains one entry per requested path, **in request order**, each
echoing its `s3Path` so you can map URLs back to files without relying on order
alone.
| Field | Type | Description |
| --------- | ------ | --------------------------------------- |
| s3Path | string | The requested S3 path, echoed back |
| signedUrl | string | Short-lived presigned URL for that path |
```json theme={null}
{
"previews": [
{
"s3Path": "s3://orion.com/649e2d2d2d2d2d2d2d2d2d2d",
"signedUrl": "https://s3.amazonaws.com/bucket/upload/file.txt?..."
}
]
}
```
**All-or-nothing.** If any path in `s3Paths` is invalid, the whole request
fails with a `422` and no partial results are returned. Check `errors[]` in the
problem response for the failing field.
Presigned URLs are short-lived (about one hour). Request them when you are
ready to use them rather than caching them.
## Idempotency
`Idempotency-Key` is accepted for client uniformity but **ignored** here: the
presigned URLs expire well inside the 24-hour replay window, so a replayed
response would hand back URLs that are already dead. Every request executes
fresh. See [Idempotent requests](/docs-api/api-idempotency).
## OpenAPI
````yaml post /prod/v1/files/preview/batch
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/files/preview/batch:
post:
tags:
- Public API V1
summary: Create file previews in batch
description: >-
Create presigned preview URLs for several S3 paths in a single request.
Accepts up to 100 paths in `s3Paths`. Results are returned in
request order, each echoing its `s3Path` so callers can map URLs back to
files.
All-or-nothing: if any path is invalid the whole request fails — no
partial results.
Use `POST /v1/files/preview` for a single path.
operationId: PublicAPIController_createFilePreviewBatch
parameters:
- name: Idempotency-Key
in: header
description: >-
Accepted for client uniformity but IGNORED on this endpoint. It has
no side effects, and its presigned URLs expire in an hour — well
inside the 24h replay window — so a replayed response would carry
URLs that are already dead against S3. Every request executes fresh:
no 24h window, no replay, no Idempotent-Replayed header, and no
key-reuse 422.
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFilePreviewBatchForPAInput'
responses:
'201':
description: A signed URL is returned for every requested path
content:
application/json:
schema:
$ref: '#/components/schemas/CreateFilePreviewBatchForPAOutput'
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Invalid s3Paths (see errors[] for the failing field)
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
CreateFilePreviewBatchForPAInput:
type: object
properties:
s3Paths:
description: S3 paths to sign, at most 100 per request.
minItems: 1
maxItems: 100
example:
- s3://orion.com/649e2d2d2d2d2d2d2d2d2d2d
- s3://orion.com/649e2d2d2d2d2d2d2d2d2d2e
type: array
items:
type: string
required:
- s3Paths
CreateFilePreviewBatchForPAOutput:
type: object
properties:
previews:
description: >-
One entry per requested path, in request order. All-or-nothing: an
invalid path fails the whole request rather than returning partial
results.
type: array
items:
$ref: '#/components/schemas/FilePreviewForPAOutput'
required:
- previews
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
FilePreviewForPAOutput:
type: object
properties:
s3Path:
type: string
description: The requested S3 path, echoed so callers can map results.
example: s3://orion.com/649e2d2d2d2d2d2d2d2d2d2d
signedUrl:
type: string
description: Short-lived presigned URL for that path.
example: >-
https://s3.amazonaws.com/bucket/upload/file.txt?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=1%2F6%2BN7Z6h%2F7oV7Z6i%2F9oV7Z4%3D&Expires=3600
required:
- s3Path
- signedUrl
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````