REST APIv1

FolderPal API

Copy Google Drive folders and generate folder structures from your templates, from your own apps and automations. Send a request, and FolderPal handles the work in the background.

Base URLhttps://api.folderpal.io/api/v1

Authentication

Create a workspace API key at FolderPal > Settings > API. All API requests require this key as a Bearer token in the request header.

Note you may be asked to connect to Google Drive. This is a simple consent prompt for Google Drive permissions so FolderPal can run in the background.

When creating a key, the following scopes are granted:

  • folders:copy allows copying folders, and reading and generating from templates.
  • jobs:read allows reading FolderPal jobs and job statuses.

Usage

API access and usage limits depend on your plan. Jobs started through the API count toward the same limits as jobs started in the app. See Pricing for each plan's limits.

Copy a folder

POST/folders/{folderId}/copy

Copy a Google Drive folder into another folder. Includes all subfolders, and includes files by default.

Requires the folders:copy scope.

cURL
curl --request POST \
  "https://api.folderpal.io/api/v1/folders/{SOURCE_FOLDER_ID}/copy" \
  --header "Authorization: Bearer {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --data '{"parent":"{DESTINATION_FOLDER_ID}","includeFiles":true,"folderName":"Acme Onboarding","externalId":"deal_123"}'

Parameters

folderIdRequired

Path · string

The source Google Drive folder ID. Use the ID itself, not a Drive URL.
Idempotency-KeyOptional

Header · string

Optionally, set a unique key for safe retries. Retrying with the same key and body within 24 hours returns the original job instead of creating a duplicate; reusing a key with a different body returns 409.
parentRequired

Body · string

The destination Google Drive folder ID.
includeFilesOptional

Body · boolean

Include files in the copy. Defaults to true; set it to false to copy only the folder structure.
folderNameOptional

Body · string

Optionally, set a name for the copied top-level folder. Defaults to the source folder's name. Can include {{key}} tags, filled in from mergeFields.
mergeFieldsOptional

Body · object

Optionally, replace {{key}} tags in folder and file names. Map each key (without braces) to a string, for example {"client_name":"Acme"}. Keys are 3–100 letters, digits, or underscores and match case-insensitively.
sharingGrantsOptional

Body · array

Share the new top-level folder. Subfolders and files inherit access through Google Drive. Each grant has:
  • target: an email address or domain, such as [email protected] or acme.com.
  • role: reader, commenter, or writer.
  • sendNotificationEmail: optional, defaults to false.

Up to 50 grants, each with a different target. Sharing emails come from the Google account that created the API key.

externalIdOptional

Body · string

Optionally, your own ID for the record behind this request, like a CRM deal ID. 1–255 characters, and it doesn't need to be unique. It's returned on the job, so don't put secrets in it.

Response

202Job accepted
Response
{
  "jobId": "a1b2c3d4-0000-4000-8000-000000000000",
  "status": "accepted"
}

Folder copy operations are asynchronous. Each request queues a folder copy job, which runs in the background. Check a job's status with GET /jobs/{jobId}, or view all jobs at FolderPal > History. Webhook notifications are coming soon.

Create folders from a template

POST/templates/{templateId}/generate

Generate a new Google Drive folder structure from a saved FolderPal template, filling in its merge fields. Templates can only be created in the web app. It works like generating in the app.

Requires the folders:copy scope.

cURL
curl --request POST \
  "https://api.folderpal.io/api/v1/templates/{TEMPLATE_ID}/generate" \
  --header "Authorization: Bearer {YOUR_API_KEY}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: acme-onboarding-2026" \
  --data '{
    "mergeFields": {"client_name":"Acme","start_date":"2026-12-01","tier":"Premium"},
    "sharingGrants": [{"target":"[email protected]","role":"writer","sendNotificationEmail":true}]
  }'

Parameters

templateIdRequired

Path · string

The template ID from List templates.
Idempotency-KeyOptional

Header · string

Works the same as for copying a folder. A retry with the same key and body returns the original job.
parentOptional

Body · string

The destination Google Drive folder ID. Defaults to the template's saved destination if none is provided.
mergeFieldsOptional

Body · object

Values for the template's fields, keyed by field name from Get a template. All values are strings:
  • Fields you leave out use their default, or are left blank. Required fields must be supplied.
  • Dates use YYYY-MM-DD and are written in the template's date format.
  • Select values must match one of the field's options.
sharingGrantsOptional

Body · array

Works the same as for copying a folder. Grants set here are added on top of the template's default grants.
externalIdOptional

Body · string

Works the same as for copying a folder.

Response

202Job accepted
Response
{
  "jobId": "a1b2c3d4-0000-4000-8000-000000000000",
  "status": "accepted"
}

Template jobs run as the template's creator. The creator must have Google Drive background access turned on. The template's saved sharing settings apply, and later edits to the template don't change jobs that were already accepted. Track progress with GET /jobs/{jobId}.

List templates

GET/templates

List the templates you can generate from in the workspace.

Requires the folders:copy scope.

cURL
curl "https://api.folderpal.io/api/v1/templates?limit=100" \
  --header "Authorization: Bearer {YOUR_API_KEY}"

Parameters

limitOptional

Query · integer

Number of templates per page, from 1 to 100. Defaults to 100.
cursorOptional

Query · string

The nextCursor value from a previous response, to fetch older templates. When nextCursor is null, there are no more pages.

Response

200Available templates
Response
{
  "templates": [
    {
      "id": "c3d4e5f6-0000-4000-8000-000000000000",
      "name": "Client onboarding"
    }
  ],
  "nextCursor": null
}

