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.
https://api.folderpal.io/api/v1Authentication
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:copyallows copying folders, and reading and generating from templates.jobs:readallows 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
/folders/{folderId}/copyCopy a Google Drive folder into another folder. Includes all subfolders, and includes files by default.
Requires the folders:copy scope.
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
folderIdRequiredPath · string
Idempotency-KeyOptionalHeader · string
409.parentRequiredBody · string
includeFilesOptionalBody · boolean
true; set it to false to copy only the folder structure.folderNameOptionalBody · string
{{key}} tags, filled in from mergeFields.mergeFieldsOptionalBody · object
{{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.sharingGrantsOptionalBody · array
target: an email address or domain, such as[email protected]oracme.com.role:reader,commenter, orwriter.sendNotificationEmail: optional, defaults tofalse.
Up to 50 grants, each with a different target. Sharing emails come from the Google account that created the API key.
externalIdOptionalBody · string
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
/templates/{templateId}/generateGenerate 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 --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
templateIdRequiredPath · string
Idempotency-KeyOptionalHeader · string
parentOptionalBody · string
mergeFieldsOptionalBody · object
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-DDand are written in the template's date format. - Select values must match one of the field's options.
sharingGrantsOptionalBody · array
externalIdOptionalBody · string
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
/templatesList the templates you can generate from in the workspace.
Requires the folders:copy scope.
curl "https://api.folderpal.io/api/v1/templates?limit=100" \
--header "Authorization: Bearer {YOUR_API_KEY}"Parameters
limitOptionalQuery · integer
cursorOptionalQuery · string
nextCursor value from a previous response, to fetch older templates. When nextCursor is null, there are no more pages.Response
{
"templates": [
{
"id": "c3d4e5f6-0000-4000-8000-000000000000",
"name": "Client onboarding"
}
],
"nextCursor": null
}Get a template
/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 "https://api.folderpal.io/api/v1/templates/{TEMPLATE_ID}" \
--header "Authorization: Bearer {YOUR_API_KEY}"Parameters
templateIdRequiredPath · string
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"
}
}fieldsarray
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.destinationobject · nullable
null if none is saved. The name may be out of date if the folder was renamed in Drive.Get a job
/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 "https://api.folderpal.io/api/v1/jobs/{JOB_ID}" \
--header "Authorization: Bearer {YOUR_API_KEY}"Parameters
jobIdRequiredPath · string
jobId returned when a copy or template job was accepted.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"
}statusstring
pending, processing, completed, partial, failed, or canceled. Only completed means everything was copied successfully.sourcestring · nullable
web, api, or google_workspace.kindstring
copy or template.completedAtstring · nullable
null while the job is still running.folderobject · nullable
templateobject · nullable
id and current name. null for folder copies.externalIdstring · nullable
externalId sent with the request, or null if there wasn't one.List jobs
/jobsList finished jobs in the workspace, most recently completed first.
Requires the jobs:read scope.
curl "https://api.folderpal.io/api/v1/jobs?status=completed&limit=100" \
--header "Authorization: Bearer {YOUR_API_KEY}"Parameters
statusOptionalQuery · 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.limitOptionalQuery · integer
cursorOptionalQuery · string
nextCursor value from a previous response, to fetch older jobs. When nextCursor is null, there are no more pages.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
/meCheck 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 "https://api.folderpal.io/api/v1/me" \
--header "Authorization: Bearer {YOUR_API_KEY}"{
"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.
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Invalid request",
"code": "VALIDATION_ERROR",
"requestId": "a1b2c3d4-0000-4000-8000-000000000000"
}| Status | Meaning |
|---|---|
| 400 | The request is malformed or contains invalid fields. |
| 401 | The API key is missing, invalid, or revoked. |
| 403 | The key is missing the required scope, or Drive background access is unavailable. |
| 404 | The job or template was not found in this workspace. |
| 409 | An idempotency key conflicts, the workspace quota is exhausted, the template is disabled, or the template creator's background access is off. |
| 429 | The request limit is exhausted. Wait for the Retry-After value. |
| 5xx | A 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.