---
title: "Create a file"
method: POST
path: "/files"
tags: ["Files"]
---

# Create a file

`POST /files`

## Request

- Base URL: `https://public-api.process.st/api/v1.1`
- URL: `https://public-api.process.st/api/v1.1/files`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Adds a document to a folder in your Library, ready for people with access to use. First call createFileUpload and upload your document to the returned URL, then pass the fileUploadId here. Each upload ID can be used once.

## Request body

- CreateFileRequest
  - `fileUploadId` string, required: Single-use handle returned by createFileUpload after uploading the document bytes.
  - `name` string, required: Display name.
  - `description` string: Optional free-form description of the file.
  - `folderId` string, required: The ID of the Folder.
  - `shareLevel` 'None' | 'View': Controls who can view this file. `None` — only organization members can view this file. `View` — anyone with the link can view this file.
  - `referenceId` string: Version prefix used when version control is enabled on this file. Combined with the version number to form the full version identifier.

## Response `201`

- PublicApiFileResponse
  - `data` object, required
    - `id` string, required: The resource's ID.
    - `name` string, required: The file's name.
    - `description` string: Optional free-form description of the file.
    - `folderId` string, required: The ID of the Folder.
    - `shareLevel` 'None' | 'View', required: Controls who can view this file. `None` — only organization members can view this file. `View` — anyone with the link can view this file.
    - `referenceId` string: Version prefix used when version control is enabled on this file. Combined with the version number to form the full version identifier.
    - `createdDate` string, date-time, required: When the resource was first created. ISO-8601 UTC.
    - `createdBy` object, required: User who created the resource.
      - `id` string, required: The resource's ID.
      - `email` string, required: The user's email address (also their login identifier).
      - `username` string, required: The user's display name (e.g. `Jane Doe`).
    - `updatedDate` string, date-time, required: When the resource was last modified. ISO-8601 UTC.
    - `updatedBy` object, required: User who last modified the resource.
      - `id` string, required: The resource's ID.
      - `email` string, required: The user's email address (also their login identifier).
      - `username` string, required: The user's display name (e.g. `Jane Doe`).
    - `links` object[]: Navigable HATEOAS links to related resources. Each entry has a `name` (RFC-5988 link relation like `self`, `edit`, `related`), an `href` URL, and a `type` (`Api` for callable endpoints, `App` for browser-facing URLs). Prefer following these `href` values over constructing URLs by hand.
      - `name` string, required: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
      - `href` string, required: URL of the linked resource.
      - `rel` 'Approval Task' | 'Approvals' | 'Assignees' | 'Comment' | 'Data Set Records' | 'Data Sets' | 'Form Field Values' | 'Subject Task' | 'Task' | 'Tasks' | 'Users' | 'Webhook' | 'Workflow' | 'Workflow Run': Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
      - `type` 'Api' | 'App', required: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.
  - `links` object[]: Pagination links. When the result has more pages, look for an entry with `name: "next"` — its `href` is the URL to fetch the next page. Absence of `next` means there are no more pages. For single-resource responses this array is typically empty.
    - `name` string, required: Standard link relation name (RFC 5988) indicating this link's role. Common values include `self`, `edit`, `related`, `previous`, `next`.
    - `href` string, required: URL of the linked resource.
    - `rel` 'Approval Task' | 'Approvals' | 'Assignees' | 'Comment' | 'Data Set Records' | 'Data Sets' | 'Form Field Values' | 'Subject Task' | 'Task' | 'Tasks' | 'Users' | 'Webhook' | 'Workflow' | 'Workflow Run': Optional. The kind of resource this link points to (e.g. `Workflow`, `Task`, `Comment`).
    - `type` 'Api' | 'App', required: Whether this link targets an API endpoint or a Process Street app URL. `Api` — a callable API endpoint you can fetch directly. `App` — a browser-facing URL in the Process Street UI.

## Other responses

- `400`: Invalid value for: body
- `default`

## Changes

- **2026-10-30** `292a565ad8bc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/process/apis/process-street-public-api/changes/files/post.md)

---

[API](https://skmtc.dev/process/apis/process-street-public-api.md) - [All operations](https://skmtc.dev/process/apis/process-street-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/process/apis/process-street-public-api/revisions/78ea0b3f3b40?raw)