Get a template

GET/templates/{templateId}

Get a template's merge fields and saved destination. Use it to build the inputs for a generate request.

Requires the folders:copy scope.

cURL
curl "https://api.folderpal.io/api/v1/templates/{TEMPLATE_ID}" \
  --header "Authorization: Bearer {YOUR_API_KEY}"

Parameters

templateIdRequired

Path · string

The template ID from List templates.

Response

200Template found
Response
{
  "id": "c3d4e5f6-0000-4000-8000-000000000000",
  "name": "Client onboarding",
  "fields": [
    { "id": "f1", "name": "client_name", "label": "Client name", "required": true, "type": "text" },
    { "id": "f2", "name": "project_number", "label": "Project number", "required": false, "type": "number", "defaultValue": 100 },
    { "id": "f3", "name": "start_date", "label": "Start date", "required": true, "type": "date", "format": "DD-MM-YYYY" },
    { "id": "f4", "name": "tier", "label": "Tier", "required": false, "type": "select", "options": ["Standard", "Premium"] }
  ],
  "destination": {
    "id": "{DESTINATION_FOLDER_ID}",
    "name": "Clients"
  }
}
fields

array

The template's merge fields. type is text, number, date, or select. Text and number fields may have a defaultValue, date fields have an output format, and select fields have options.
destination

object · nullable

The saved destination folder, or null if none is saved. The name may be out of date if the folder was renamed in Drive.

Get a job

GET/jobs/{jobId}

Check the status of a generation job and find the Drive folder it created. Jobs include both folder copies and template generations.

Requires the jobs:read scope.

cURL
curl "https://api.folderpal.io/api/v1/jobs/{JOB_ID}" \
  --header "Authorization: Bearer {YOUR_API_KEY}"

Parameters

jobIdRequired

Path · string

The jobId returned when a copy or template job was accepted.

Response

200Job found
Response
{
  "jobId": "a1b2c3d4-0000-4000-8000-000000000000",
  "status": "completed",
  "source": "api",
  "kind": "copy",
  "createdAt": "2026-09-17T01:00:00Z",
  "startedAt": "2026-09-17T01:01:00Z",
  "completedAt": "2026-09-17T01:05:00Z",
  "folder": {
    "id": "{GOOGLE_DRIVE_FOLDER_ID}",
    "name": "Acme Project",
    "mimeType": "application/vnd.google-apps.folder",
    "webViewLink": "https://drive.google.com/drive/folders/{GOOGLE_DRIVE_FOLDER_ID}"
  },
  "template": null,
  "externalId": "deal_123"
}
status

string

One of pending, processing, completed, partial, failed, or canceled. Only completed means everything was copied successfully.
source

string · nullable

Where the job started: web, api, or google_workspace.
kind

string

copy or template.
completedAt

string · nullable

When processing ended, including failed jobs. null while the job is still running.
folder

object · nullable

A snapshot of the top-level folder for that generation.
template

object · nullable

The template's id and current name. null for folder copies.
externalId

string · nullable

The externalId sent with the request, or null if there wasn't one.

List jobs

GET/jobs

List finished jobs in the workspace, most recently completed first.

Requires the jobs:read scope.

cURL
curl "https://api.folderpal.io/api/v1/jobs?status=completed&limit=100" \
  --header "Authorization: Bearer {YOUR_API_KEY}"

Parameters

statusOptional

Query · string

completed (the default), partial, or completed,partial. A partial job created the top-level folder, but some items failed. If it's retried and completes, it keeps the same jobId.
limitOptional

Query · integer

Number of jobs per page, from 1 to 100. Defaults to 100.
cursorOptional

Query · string

The nextCursor value from a previous response, to fetch older jobs. When nextCursor is null, there are no more pages.

Response

200Jobs found
Response
{
  "jobs": [
    {
      "jobId": "a1b2c3d4-0000-4000-8000-000000000000",
      "status": "completed",
      ...
    }
  ],
  "nextCursor": null
}

Each job uses the same format as Get a job.

Verify a key

GET/me

Check that an API key works and see which workspace, key name, and scopes it belongs to. This does not create a job.

Works with either the folders:copy or jobs:read scope.

cURL
curl "https://api.folderpal.io/api/v1/me" \
  --header "Authorization: Bearer {YOUR_API_KEY}"
Response
{
  "workspaceId": "a1b2c3d4-0000-4000-8000-000000000000",
  "workspaceName": "Acme Inc",
  "keyId": "b2c3d4e5-0000-4000-8000-000000000000",
  "keyName": "Production automation",
  "scopes": ["folders:copy", "jobs:read"]
}

Errors and retries

Every error uses the same JSON format. Use the HTTP status and code field to decide what your automation should do next.

Error response
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request",
  "code": "VALIDATION_ERROR",
  "requestId": "a1b2c3d4-0000-4000-8000-000000000000"
}
StatusMeaning
400The request is malformed or contains invalid fields.
401The API key is missing, invalid, or revoked.
403The key is missing the required scope, or Drive background access is unavailable.
404The job or template was not found in this workspace.
409An idempotency key conflicts, the workspace quota is exhausted, the template is disabled, or the template creator's background access is off.
429The request limit is exhausted. Wait for the Retry-After value.
5xxA temporary service error. Retry conservatively with the same idempotency key.

Request limits are 60 requests per key and 300 per workspace per minute, shared across all endpoints. Do not automatically retry other 4xx responses.