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

# Sync an uploaded file into the sandbox

> After a successful Uppy upload, call this endpoint with the S3 key to materialise the file in the agent's sandbox filesystem so the agent can read it on its next tool call. No-op if the sandbox is not currently active. Requires write access to the session and the key must belong to the session prefix.



## OpenAPI

````yaml /openapi/openapi.json post /sessions/{sessionId}/files/sync-to-sandbox
openapi: 3.1.0
info:
  title: IMP REST API
  version: 1.0.0
  description: >-
    REST endpoints of the IMP backend. GraphQL covers entity CRUD; REST covers
    agent runs, media, files, and system utilities. All requests require
    authentication unless the agent is public.
servers:
  - url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:9001
        description: >-
          Base URL of your IMP backend. Self-hosted deployments typically run on
          port 9001.
security:
  - apiKey: []
  - bearer: []
tags:
  - name: Agents
    description: Endpoints for running, compacting, and querying agent instances.
  - name: Sessions
    description: Endpoints for managing files attached to agent sessions.
  - name: Media
    description: Transcription, speech synthesis, and image generation.
  - name: System
    description: Platform health and configuration utilities.
  - name: Budgets
    description: >-
      LiteLLM tag-budget management for users, roles, teams, projects, agents,
      and routines. Access requires `super_admin` or a role with
      `budget_management` write scope.
  - name: Skills
    description: >-
      Skills are versioned bundles of files (markdown, scripts, assets) mounted
      into the agent sandbox. These endpoints manage the skill registry and
      individual skill files.
  - name: Uploads
    description: >-
      Uppy-compatible S3 companion routes for single-part and multipart file
      uploads. Accept the standard API key. The `internal-key` header (set to
      `INTERNAL_SECRET`) is accepted only on `/s3/delete`, `/s3/download`,
      `/s3/list`, and `/s3/object` — it does **not** work on `/s3/sign` or the
      `/s3/multipart` routes.
  - name: Compliance
    description: >-
      GDPR / DSGVO operator endpoints for data-subject access (export) and
      erasure. Both require `super_admin`.
  - name: Artifacts
    description: >-
      Shareable artifact links — create, list, and revoke share links for files
      stored in S3.
paths:
  /sessions/{sessionId}/files/sync-to-sandbox:
    post:
      tags:
        - Sessions
      summary: Sync an uploaded file into the sandbox
      description: >-
        After a successful Uppy upload, call this endpoint with the S3 key to
        materialise the file in the agent's sandbox filesystem so the agent can
        read it on its next tool call. No-op if the sandbox is not currently
        active. Requires write access to the session and the key must belong to
        the session prefix.
      operationId: syncSessionFileToSandbox
      parameters:
        - name: sessionId
          in: path
          required: true
          description: Agent session ID (UUID).
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key
              properties:
                key:
                  type: string
                  description: Full S3 object key as returned by upload-sign.
      responses:
        '200':
          description: Sync result.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '400':
          description: Missing `key` in request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication failed or caller lacks write access to the session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Key does not belong to this session's prefix.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
        message:
          type: string
          description: Human-readable error message (alternate key used on some endpoints).
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Organisation API key. Format: `sk_<secret>/<keyname>` — the secret
        portion, a literal slash, and the human-readable key name. The header
        `exulu-api-key` is accepted as an alias. A `Bearer ` prefix is tolerated
        and stripped. Keys with an agent scope are only valid for the scoped
        agent instance.
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        NextAuth session JWT (HS256, signed with `NEXTAUTH_SECRET`). This is the
        token the IMP frontend uses automatically.

````