> 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/types/file.md).

# File

File Type

Represents a file object in the system.

## Fields

| Field          | Type           | Description                                                                                                                                              |
| -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`           | `ID!`          | Unique identifier of the file                                                                                                                            |
| `tenantID`     | `UUID!`        | Tenant identifier                                                                                                                                        |
| `createdAt`    | `Time!`        | Creation timestamp                                                                                                                                       |
| `createdBy`    | `UUID`         | User identifier who created the file                                                                                                                     |
| `updatedAt`    | `Time`         | Last update timestamp                                                                                                                                    |
| `updatedBy`    | `UUID`         | User identifier who last updated the file                                                                                                                |
| `deletedAt`    | `Time`         | Deletion timestamp                                                                                                                                       |
| `deletedBy`    | `UUID`         | User identifier who deleted the file                                                                                                                     |
| `dataTypeID`   | `UUID`         | Data type identifier                                                                                                                                     |
| `dataTypeSlug` | `String`       | Data type slug                                                                                                                                           |
| `data`         | `Map`          | Custom data associated with the file                                                                                                                     |
| `refid`        | `UUID!`        | Reference ID for the attached entity                                                                                                                     |
| `reftype`      | `FileReftype!` | Reference type of the file                                                                                                                               |
| `description`  | `String`       | Description of the file                                                                                                                                  |
| `filename`     | `String!`      | Name of the attached file                                                                                                                                |
| `size`         | `Int`          | Size of the file in bytes. May be `null` until the upload has been finalized via [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md). |
| `contentType`  | `String!`      | MIME type of the file                                                                                                                                    |
| `publicAlias`  | `String`       | Human-readable, slug-based identifier for the file (unique per tenant)                                                                                   |
| `url`          | `String`       | URL to access the file content                                                                                                                           |
| `publicURL`    | `String`       | URL that resolves the public alias to a pre-signed S3 URL via 307 redirect                                                                               |

## Interfaces

* `Node`

## Optional Size and Two-Phase Upload

The `size` field is nullable to support a two-phase upload workflow:

1. [`createFile`](/graphql-api/mutations/createfile.md) creates the metadata record. The `size` argument is optional, so workers and pipelines can record file metadata before the payload is available.
2. The client `PUT`s the bytes to the returned `preSignedUploadUrl`.
3. [`finalizeFileUpload`](/graphql-api/mutations/finalize-file-upload.md) inspects the object in S3 and persists the real byte size on the `File` record.

To find files that are still pending finalization, filter with the `sizeIsNil` predicate on `FileWhereInput`:

```graphql
query PendingUploads {
  files(where: { sizeIsNil: true }) {
    edges {
      node {
        id
        filename
        createdAt
      }
    }
  }
}
```

## Public Alias

The `publicAlias` field provides a stable, human-readable identifier for a file that is unique within a tenant. When set, it enables access to the file through a public HTTP endpoint at `/api/v1/files/{tenantId}/{alias}`, which returns a 307 redirect to a pre-signed S3 URL with cache-busting headers.

The `publicURL` field is a computed field that returns the full URL for this endpoint when a `publicAlias` is set.

This allows stable, shareable links to files without exposing internal IDs.

## Usage Example

```graphql
query {
  files(first: 5) {
    edges {
      node {
        id
        reftype
        filename
        contentType
        size
        url
        publicAlias
        publicURL
        description
        createdAt
      }
    }
  }
}
```


---

# 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/types/file.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.