> For the complete documentation index, see [llms.txt](https://docs.pyck.cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pyck.cloud/graphql-api/mutations/createfile.md).

# Create File

createFile Mutation

Creates a new File object.

## Arguments

| Name    | Type               | Description                      |
| ------- | ------------------ | -------------------------------- |
| `input` | `CreateFileInput!` | Input data for creating the file |

## Return Type

`CreateFileResult` - Contains the created file ID, the file object, and a pre-signed upload URL for the file content.

## Input Fields

`CreateFileInput`:

| Field          | Type           | Description                                                                                                                                                                                                                                                          |
| -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dataTypeID`   | `UUID`         | Optional data type ID                                                                                                                                                                                                                                                |
| `dataTypeSlug` | `String`       | Optional data type slug                                                                                                                                                                                                                                              |
| `data`         | `Map`          | Custom data associated with the file                                                                                                                                                                                                                                 |
| `refid`        | `UUID!`        | Required reference ID                                                                                                                                                                                                                                                |
| `reftype`      | `FileReftype!` | Required reference type                                                                                                                                                                                                                                              |
| `description`  | `String`       | Optional description                                                                                                                                                                                                                                                 |
| `filename`     | `String!`      | Required filename                                                                                                                                                                                                                                                    |
| `size`         | `Int`          | Optional file size in bytes. Workers and clients that do not know the size up front can omit this field and call [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md) after the bytes have been uploaded to S3 to populate it from object storage. |
| `contentType`  | `String!`      | Required content MIME type                                                                                                                                                                                                                                           |
| `publicAlias`  | `String`       | Optional human-readable, slug-based identifier (unique per tenant)                                                                                                                                                                                                   |

{% hint style="warning" %}
**Breaking change:** `CreateFileInput.size` was changed from `Int!` to `Int`. The corresponding `File.size` field on the response type is now nullable as well. Existing clients must handle a missing `size` until [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md) has been called.
{% endhint %}

## Recommended Upload Workflow

The typical pyck file upload flow is now a two-phase write:

1. Call `createFile` to create the metadata record. `size` may be omitted.
2. `PUT` the file bytes to the returned `preSignedUploadUrl`.
3. Call [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md) with the file `id`. The resolver inspects the object in S3, reads its real byte size, and persists it on the `File` record.

This split lets workers and background pipelines record file metadata before the payload is available, then reconcile the size once the upload completes.

## Usage Example

```graphql
mutation {
  createFile(
    input: {
      refid: "550e8400-e29b-41d4-a716-446655440000"
      reftype: item
      filename: "product_image.jpg"
      contentType: "image/jpeg"
      description: "Product image for item"
      publicAlias: "product-image-smartphone-front"
    }
  ) {
    id
    preSignedUploadUrl
    file {
      id
      filename
      contentType
      size
      publicAlias
      publicURL
    }
  }
}
```

You may still pass `size` if it is known at creation time:

```graphql
mutation {
  createFile(
    input: {
      refid: "550e8400-e29b-41d4-a716-446655440000"
      reftype: item
      filename: "product_image.jpg"
      size: 12345
      contentType: "image/jpeg"
    }
  ) {
    id
    preSignedUploadUrl
  }
}
```

## Related

* [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md) - Finalize the upload by persisting the real size from S3
* [File](/graphql-api/types/file.md) - File type reference


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.pyck.cloud/graphql-api/mutations/createfile.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.