---
title: "Add a new file"
method: POST
path: "/files"
tags: ["File Library API"]
---

# Add a new file

`POST /files`

Adds a new File to the library by providing URL of the file.

If a file with identical URL already exists, then the original file is returned. If a file does not exist, a new file is created.

[See examples](#tag/Examples/File-Library-API-examples/Add-a-new-file)

## Headers

- `X-PF-Store-Id` string

## Request body

- File — Information about the File
  - `type` string — Role of the file
  - `id` integer — File ID
  - `url` string, required — Source URL where the file is downloaded from. The use of .ai .psd and .tiff files have been depreciated, if your application uses these file types or accepts these types from users you will need to add validation.
  - `options` FileOption[] — Array of additional options for this file [See examples](#tag/Common/Options)
    - `id` string, required — Option id
    - `value` string, required — Option value
  - `hash` string — MD5 checksum of the file
  - `filename` string — File name
  - `mime_type` string — MIME type of the file
  - `size` integer — Size in bytes
  - `width` integer — Width in pixels
  - `height` integer — Height in pixels
  - `dpi` integer — Resolution DPI.<br>**Note:** for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
  - `status` string — File processing status:<br>**ok** - file was processed successfuly<br>**waiting** - file is being processed<br>**failed** - file failed to be processed
  - `created` integer — File creation timestamp
  - `thumbnail_url` string — Small thumbnail URL
  - `preview_url` string — Medium preview image URL
  - `visible` boolean — Show file in the Printfile Library (default true)
  - `is_temporary` boolean — Whether it is a temporary printfile.

## Response `200`

OK

- object
  - `code` integer — Response status code `200`
  - `result` File — Information about the File
    - `type` string — Role of the file
    - `id` integer — File ID
    - `url` string, required — Source URL where the file is downloaded from. The use of .ai .psd and .tiff files have been depreciated, if your application uses these file types or accepts these types from users you will need to add validation.
    - `options` FileOption[] — Array of additional options for this file [See examples](#tag/Common/Options)
      - `id` string, required — Option id
      - `value` string, required — Option value
    - `hash` string — MD5 checksum of the file
    - `filename` string — File name
    - `mime_type` string — MIME type of the file
    - `size` integer — Size in bytes
    - `width` integer — Width in pixels
    - `height` integer — Height in pixels
    - `dpi` integer — Resolution DPI.<br>**Note:** for vector files this may be indicated as only 72dpi, but it doesn't affect print quality since the vector files are resolution independent.
    - `status` string — File processing status:<br>**ok** - file was processed successfuly<br>**waiting** - file is being processed<br>**failed** - file failed to be processed
    - `created` integer — File creation timestamp
    - `thumbnail_url` string — Small thumbnail URL
    - `preview_url` string — Medium preview image URL
    - `visible` boolean — Show file in the Printfile Library (default true)
    - `is_temporary` boolean — Whether it is a temporary printfile.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

[API](https://skmtc.net/printful/apis/api-documentation-printful.md) · [All operations](https://skmtc.net/printful/apis/api-documentation-printful/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/printful/api-documentation-printful/revisions/18e2f2e178dd/schema)