Reference · Files

# POST/file

Registers a file name and returns a URL to upload the file to. Send the file’s bytes to that URL with `PUT` within 5 minutes. The file can then be used as an input by its `file_path`.

## Request body

Request body

- `file_name` (string): Required. 1 to 255 characters, with no slash or backslash and no control characters. Not “.” or “..”.
- `dir_id` (string): The directory to put the file in. Left out, a new directory is created that expires after 24 hours.

To upload: `curl -X PUT "$UPLOAD_URL" --upload-file source.mp4`. A file may be up to 5 GB.

## Example

Request

```bash
curl https://media.logicboostkit.com/file \
  -H "Authorization: Basic $MEDIA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "source.mp4" }'
```

Response

```http
HTTP/1.1 200 OK
X-Request-Id: job_0mv6hqvpqkiwproi518azpod

{
  "ok": true,
  "file": {
    "dir_id": "dir_pi23jgy1yxlmigi873bz",
    "file_name": "source.mp4",
    "file_path": "dir_pi23jgy1yxlmigi873bz/source.mp4",
    "added_on": "2026-10-13T09:41:07.214Z"
  },
  "upload": {
    "url": "https://…",
    "method": "PUT",
    "headers": {},
    "expiresInSeconds": 300
  }
}
```

## Response fields

Response fields

- `ok` (boolean): true when the name was registered.
- `file.dir_id` (string): The directory the file is in.
- `file.file_name` (string): The name you sent.
- `file.file_path` (string): dir_id/file_name: what a task’s input refers to.
- `file.added_on` (string): When the name was registered, in UTC.
- `upload.url` (string): Where to send the bytes. Signed, and yours alone.
- `upload.method` (string): Always PUT.
- `upload.headers` (object): Headers the upload must carry. Always empty; a Content-Type you send anyway is accepted and kept.
- `upload.expiresInSeconds` (number): How long the URL works: 300.

After the URL expires it answers 403. Call `POST /file` again with the same name and directory for a fresh one.

## Status codes

Status codes

- **200**: The name is registered and the upload URL is ready. Not charged.
- **400**: The body isn’t a JSON object, `file_name` is missing, or it breaks the naming rule.
- **401**: The `Authorization` header is missing, or the key is invalid, revoked or expired.
- **403**: The account isn’t active. The error says what to do.
- **404**: `Directory not found`: `dir_id` isn’t a directory in your account, or it has expired.
- **409**: `File name already exists in directory`: a file has already been uploaded under this name. Delete it first, or choose another name.
- **429**: More than 300 requests in a minute on this key. Wait for the number of seconds in `Retry-After`.

Every error has the shape `{"ok": false, "error": "…"}` and is never charged.