> ## 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 a file preview
> Create a file preview using a S3 Path.
The input should contain the following information:
- `s3Path`: the path of the file in the S3 bucket
Create a short-lived presigned preview URL for a single file.
The input should contain the following information:
* **s3Path**: the path of the file in the S3 bucket
Need URLs for several files? Use
[`POST /files/preview/batch`](/api-reference/endpoint/create-file-previews-in-batch)
to sign up to 100 paths in one request instead of looping over this endpoint.
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 URL expires well inside the 24-hour replay window, so a replayed
response would hand back a URL that is already dead. Every request executes
fresh. See [Idempotent requests](/docs-api/api-idempotency).
## OpenAPI
````yaml post /prod/v1/files/preview
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:
post:
tags:
- Public API V1
summary: Create a file preview
description: |-
Create a file preview using a S3 Path.
The input should contain the following information:
- `s3Path`: the path of the file in the S3 bucket
operationId: PublicAPIController_createFilePreview
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/CreateFilePreviewForPAInput'
responses:
'201':
description: The signed URL for the file preview is retrieved
content:
application/json:
example:
signedUrl: >-
https://s3.amazonaws.com/bucket/upload/file.txt?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=1%2F6%2BN7Z6h%2F7oV7Z6i%2F9oV7Z4%3D&Expires=3600
schema:
type: object
properties:
signedUrl:
type: string
'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 s3Path
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid s3Path.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid s3Path.
error: Unprocessable Entity
statusCode: 422
'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:
CreateFilePreviewForPAInput:
type: object
properties:
s3Path:
type: string
description: S3 Path
example: s3://orion.com/649e2d2d2d2d2d2d2d2d2d2d
required:
- s3Path
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
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
````