Import a folder

POST

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

curl --request POST \
  --url https://shareout.site/v1/workspaces/example/file-imports/sources \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "provider": "google_drive", "ref": "example", "name": "example", "targetFolderId": "example", "convert": true, "dailySync": false }'

• Production

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.

Authorizations

• bearerAuth

Parameters

Path Parameters

workspaceId

required

string

Workspace ID or slug.

Request Body^required

Media typeapplication/json

object

provider

required

string

Allowed values: google_drive microsoft

ref

required

A selectable ref from browse.

string

name

string

targetFolderId

string

nullable

convert

Turn Word/Excel/PDF/Markdown/CSV (and slides

boolean

default: true

dailySync

boolean

Responses

201

Created and started

Media typeapplication/json

object

source

object

id

string

provider

string

Allowed values: google_drive microsoft

remoteName

string

targetFolderId

string

nullable

targetFolderName

string

nullable

convert

boolean

dailySync

boolean

nextSyncAt

string

nullable

connected

False after the connection was revoked.

boolean

mine

boolean

lastRun

object

id

string

sourceId

string

status

string

Allowed values: queued walking importing done stopped failed

trigger

string

Allowed values: manual resync schedule

counts

object

found

integer

imported

integer

converted

integer

skipped

integer

unchanged

integer

failed

integer

stopCode

STORAGE_QUOTA_EXCEEDED, CONNECTION_REVOKED, RATE_LIMITED, WALK_LIMIT (warning on a done run), NOT_ALLOWED, SOURCE_DELETED, STALLED, FAILED.

string

nullable

stopMessage

string

nullable

createdAt

string format: date-time

finishedAt

string format: date-time

nullable

errors

Files that failed, were skipped, or imported with a warning (up to 200).

Array<object>

object

path

string

status

string

code

string

message

string

run

object

id

string

sourceId

string

status

string

Allowed values: queued walking importing done stopped failed

trigger

string

Allowed values: manual resync schedule

counts

object

found

integer

imported

integer

converted

integer

skipped

integer

unchanged

integer

failed

integer

stopCode

STORAGE_QUOTA_EXCEEDED, CONNECTION_REVOKED, RATE_LIMITED, WALK_LIMIT (warning on a done run), NOT_ALLOWED, SOURCE_DELETED, STALLED, FAILED.

string

nullable

stopMessage

string

nullable

createdAt

string format: date-time

finishedAt

string format: date-time

nullable

errors

Files that failed, were skipped, or imported with a warning (up to 200).

Array<object>

object

path

string

status

string

code

string

message

string

Example

{
  "source": {
    "provider": "google_drive",
    "lastRun": {
      "status": "queued",
      "trigger": "manual"
    }
  },
  "run": {
    "status": "queued",
    "trigger": "manual"
  }
}

400

Invalid request

Media typeapplication/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

403

Access denied

Media typeapplication/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}

409

Slug taken or version conflict

Media typeapplication/json

object

success

required

boolean

error

required

Human-readable message.

string

code

required

Machine-readable error code.

string

request_id

Correlation id (also the X-Request-Id header). Quote it in support tickets.

string

reason

Finer cause under code. For UNAUTHORIZED: missing, invalid, revoked or expired.

string

hint

What to do next, in plain words.

string

suggestion

string

param

The request field at fault.

string

docs

Doc page for this error.

string

redirect_url

string

support

Present on 5xx — how to reach a human.

object

how

string

include

Array<string>

Example

{
  "success": false,
  "support": {
    "how": "POST /v1/support/tickets",
    "include": [
      "request_id"
    ]
  }
}