> For the complete documentation index, see [llms.txt](https://developer.kizen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-apis/upload-files-for-smartconnector-runs.md).

# Upload Files for SmartConnector Runs

{% hint style="success" %}
**Audience**: Developers, Integrators

**Purpose**: Describes how to upload an input file to <code class="expression">space.vars.Kizen\_company\_name</code> for a <code class="expression">space.vars.smartconnector</code> run, from the pre-signed URL request through S3 upload and confirmation, returning a reusable file reference.&#x20;
{% endhint %}

A <code class="expression">space.vars.smartconnector</code> typically runs against an input file you provide. If none is supplied, it falls back to the <code class="expression">space.vars.smartconnector</code> 's sample file. To use your own file, first upload it to <code class="expression">space.vars.Kizen\_company\_name</code>'s file storage. The presigned request in [Get a Presigned Upload URL](#get-a-presigned-upload-url) returns an `s3object_id`, which you confirm in [Confirm the Upload with Kizen](#confirm-the-upload-with-kizen) and then pass as `source_file_id` to the [Start SmartConnector Flow API](/docs/concepts/smartconnectors/smartconnector-apis/start-smartconnector-flow-api.md).

#### Get a Presigned Upload URL

Request a temporary presigned URL from <code class="expression">space.vars.Kizen\_company\_name</code>'s file storage service. This URL authorizes a direct upload to S3 and expires after a short window. Upload the file and confirm the upload before the `expires_at` timestamp in the response.

**GET** `/api/s3/presigned-post`

| Query Parameter | Type   | Required | Description                                                                                                                          |
| --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `filename`      | string | Yes      | The name of the file to upload, including extension (for example, `data.csv`).                                                       |
| `contenttype`   | string | Yes      | The MIME type of the file (for example, `text/csv` or `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for XLSX`). |
| `source`        | string | Yes      | Must be set to `smart_connector_import`.                                                                                             |

**Example request:**

```
GET /api/s3/presigned-post?filename=data.csv&contenttype=text/csv&source=smart_connector_import
```

**Example response:**

```json
{
  "url": "https://<bucket>.s3.amazonaws.com/",
  "fields": {
    "key": "...",
    "Content-Type": "text/csv",
    "acl": "private",
    "tagging": "...",
    "policy": "...",
    "x-amz-algorithm": "...",
    "x-amz-credential": "...",
    "x-amz-date": "...",
    "x-amz-signature": "..."
  },
  "s3object_id": "f9e8d7c6-...",
  "max_file_size": 15000000,
  "expires_at": "..."
}
```

**Response fields:**

| Field           | Type              | Description                                                                                                                                                                                                            |
| --------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`           | string            | The S3 bucket URL to POST the file to in the upload process.                                                                                                                                                           |
| `fields`        | object            | Required form fields to include in the upload multipart POST. All fields must be included in the upload request.                                                                                                       |
| `s3object_id`   | string (UUID)     | The <code class="expression">space.vars.Kizen\_company\_name</code> identifier for this upload, a randomly generated ID. Pass this as the `uuid` parameter in the upload and as the `source_file_id` subsequent steps. |
| `max_file_size` | integer           | Maximum allowed file size in bytes.                                                                                                                                                                                    |
| `expires_at`    | string (datetime) | Timestamp after which the presigned URL is no longer valid.                                                                                                                                                            |

### Upload the File to S3

POST the file directly to the S3 URL. This request goes to S3 directly, not to the <code class="expression">space.vars.Kizen\_company\_name</code> API.

**POST** `{url from URL request response}`

Send all fields returned in the `fields` <code class="expression">space.vars.object</code> from the URL request as `multipart/form-data`, with the file content appended last. Capture the `ETag` value from the S3 response header, since you will need it in subsequent steps.

### Confirm the Upload with Kizen

Notify <code class="expression">space.vars.Kizen\_company\_name</code> that the S3 upload completed successfully so the file is registered in the system and available for use as a <code class="expression">space.vars.smartconnector</code> run input.

**POST** `/api/s3/success?source=smart_connector_import`

Send as `application/x-www-form-urlencoded`:

| Field | Type          | Required | Description                                                                                                      |
| ----- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| uuid  | string (UUID) | Yes      | The `s3object_id` returned with the URL request.                                                                 |
| key   | string        | Yes      | The key value from the `fields` <code class="expression">space.vars.object</code> returned with the URL request. |
| name  | string        | Yes      | The filename including extension ( `data.csv`).                                                                  |
| etag  | string        | Yes      | The `ETag` value from the S3 upload response header.                                                             |

Once this request returns successfully, the file is registered in <code class="expression">space.vars.Kizen\_company\_name</code> and ready to use as the input for a <code class="expression">space.vars.smartconnector</code> run.

***

## What's Next?

Continue with the [Start SmartConnector Flow API](/docs/concepts/smartconnectors/smartconnector-apis/start-smartconnector-flow-api.md) to run a <code class="expression">space.vars.smartconnector</code> against your uploaded file, passing the `s3object_id` as `source_file_id`.

<details>

<summary><strong>Related Topics</strong></summary>

* [SmartConnector External Data Source](/docs/concepts/smartconnectors/smartconnector-external-data-sources.md)
* [SmartConnector Settings](/docs/concepts/smartconnectors/smartconnector-settings.md)

</details>


---

# 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 dynamically by asking a question.

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

```
GET https://developer.kizen.com/docs/concepts/smartconnectors/smartconnector-apis/upload-files-for-smartconnector-runs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.