> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequentum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload input files to an Agent

> Stores one or more input files against a single Agent. Only that Agent can read them at
Run time - use the Space endpoint instead to share one file across every Agent in a Space.

The request is `multipart/form-data` with one or more parts named `files`.

**Supported formats**

`.csv`, `.tsv`, `.txt`, `.json`, `.xml`, `.xls`, `.xlsx`, `.parquet`, `.zip`. A file may
be up to 2 GB, and 2 GB is also the ceiling on the request as a whole - every `files`
part, the `lastModified` part and the multipart framing count toward it. So a batch has to
stay under 2 GB in total, and a single file has to leave room for the framing around it. A
request over the ceiling is rejected while the body is still being read, before the
endpoint runs, so it does not come back with the usual error body.

The Editor applies its own, lower ceiling of 100 MiB when a file is uploaded through an
Agent's `Files` panel. That is a limitation of the Editor, not of this endpoint: a file
between 100 MiB and 2 GB is accepted here and readable by a Run, but cannot be uploaded or
replaced through the Editor.

**Re-uploading**

Uploading a file whose name already exists overwrites it, so a Run always reads the file
most recently uploaded under that name. This is what makes a two-stage workflow work: the
first Agent's output can be pushed under a fixed name that the second Agent reads. Agent
input files keep no version history, and the returned `id` changes on every upload.

A `.zip` is stored as a single file on this endpoint - it is never expanded. A zip whose
contents cannot be read is rejected.

**Last Modified**

By default, the file's Last Modified time shown in the Agent's Files panel is the time of
this upload. Send `lastModified` to record the file's own modification time instead - one
value applies to every file, or send one value per `files` part to give each file its own
time.

The Editor sends this value automatically when a file is uploaded through an Agent's
`Files` panel: the browser reads it from the file you pick, with nothing for you to do. A
script or HTTP client calling this endpoint has no such value available on its own - no
common client (curl, Postman, `requests`, `httpx`) attaches a file's modification time to
an upload by default. To match what the Editor does, read the file's own mtime yourself
and send `lastModified`, the way every code sample on this page does.

Every file is checked before any of them is stored — its name, extension and size, and for a
`.zip`, that its contents can be read. The batch is then written in a single database
transaction. So a rejected request stores nothing at all, and a request that fails while
being written registers none of its files against the Agent.

Requires write access to the Agent.



## OpenAPI

````yaml POST /api/v1/input-files/agent/{agentId}
openapi: 3.0.4
info:
  title: Sequentum Cloud API
  description: API endpoints for Sequentum Cloud
  version: v1
servers: []
security:
  - ApiKey: []
    Bearer: []
