# File

Property Type: `file`

File types store binary data such as images or video. Each File type can be configured with multiple processors, which create streamable, named *facets*. Every File property has a default *content* facet at its root.

Streaming files is done in one of two ways, both of which begin by directly accessing a named *facet* using the path to the file property plus the facet name. For example, the Organization logo content can be accessed as follows:

```
GET /orgs/5516ee1b34d8d934281699e3/logo/content
```

The response depends on the value of the `HTTP accept` request header. If the header begins with `application/json`, the response is a json document containing a secure `url` property to the file stream:

```javascript

{
    "object": "facet",
    "ETag": "594b69d035ac27c2e69ef053082eb6a3",
    "creator": "5516ee2634d8d93428169c0e",
    "height": 500,
    "location": 4,
    "mime": "image/jpeg",
    "name": "content",    
    "size": 52586,
    "state": 2,
    "url": "https://cdn.medable.com/5516ee1b34d8d93428169/...",
    "width": 622
}
```

If the accept header does not begin with application/json, the request will result in a `302 Found`, with the `Location` response header having been set to the above `url` property.

{% hint style="info" %}
In cases where it's not possible to include HTTP request headers, such as an image tag, the Medable-Client-Key may be placed in the url as a query argument.
{% endhint %}

The Organization `logo` File property has a `thumbnail` facet, which can be accessed in much the same way, replacing *content* with *thumbnail* (`GET /orgs/5516ee1b34d8d934281699e3/logo/thumbnail`).

Reading a File without requesting a stream retrieves all of the File's facet information, which includes the root content and any available facets:

```
GET /orgs/5516ee1b34d8d934281699e3/logo
{
    "ETag": "594b69d035ac27c2e69ef053082eb6a3",
    "creator": "5516ee2634d8d93428169c0e",
    "facets": [
        {
            "ETag": "5046104d05edf82e2a2c0d72118ca15b",
            "creator": "5516ee2634d8d93428169c0e",
            "height": 241,
            "location": 4,
            "mime": "image/jpeg",
            "name": "thumbnail",
            "path": "/orgs/5516ee1b34d8d934281699e3/logo/thumbnail",
            "size": 16495,
            "state": 2,
            "width": 300
        }
    ],
    "height": 500,
    "location": 4,
    "mime": "image/jpeg",
    "name": "content",
    "path": "/orgs/5516ee1b34d8d934281699e3/logo/content",
    "size": 52586,
    "state": 2,
    "width": 622
}
```

#### File States

File content and facets can be in the following states:

| State | Name       | Description                                                                                           |
| ----- | ---------- | ----------------------------------------------------------------------------------------------------- |
| 0     | Pending    | The facet has been created, and the system is waiting for uploads.                                    |
| 1     | Processing | Sources are uploaded and are currently being processed into facets.                                   |
| 2     | Ready      | The facet is ready for streaming.                                                                     |
| 3     | Error      | There was an error processing the facet. A `fault` property is attached to the facet.                 |
| 4     | Dead       | The system will no longer attempt to process this facet. A `fault` property is attached to the facet. |

{% hint style="info" %}
Requests for facets that are still in a pending or processing will result in a `202 kMediaNotReady` fault. Clients should try again after a time. File processing time depends on the file size, type, number and type of facets, the and the facet storage location.
{% endhint %}

Private facets are only readable by the facet creator. As such, the uploaded content is completely isolated from view by other users, but can still be used as input to another process. The Conversation `attachments` File array is configured in this fashion, having a content facet that is configured to use an *overlay* png, combining it with a private *original* to produce a final image that is anonymized.

See File Uploads to find out how to upload media content.

### Property Options

| Name       | Type           | Description                                                                                                           |
| ---------- | -------------- | --------------------------------------------------------------------------------------------------------------------- |
| processors | Document Array | Processors specify how your file will be processed. Available processor types are `image`, `overlay`, and `passthru`. |

**Base property options not available:**

* indexed
* unique


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.medable.com/cortex-api/objects-definition/object-properties/file.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.