Google Drive Integration¶

Google Drive integration allows you to translate files directly from your Drive and optionally deliver translated files back automatically.

Plan Requirement

Google Drive integration requires a Professional plan or higher.

Connect Your Account¶

Generate Authorization URL¶

GET /v1/integrations/google/connect

Generate an OAuth authorization URL. Redirect the user to this URL to grant Falara read/write access to their Google Drive.

Authentication: X-API-Key header

Scopes requested:

Scope	Purpose
`drive.file`	Access only files opened or created by Falara
`openid`	Verify user identity
`email`	Retrieve account email address

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/integrations/google/connect \
  -H "X-API-Key: YOUR_API_KEY"

import requests

resp = requests.get(
    "https://app.falara.io/v1/integrations/google/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
auth_url = resp.json()["url"]

const resp = await fetch(
  "https://app.falara.io/v1/integrations/google/connect",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { url } = await resp.json();

Response 200 OK

{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&scope=..."
}

Check Connection Status¶

GET /v1/integrations/google/status

Check whether a Google Drive connection is active for the current API key.

Authentication: X-API-Key header

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/integrations/google/status \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/integrations/google/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(resp.json()["status"])  # "active" or "none"

const resp = await fetch(
  "https://app.falara.io/v1/integrations/google/status",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log(data.status); // "active" or "none"

Response 200 OK

{
  "status": "active",
  "google_email": "user@example.com",
  "scopes": ["drive.file", "openid", "email"]
}

Field	Type	Description
`status`	string	`"active"` (connected) or `"none"` (not connected)
`google_email`	string	Google account email (only when active)
`scopes`	list	Granted OAuth scopes (only when active)

Disconnect Account¶

DELETE /v1/integrations/google/disconnect

Revoke Falara's access to Google Drive and delete all stored tokens.

Authentication: X-API-Key header

cURLPythonJavaScript

curl -X DELETE https://app.falara.io/v1/integrations/google/disconnect \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.delete(
    "https://app.falara.io/v1/integrations/google/disconnect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(resp.json()["status"])  # "disconnected"

const resp = await fetch(
  "https://app.falara.io/v1/integrations/google/disconnect",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();

Response 200 OK

{
  "status": "disconnected"
}

Get Picker Token¶

GET /v1/integrations/google/picker-token

Retrieve a short-lived access token for the Google Picker UI widget. Use this token client-side to let users browse and select files from their Drive.

Authentication: X-API-Key header

cURLPythonJavaScript

curl -X GET https://app.falara.io/v1/integrations/google/picker-token \
  -H "X-API-Key: YOUR_API_KEY"

resp = requests.get(
    "https://app.falara.io/v1/integrations/google/picker-token",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
token = resp.json()["access_token"]

const resp = await fetch(
  "https://app.falara.io/v1/integrations/google/picker-token",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { access_token } = await resp.json();

Response 200 OK

{
  "access_token": "ya29.a0AfH6SMB..."
}

Token Lifetime

The picker token expires in approximately 1 hour. Use it exclusively for the client-side file picker -- never store or reuse it for other purposes.

Translate Drive Files¶

Create Drive Translation Jobs¶

POST /v1/services/google-drive/jobs

Create one or more translation jobs from files stored in Google Drive. Each file is translated into every requested target language, producing one job per file-language combination.

Authentication: X-API-Key header Status: 202 Accepted

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/services/google-drive/jobs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
        "name": "brochure.docx"
      }
    ],
    "source_lang": "de",
    "target_langs": ["en", "fr"],
    "quality": "standard",
    "glossary_id": "gloss_abc12345",
    "project_name": "Q2 Brochures",
    "source_review": true
  }'

resp = requests.post(
    "https://app.falara.io/v1/services/google-drive/jobs",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "files": [
            {
                "file_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
                "name": "brochure.docx",
            }
        ],
        "source_lang": "de",
        "target_langs": ["en", "fr"],
        "quality": "standard",
        "glossary_id": "gloss_abc12345",
        "project_name": "Q2 Brochures",
        "source_review": True,
    },
)
batch = resp.json()

const resp = await fetch(
  "https://app.falara.io/v1/services/google-drive/jobs",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      files: [
        {
          file_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
          name: "brochure.docx",
        },
      ],
      source_lang: "de",
      target_langs: ["en", "fr"],
      quality: "standard",
      glossary_id: "gloss_abc12345",
      project_name: "Q2 Brochures",
      source_review: true,
    }),
  }
);
const batch = await resp.json();

Request Body

Field	Type	Required	Description
`files`	list	yes	Drive files to translate. Each object contains `file_id` and `name`.
`source_lang`	string	yes	BCP-47 source language code (e.g. `"de"`, `"en"`)
`target_langs`	list[string]	yes	Target languages, 1 to 10 codes
`quality`	string	no	`"standard"` (default) or `"premium"`
`glossary_id`	string	no	Glossary ID to enforce terminology
`text_type`	string	no	Text category hint (e.g. `"marketing"`, `"legal"`)
`constraints`	list	no	Formal constraints for the translation
`source_review`	boolean	no	Force source review step on or off
`project_name`	string	no	Human-readable project label

Response 202 Accepted

{
  "batch_id": "b1c2d3e4-5678-9abc-def0-1234567890ab",
  "jobs": [
    {
      "job_id": "550e8400-e29b-41d4-a716-446655440000",
      "target_language": "en",
      "status": "queued"
    },
    {
      "job_id": "661f9511-f30c-52e5-b827-557766551111",
      "target_language": "fr",
      "status": "queued"
    }
  ]
}

Plan Limits¶

Plan	Files per Request	Daily Limit
Professional	5	50
Business	10	200
Enterprise	20	Unlimited

File Delivery¶

Deliver Translated File to Drive¶

POST /v1/jobs/{job_id}/deliver

Manually trigger delivery of a translated file back to Google Drive.

Authentication: X-API-Key header Status: 200 OK

cURLPythonJavaScript

curl -X POST https://app.falara.io/v1/jobs/550e8400-e29b-41d4-a716-446655440000/deliver \
  -H "X-API-Key: YOUR_API_KEY"

job_id = "550e8400-e29b-41d4-a716-446655440000"
resp = requests.post(
    f"https://app.falara.io/v1/jobs/{job_id}/deliver",
    headers={"X-API-Key": "YOUR_API_KEY"},
)

const jobId = "550e8400-e29b-41d4-a716-446655440000";
const resp = await fetch(
  `https://app.falara.io/v1/jobs/${jobId}/deliver`,
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);

When to Use This Endpoint

Jobs that finish with completed status are automatically delivered to Google Drive. Use this endpoint only for re-delivery or for jobs that ended with needs_review or completed_with_blocks status, where automatic delivery was skipped.

Errors¶

Status	Reason
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Plan does not include Google Drive integration, or Drive account not connected
`404 Not Found`	Job ID not found
`400 Bad Request`	Not a Drive job, or job is not in a terminal status
`422 Unprocessable Entity`	Validation error (e.g. unsupported language, too many files)