---
title: "File Upload"
method: POST
path: "/v1/data-acquisition/agent/upload"
tags: ["Data Acquisition"]
---

# File Upload

`POST /v1/data-acquisition/agent/upload`

## Request

- Base URL: `https://api.tetrascience.com`
- URL: `https://api.tetrascience.com/v1/data-acquisition/agent/upload`
- Auth: API key in header `ts-auth-token` and API key in header `x-org-slug`

This endpoint uploads a file to TetraScience Cloud.  It requires a user-defined agent set up in the TetraScience Web UI.  API users can use it to upload, manage their files, and trigger pipelines.


Maximum payload size: 500MB

Validations performed by this endpoint:

1. `agentId` must be a valid ID of the user defined agent (UDA)
2. param `sourceType` must contain only lower case alphanumerical characters and dashes
3. params `metadata` and `tags` must contain only ASCII characters; `tags` values cannot contain comma and values must be unique
4. params `metadata` and `tags` together as JSON objects must have less than 1.5KB of text (1536 characters)

## Request body `multipart/form-data`

- object
  - `agentId` string, required: This is the sourceId for a user-defined integration. Need to copy from the TetraScience Web UI where the user-defined integration is created. For existing TetraScience Agent who can connect to TetraScience Cloud directly, provide the agentId to this field.
  - `agent` 'TetraScience.Agent.file-log' | 'TetraScience.Agent.empower' | 'TetraScience.Agent.unicorn' | 'TetraScience.Agent.labx' | 'TetraScience.Agent.chromeleon' | 'TetraScience.Agent.user-defined': Type of agent, in the form `TetraScience.Agent.file-log`, `TetraScience.Agent.empower`, etc. If provided, object in data lake will have the metadata value `agent` in the form of `agent agentVersion` (for example, `TetraScience.Agent.file-log v4.3.0')
  - `agentVersion` string: Version of the agent that's uploading the file (for example, `v4.3.0`)
  - `sourceType` string: If provided, this field will overwrite the sourceType configured in the TetraScience Web UI. Default value: `unknown` A valid sourceType string can contain only alphanumeric characters in lower case letters and dash. Any other character will trigger validation error.
  - `fileCategory` 'RAW' | 'PROCESSED': The file category of the uploaded file, included in the datalake path.
  - `fileId` string: If provided, it must be a valid and unique UUID. If not provided, platform will generate unique UUID value.
  - `traceId` string: A valid UUID, if provided. If not present, system will use the `fileId` value
  - `filePath` string, required: Required. An example of `filePath` can be `/experiment_2/sample a/result.pdf`
  - `file` string, binary, required: Content of a single file to upload
  - `payloadGzip` string: If set to `true`, indicates the file content is gzip compressed. If false or omitted, the content will be gzipped during upload. Default value: `false`.
  - `metadata` string: JSON string as `{"key", "value"}`. The metadata and value will overwrite metadata defined for the user-defined integration in the TetraScience Web UI. Validations: fields and values must contain only ASCII characters; values must be either string or null values.
  - `tags` string: JSON string as `["tag 1", "tag 2"]`. Validations: values must contain only ASCII characters; value must not have comma (,); values must be unique
  - `labels` string: JSON string as `[{"name":"label name", "value":"label value"}]`. The labels will join the agent defined labels. Validations: Names can include any unicode characters, except line breaks. They cannot be empty, and they have a maximun length of 128 characters. Values can include any unicode characters, except line breaks, and they cannot be empty.

## Response `200`

200

- object
  - `type` string
  - `fileKey` string
  - `bucket` string
  - `version` string
  - `fileId` string

## Other responses

- `404`: 404
- `422`: 422

---

[API](https://skmtc.dev/tetrascience/apis/agents.md) - [All operations](https://skmtc.dev/tetrascience/apis/agents/llms.txt) - [OpenAPI document](https://skmtc.dev/tetrascience/apis/agents/revisions/ae8c491f4b2e?raw)