---
title: "Import a folder"
method: POST
path: "/v1/workspaces/{workspaceId}/file-imports/sources"
tags: ["File imports"]
---

# Import a folder

`POST /v1/workspaces/{workspaceId}/file-imports/sources`

## Request

- Base URL: `https://shareout.site`
- URL: `https://shareout.site/v1/workspaces/{workspaceId}/file-imports/sources`
- Auth: HTTP bearer

Creates the import and starts its first run. The picked folder becomes a ShareOut folder inside `targetFolderId` (or at the top level), mirroring subfolders. Files take the target folder's visibility (private → private, public → link-shareable, otherwise team); converted pages are never public. At most 10 folders per workspace can sync daily.

## Request body

- object
  - `provider` 'google_drive' | 'microsoft', required
  - `ref` string, required: A selectable ref from browse.
  - `name` string
  - `targetFolderId` string, nullable
  - `convert` boolean: Turn Word/Excel/PDF/Markdown/CSV (and slides
  - `dailySync` boolean

## Response `201`

Created and started

- object
  - `source` FileImportSource
    - `id` string
    - `provider` 'google_drive' | 'microsoft'
    - `remoteName` string
    - `targetFolderId` string, nullable
    - `targetFolderName` string, nullable
    - `convert` boolean
    - `dailySync` boolean
    - `nextSyncAt` string, nullable
    - `connected` boolean: false after the connection was revoked.
    - `mine` boolean
    - `lastRun` FileImportRun
      - `id` string
      - `sourceId` string
      - `status` 'queued' | 'walking' | 'importing' | 'done' | 'stopped' | 'failed'
      - `trigger` 'manual' | 'resync' | 'schedule'
      - `counts` object
        - `found` integer
        - `imported` integer
        - `converted` integer
        - `skipped` integer
        - `unchanged` integer
        - `failed` integer
      - `stopCode` string, nullable: STORAGE_QUOTA_EXCEEDED, CONNECTION_REVOKED, RATE_LIMITED, WALK_LIMIT (warning on a done run), NOT_ALLOWED, SOURCE_DELETED, STALLED, FAILED.
      - `stopMessage` string, nullable
      - `createdAt` string, date-time
      - `finishedAt` string, date-time, nullable
      - `errors` object[]: Files that failed, were skipped, or imported with a warning (up to 200).
        - `path` string
        - `status` string
        - `code` string
        - `message` string
  - `run` FileImportRun
    - `id` string
    - `sourceId` string
    - `status` 'queued' | 'walking' | 'importing' | 'done' | 'stopped' | 'failed'
    - `trigger` 'manual' | 'resync' | 'schedule'
    - `counts` object
      - `found` integer
      - `imported` integer
      - `converted` integer
      - `skipped` integer
      - `unchanged` integer
      - `failed` integer
    - `stopCode` string, nullable: STORAGE_QUOTA_EXCEEDED, CONNECTION_REVOKED, RATE_LIMITED, WALK_LIMIT (warning on a done run), NOT_ALLOWED, SOURCE_DELETED, STALLED, FAILED.
    - `stopMessage` string, nullable
    - `createdAt` string, date-time
    - `finishedAt` string, date-time, nullable
    - `errors` object[]: Files that failed, were skipped, or imported with a warning (up to 200).
      - `path` string
      - `status` string
      - `code` string
      - `message` string

## Other responses

- `400`: Invalid request
- `403`: Access denied
- `409`: Slug taken or version conflict

## Changes

- **2026-10-17** `a43d748cfdda`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shareout/apis/shareout-rest-api/changes/v1/workspaces/:workspaceId/file-imports/sources/post.md)

---

[API](https://skmtc.dev/shareout/apis/shareout-rest-api.md) - [All operations](https://skmtc.dev/shareout/apis/shareout-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shareout/apis/shareout-rest-api/revisions/1e3f7fd34f6d?raw)