---
title: "Client and temp files"
section: "API Reference"
route: /apiclientfile
account: {accountId}
bruce_api: https://{accountId}.api.nextspace.host
guardian_api: https://guardian.nextspace.host
---
# Client and temp files

Persistent files that we track in your account are called Client Files. These are stored in your File Store Location (typically an S3 bucket) with a corresponding entry in our table with metadata.

A temp file uses a similar process however it's cleared periodically.

## Details

You can request the metadata on a Client File using the 'details' endpoint. This does not work for temp files.

### Client File details

```http
GET https://{accountId}.api.nextspace.host/file/{file_id}/details
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{file_id}` | path | yes | ID of the Client File to get details for. |

**Response**

```typescript
interface IResponse {
    // The ID of the file.
    ID: string;
    // The file's extension.
    // Should start with a 'dot', we're actively working to ensure this is always the case.
    // It's recommended to either parse it from 'OriginalFileName' or check for the dot yourself until stable.
    FileExt: string;
    // The file's mime type.
    MIMEType: string;
    // The file's original name. This includes the extension.
    OriginalFileName: string;
    // The file's size in bytes.
    OriginalLength: number;
    // The user's ID who uploaded the file.
    "UploadedByUser.ID": string;
    // An optional category for the file.
    // Some Nextspace default purposes have additional meaning.
    Purpose?: string;
    // UTC date/time when the file was uploaded.
    Created: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/{file_id}/details";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Download

To download a Client File from a known ID use this request:

### Download Client File

```http
GET https://{accountId}.api.nextspace.host/file/{file_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{file_id}` | path | yes | ID of the Client File to download. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/{file_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

To download a temp file from a known ID use this request:

### Download Client File

```http
GET https://{accountId}.api.nextspace.host/tempFile/{file_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{file_id}` | path | yes | ID of the temp file to download. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/tempFile/{file_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Delete

To delete a Client File use this request:

### Delete Client File

```http
GET https://{accountId}.api.nextspace.host/file/{file_id}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{file_id}` | path | yes | ID of the Client File to delete. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/{file_id}";
const method = "get";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Delete multiple Client Files

```http
POST https://{accountId}.api.nextspace.host/deleteFiles
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IRequest {
    // Array of Client File IDs to delete.
    "Items": string[];
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/deleteFiles";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Update Purpose

If you'd like to update the purpose of an existing Client File. You can use this request:

### Update Client File purpose

```http
POST https://{accountId}.api.nextspace.host/file/updatepurpose/{file_id}?Purpose={purpose}
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |
| `{file_id}` | path | yes | ID of the Client File to update. |
| `Purpose={purpose}` | query | yes | The new purpose for the file. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/updatepurpose/{file_id}";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

## Upload file

Smaller file uploads (typically up to 100MB) can be done by sending the file directly in the request body.

### Upload Client File

```http
POST https://{accountId}.api.nextspace.host/file/uploadNew
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IRequest {
    // The file to upload.
    file: File;
    // Optional purpose to assign to the newly created Client File record.
    Purpose?: string;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/uploadNew";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Upload temp file

```http
POST https://{accountId}.api.nextspace.host/file/uploadTemp
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IRequest {
    // The file to upload.
    file: File;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/file/uploadTemp";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

For larger file uploads, we have to perform a multi-part upload.

You split the file into chunks and upload each part separately. Once all parts are uploaded, your Client File record is created.
The final part you upload to complete your Client File will return the Client File record.

If you experience an issue with a part upload, you can re-upload that part. The system will overwrite the existing portion with the new one.

### Upload Client File part

```http
POST https://{accountId}.api.nextspace.host/fileUpload
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Request body**

```typescript
interface IRequest {
    // Name of the file.
    "originalFileName": string;
    // Unique token to identify this upload.
    // Use a UUID or similar.
    "token": string;
    // Total number of parts you're uploading.
    "count": number;
    // The part number of this upload.
    // This starts at 1.
    "part": number;
    // The file part to upload.
    "file": File;
}
```

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/fileUpload";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

### Upload temp file part

```http
POST https://{accountId}.api.nextspace.host/tempFileUpload
```

**Requires:**

- Account ID: Account ID must be specified in the subdomain of the request url.
- Logged in user auth token: A token for an active user session on the account, sent as "Authorization: Bearer <token>".
- Power user auth token: A token for an active power user session on the account, sent as "Authorization: Bearer <token>".

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `{accountId}` | path | yes | The account id of the account to perform the request on. |

**Javascript example**

```javascript
const url = "https://{accountId}.api.nextspace.host/tempFileUpload";
const method = "post";
const token = "your-token";
const body = null;

async function doRequest(type, url, body, token) {
    const headers = {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
    };
    const options = {
        method: type,
        headers: headers,
        body: body ? JSON.stringify(body) : null
    };
    const res = await fetch(url, options);
    const json = await res.json();
    return json;
}

doRequest(method, url, body, token).then((res) => {
    console.log(res);
}).catch((err) => {
    console.error(err);
});
```

---

Urls on this page are resolved for account `{accountId}`.
Site index: https://docs.nextspace.host/llms.txt · whole site in one file: https://docs.nextspace.host/llms-full.txt
Human-readable version of this page: https://docs.nextspace.host/apiclientfile