> ## 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 a Space

> Stores one or more input files in a Space, where every Agent in that Space can read them
at Run time by file name. Use the Agent endpoint instead to keep a file private to a
single Agent.

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 100 MiB, and the request as a whole - every `files` part, the `lastModified` part
and the multipart framing - has to stay under 2 GB. A request over that 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.

**Re-uploading**

Uploading a file whose name already exists overwrites its content in place, keeping the
same `id`, 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.

**Zip files**

A `.zip` produced by exporting a Run is expanded into one input file per text file inside
it, matching what the Control Center UI does; the response reports each extracted file
with `expandedFrom` set to the zip's name. Entries whose extension is not in the supported
list are skipped. Any other `.zip` is stored as a single file.

An expanded zip may contain at most 500 input files totalling 500 MiB uncompressed, and
each entry name must be a plain file name — an entry carrying a directory path, or a zip
whose contents cannot be read, is rejected.

**Last Modified**

By default, the file's Last Modified time shown in the Space's file list 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 Control Center UI always sends this value automatically: 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. If you want this endpoint to
match the UI's behavior, read the file's own mtime yourself and send `lastModified`, the way
every code sample on this page does.

**What this endpoint will not do**

The Space file store imports a text file whose first token is `agent:` or `@template:` as
an Agent or Template definition. This endpoint refuses such a file rather than creating or
replacing an Agent — upload Agent content with `POST /api/v1/agent/{agentId}/content`
instead. A file whose name is already taken by an Agent or Template in the Space is
likewise refused.

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 Space.

Requires write access to the Space.



## OpenAPI

````yaml POST /api/v1/input-files/space/{spaceId}
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/space/{spaceId}:
    post:
      tags:
        - ApiInputFile
      summary: Upload input files to a Space
      description: >-
        Stores one or more input files in a Space, where every Agent in that
        Space can read them

        at Run time by file name. Use the Agent endpoint instead to keep a file
        private to a

        single Agent.


        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 100 MiB, and the request as a whole - every `files` part, the
        `lastModified` part

        and the multipart framing - has to stay under 2 GB. A request over that
        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.


        **Re-uploading**


        Uploading a file whose name already exists overwrites its content in
        place, keeping the

        same `id`, 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.


        **Zip files**


        A `.zip` produced by exporting a Run is expanded into one input file per
        text file inside

        it, matching what the Control Center UI does; the response reports each
        extracted file

        with `expandedFrom` set to the zip's name. Entries whose extension is
        not in the supported

        list are skipped. Any other `.zip` is stored as a single file.


        An expanded zip may contain at most 500 input files totalling 500 MiB
        uncompressed, and

        each entry name must be a plain file name — an entry carrying a
        directory path, or a zip

        whose contents cannot be read, is rejected.


        **Last Modified**


        By default, the file's Last Modified time shown in the Space's file list
        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 Control Center UI always sends this value automatically: 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. If you want
        this endpoint to

        match the UI's behavior, read the file's own mtime yourself and send
        `lastModified`, the way

        every code sample on this page does.


        **What this endpoint will not do**


        The Space file store imports a text file whose first token is `agent:`
        or `@template:` as

        an Agent or Template definition. This endpoint refuses such a file
        rather than creating or

        replacing an Agent — upload Agent content with `POST
        /api/v1/agent/{agentId}/content`

        instead. A file whose name is already taken by an Agent or Template in
        the Space is

        likewise refused.


        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 Space.


        Requires write access to the Space.
      parameters:
        - name: spaceId
          in: path
          description: The ID of the Space
          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`; a `.zip`
            cannot be read or exceeds the expansion limits; the content would be
            imported as an Agent or Template; or the name is already taken by an
            Agent or Template
          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 Space 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 the
            file's own mtime.

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


            const form = new FormData();

            // A zip exported from a Run is expanded into one input file per
            text file inside it; each

            // one comes back with expandedFrom set to the zip's name.

            form.append("files", new Blob([await
            readFile("export_run812.zip")]), "export_run812.zip");

            // 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("export_run812.zip")).mtimeMs)));


            const res = await
            fetch("https://dashboard.sequentum.com/api/v1/input-files/space/7",
            {
              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} (id ${file.id})`);
            }
        - lang: python
          label: Python
          source: >-
            import os

            import requests


            # A zip exported from a Run is expanded into one input file per text
            file inside it; each

            # one comes back with expandedFrom set to the zip's 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("export_run812.zip", "rb") as handle:
                response = requests.post(
                    "https://dashboard.sequentum.com/api/v1/input-files/space/7",
                    headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
                    files=[("files", ("export_run812.zip", handle, "application/zip"))],
                    data={"lastModified": int(os.path.getmtime("export_run812.zip"))},
                )

            response.raise_for_status()

            for file in response.json()["files"]:
                print(f"Stored {file['name']} (id {file['id']})")
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.