paths:
  /api/v1/input-files/agent/{agentId}:
    post:
      tags:
        - ApiInputFile
      summary: Upload input files to an Agent
      description: >-
        Stores one or more input files against a single Agent. Only that Agent
        can read them at

        Run time - use the Space endpoint instead to share one file across every
        Agent in a Space.


        The request is `multipart/form-data` with one or more parts named
        `files`.


        **Supported formats**


        `.csv`, `.tsv`, `.txt`, `.json`, `.xml`, `.xls`, `.xlsx`, `.parquet`,
        `.zip`. A file may

        be up to 2 GB, and 2 GB is also the ceiling on the request as a whole -
        every `files`

        part, the `lastModified` part and the multipart framing count toward it.
        So a batch has to

        stay under 2 GB in total, and a single file has to leave room for the
        framing around it. A

        request over the ceiling is rejected while the body is still being read,
        before the

        endpoint runs, so it does not come back with the usual error body.


        The Editor applies its own, lower ceiling of 100 MiB when a file is
        uploaded through an

        Agent's `Files` panel. That is a limitation of the Editor, not of this
        endpoint: a file

        between 100 MiB and 2 GB is accepted here and readable by a Run, but
        cannot be uploaded or

        replaced through the Editor.


        **Re-uploading**


        Uploading a file whose name already exists overwrites it, so a Run
        always reads the file

        most recently uploaded under that name. This is what makes a two-stage
        workflow work: the

        first Agent's output can be pushed under a fixed name that the second
        Agent reads. Agent

        input files keep no version history, and the returned `id` changes on
        every upload.


        A `.zip` is stored as a single file on this endpoint - it is never
        expanded. A zip whose

        contents cannot be read is rejected.


        **Last Modified**


        By default, the file's Last Modified time shown in the Agent's Files
        panel is the time of

        this upload. Send `lastModified` to record the file's own modification
        time instead - one

        value applies to every file, or send one value per `files` part to give
        each file its own

        time.


        The Editor sends this value automatically when a file is uploaded
        through an Agent's

        `Files` panel: the browser reads it from the file you pick, with nothing
        for you to do. A

        script or HTTP client calling this endpoint has no such value available
        on its own - no

        common client (curl, Postman, `requests`, `httpx`) attaches a file's
        modification time to

        an upload by default. To match what the Editor does, read the file's own
        mtime yourself

        and send `lastModified`, the way every code sample on this page does.


        Every file is checked before any of them is stored — its name, extension
        and size, and for a

        `.zip`, that its contents can be read. The batch is then written in a
        single database

        transaction. So a rejected request stores nothing at all, and a request
        that fails while

        being written registers none of its files against the Agent.


        Requires write access to the Agent.
      parameters:
        - name: agentId
          in: path
          description: The ID of the Agent
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                files:
                  type: array
                  items:
                    type: string
                    format: binary
                  description: The input files to store
                lastModified:
                  type: array
                  items:
                    type: integer
                    format: int64
                  description: >-
                    Optional last-modified time(s) for the files, as a Unix
                    epoch between `315532800` (1980-01-01) and `4102444800`
                    (2100-01-01) in seconds, or the equivalent in milliseconds.
                    Send one value to apply it to every file in the batch, or
                    one value per `files` part, in the same order, to give each
                    file its own time. `0` or omitting the part entirely means
                    the time of the upload, and a value ahead of the upload time
                    is recorded as the upload time.
            encoding:
              files:
                style: form
              lastModified:
                style: form
      responses:
        '200':
          description: The files were stored
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputFileUploadResult'
        '400':
          description: >-
            If no files were sent; a file is empty, oversized, or has an
            unsupported extension or name; `lastModified` is out of range, or
            its count matches neither one nor the number of `files`; or a `.zip`
            cannot be read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
        '401':
          description: If the API key is missing or invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: >-
            If the Agent is not found, or the user doesn't have write access to
            it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: >-
            If the files could not be stored. The message carries a reference
            that identifies the request in the server logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      x-codeSamples:
        - lang: curl
          label: cURL
          source: >-
            # Omitting lastModified records the upload time instead of each
            file's own mtime.

            curl -X POST
            https://dashboard.sequentum.com/api/v1/input-files/agent/123 \
              -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
              -F "files=@urls.csv" \
              -F "files=@extra-urls.txt" \
              -F "lastModified=$(date -r urls.csv +%s)" \
              -F "lastModified=$(date -r extra-urls.txt +%s)"
        - lang: node
          label: Node.js
          source: >-
            import { readFile, stat } from "node:fs/promises";


            const form = new FormData();

            // Every part must be named "files". Re-uploading a name overwrites
            that input file, so the

            // next Run of the Agent reads whatever was uploaded last under that
            name.

            form.append("files", new Blob([await readFile("urls.csv")]),
            "urls.csv");

            // lastModified is a Unix epoch in seconds or milliseconds - mtimeMs
            is already the unit the

            // API accepts, rounded because it carries a fractional part.
            Omitting it records the upload

            // time instead of the file's own mtime.

            form.append("lastModified", String(Math.round((await
            stat("urls.csv")).mtimeMs)));


            const res = await
            fetch("https://dashboard.sequentum.com/api/v1/input-files/agent/123",
            {
              method: "POST",
              headers: { "Authorization": `ApiKey ${process.env.SEQUENTUM_API_KEY}` },
              body: form,
            });


            const result = await res.json();

            for (const file of result.files) {
              console.log(`Stored ${file.name} (${file.size} bytes)`);
            }
        - lang: python
          label: Python
          source: >-
            import os

            import requests


            # Every part must be named "files". Re-uploading a name overwrites
            that input file, so the

            # next Run of the Agent reads whatever was uploaded last under that
            name.

            # lastModified is a Unix epoch in seconds or milliseconds -
            getmtime() is already the unit the

            # API accepts. Omitting it records the upload time instead of the
            file's own mtime.

            with open("urls.csv", "rb") as handle:
                response = requests.post(
                    "https://dashboard.sequentum.com/api/v1/input-files/agent/123",
                    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
                    files=[("files", ("urls.csv", handle, "text/csv"))],
                    data={"lastModified": int(os.path.getmtime("urls.csv"))},
                )

            response.raise_for_status()

            for file in response.json()["files"]:
                print(f"Stored {file['name']} ({file['size']} bytes)")
