# Create File

[View original](https://ittybit.cloud/api/files/create)


`POST /files`

Creates a new file from a publicly accessible or signed URL.

### Parameters

```json
[
  {
    "$ref": "#/components/parameters/AcceptVersionHeader"
  }
]
```

### Request Body

The request body should contain a properly formatted JSON object with a `url` property. Other optional properties are listed below. See [File Object](/docs/files) for more details.

**Schema:**

```json
{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string"
    },
    "media_id": {
      "type": "string"
    },
    "folder": {
      "type": "string"
    },
    "filename": {
      "type": "string"
    },
    "ref": {
      "type": "string"
    },
    "metadata": {
      "type": "object"
    }
  }
}
```

**Example:**

```json
{
  "url": "https://ittyb.it/sample.mp4",
  "folder": "ittybit/samples",
  "filename": "video.mp4",
  "metadata": {
    "customKey": "your custom value"
  }
}
```

### Responses

#### 201 - Success

**Example:**

```json
{
  "id": "file_abcdefgh1234",
  "media_id": "med_abcdefgh1234",
  "object": "source",
  "kind": "video",
  "type": "video/mp4",
  "width": 1920,
  "height": 1080,
  "duration": 123.45,
  "filesize": 12345678,
  "folder": "ittybit/samples",
  "filename": "video.mp4",
  "url": "https://you.ittybit.net/ittybit/samples/video.mp4",
  "metadata": {
    "customKey": "your custom value"
  },
  "created": "2025-01-01T01:23:45Z",
  "updated": "2025-01-01T01:23:45Z",
  "status": "ready"
}
```