components:
  schemas:
    InputFileUploadResult:
      type: object
      properties:
        files:
          type: array
          items:
            $ref: '#/components/schemas/UploadedInputFileModel'
          description: The files that were stored, in the order they were processed.
          nullable: true
      additionalProperties: false
      description: >-
        Result of uploading input files. Contains one entry per stored file - an
        agent export zip

        produces one entry per file extracted from it.
    BadRequestError:
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
        statusDescription:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
          readOnly: true
        severity:
          $ref: '#/components/schemas/ErrorSeverity'
        errorCode:
          type: string
          description: >-
            Optional machine-readable error code. When present, clients should
            switch on this

            value rather than parsing
            Sequentum.Enterprise.Core.ControllerError.Message. The controller
            pipeline serialises

            with System.Text.Json, which ignores the Newtonsoft attribute below,
            so an unset code

            reaches the client as `"errorCode": null` rather than being omitted
            - clients

            must treat null and absent alike.
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    InternalServerError:
      type: object
      properties:
        statusCode:
          type: integer
          format: int32
        statusDescription:
          type: string
          nullable: true
        message:
          type: string
          nullable: true
          readOnly: true
        severity:
          $ref: '#/components/schemas/ErrorSeverity'
        errorCode:
          type: string
          description: >-
            Optional machine-readable error code. When present, clients should
            switch on this

            value rather than parsing
            Sequentum.Enterprise.Core.ControllerError.Message. The controller
            pipeline serialises

            with System.Text.Json, which ignores the Newtonsoft attribute below,
            so an unset code

            reaches the client as `"errorCode": null` rather than being omitted
            - clients

            must treat null and absent alike.
          nullable: true
      additionalProperties: false
    UploadedInputFileModel:
      type: object
      properties:
        name:
          type: string
          description: The file name the Agent uses to read the file at Run time.
          nullable: true
        id:
          type: integer
          description: >-
            The ID of the stored file. For a Space input file this is the shared
            file's ID, stable

            across re-uploads of the same name. For an Agent input file it
            identifies the record just

            written, and changes every time the file is re-uploaded.
          format: int32
        version:
          type: integer
          description: >-
            The shared file's version number after the upload. Re-uploading the
            same name overwrites

            the content in place, so this number does not increment. `null` for
            Agent input files,

            which are not versioned at all.
          format: int32
          nullable: true
        size:
          type: integer
          description: The stored size in bytes.
          format: int64
        expandedFrom:
          type: string
          description: >-
            The name of the export zip this file was extracted from, when it
            came from one.
          nullable: true
      additionalProperties: false
      description: One stored input file.
    ErrorSeverity:
      enum:
        - 0
        - 1
        - 2
        - 3
        - 4
      type: integer
      description: >-
        `0` = `Error`; `1` = `Unexpected`; `2` = `Fatal`; `3` = `Warning`; `4` =
        `Info`
      format: int32
  securitySchemes:
    ApiKey:
      type: apiKey
      description: >-
        API Key authorization header. Example: "Authorization: ApiKey
        {your-api-key}"
      name: Authorization
      in: header
    Bearer:
      type: http
      description: 'OAuth 2.0 Bearer token. Example: "Authorization: Bearer {access-token}"'
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.