{
  "openapi": "3.0.1",
  "info": {
    "title": "Google Sheets Import Export",
    "description": "Read rows from a Google Sheets tab or A1 range into an Apify dataset, or export any Actor's dataset to a sheet as an integration step: append, replace or append-only-new-rows (dedupe on key columns). Public sheets read without credentials; private sheets and writes need a service-account key.",
    "version": "0.1",
    "x-build-id": "eUHFc1hanugUsvb6K"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/axiomworks~google-sheets-import-export/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-axiomworks-google-sheets-import-export",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/axiomworks~google-sheets-import-export/runs": {
      "post": {
        "operationId": "runs-sync-axiomworks-google-sheets-import-export",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/axiomworks~google-sheets-import-export/run-sync": {
      "post": {
        "operationId": "run-sync-axiomworks-google-sheets-import-export",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "required": [
          "spreadsheetUrl"
        ],
        "properties": {
          "spreadsheetUrl": {
            "title": "Spreadsheet URL or ID",
            "type": "string",
            "description": "Required URL or ID; sheetName overrides URL gid. One spreadsheet per run. Google Sheets URL or bare spreadsheet ID to read from or write to, e.g. 'https://docs.google.com/spreadsheets/d/<id>/edit#gid=0'. A #gid= in the URL selects that tab. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "mode": {
            "title": "Operation: read, append, replace or append-dedupe",
            "enum": [
              "read",
              "append",
              "replace",
              "append-dedupe"
            ],
            "type": "string",
            "description": "Omitted mode infers append when datasetId/rawData exists (append-dedupe with dedupeFields), otherwise read. Set explicitly for agents. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "sheetName": {
            "title": "Tab name (exact worksheet title)",
            "type": "string",
            "description": "Omitted selects URL gid or first tab. Overrides URL gid; a tab name inside range is used when sheetName is omitted. Tab (worksheet) name to use, e.g. 'Class Data'. Overrides the gid in the URL. In write modes the tab is created when it does not exist. Default: the tab from the URL, else the first tab. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "range": {
            "title": "Read range (A1 notation)",
            "type": "string",
            "description": "Omitted reads the whole tab. A tab-qualified range supplies sheetName only when sheetName is omitted. Read selection uses headerRow and offset. Optional A1 range to read, e.g. 'A1:C10' or 'Class Data!A1:C10' (the tab prefix sets the tab name). Read mode only. Default: the whole tab. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "maxItems": {
            "title": "Row limit: integer, 0 for unlimited",
            "minimum": 0,
            "maximum": 1000000,
            "type": "integer",
            "description": "Shared row budget for this run, applied after read offset and before write dedupe; 0 is unlimited. Omitted: 1000 read rows or unlimited write rows. Limit rows to process, 0-1000000. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "offset": {
            "title": "Read offset (number of data rows to skip)",
            "minimum": 0,
            "type": "integer",
            "description": "Default 0 skips no data rows. Read only; applied before maxItems. Read mode: number of data rows to skip after the header before reading, e.g. 100 to continue after a previous run's first 100 rows. Applied before maxItems. Default 0. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": 0
          },
          "columns": {
            "title": "Columns to keep (array of names)",
            "type": "array",
            "description": "Omitted keeps all columns. Read headers or write keys; excludeColumns applies afterward. Only output/write these columns (read: sheet header names; write modes: item keys, 'a' also keeps 'a/b'), in this order, e.g. ['Name', 'Email']. Read metadata fields are always included. Default: all columns. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "items": {
              "type": "string"
            }
          },
          "excludeColumns": {
            "title": "Columns to exclude (array of names)",
            "type": "array",
            "description": "Omitted excludes none. Applied after columns in reads and writes. Columns to drop in every mode (read: sheet header names; write: item keys, 'a' also drops 'a/b'), e.g. ['internalId']. Applied after 'columns'. Default: none. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "items": {
              "type": "string"
            }
          },
          "headerRow": {
            "title": "Header row number: 1 or greater",
            "type": "integer",
            "description": "Default 1 uses the first selected-range row as read headers. Read only; offset skips subsequent data rows. 1-based header row within the selected read range, e.g. 2 when its first row is a title. Accepts integers 1 or greater; default 1. Rows before it are skipped. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": 1
          },
          "serviceAccountKey": {
            "title": "Secret Google service-account JSON key",
            "type": "string",
            "description": "Omitted supports public reads; private reads and writes need a key and sheet sharing. Write access errors follow onWriteError. Full service-account JSON key file as a string, e.g. a JSON document containing client_email and private_key. Never paste credentials into prompts or public output. Omit for public reads. For private reads/writes, share the sheet with client_email as Viewer/Editor. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "datasetId": {
            "title": "Source Apify dataset ID",
            "type": "string",
            "description": "Omitted uses integration resource.defaultDatasetId if present. Write source; rawData takes precedence when both are supplied. Apify dataset ID whose items are written to the sheet in write modes, e.g. 'aBcD1234efGH5678', or '{{resource.defaultDatasetId}}' in an integration. Empty in an integration run: the triggering run's default dataset is used. Use this or rawData. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "rawData": {
            "title": "Rows to write (JSON array of objects)",
            "type": "array",
            "description": "Omitted uses datasetId/integration dataset. Write source; takes precedence over datasetId. JSON array of objects to write instead of a dataset, e.g. [{\"url\": \"https://a.example\", \"title\": \"A\"}]. Each object becomes one sheet row; keys become columns. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError."
          },
          "dedupeFields": {
            "title": "Dedupe key columns (array of names)",
            "type": "array",
            "description": "Omitted performs no dedupe in other modes; required for append-dedupe. Uses output column names after flattenNested. Column names that identify a row in append-dedupe mode, e.g. ['url']. Rows whose values already exist in the sheet (or earlier in the batch) are skipped. Required for append-dedupe. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "items": {
              "type": "string"
            }
          },
          "columnsOrder": {
            "title": "Column order (array of names)",
            "type": "array",
            "description": "Omitted uses first-seen key order. Write only; applies when the tab has no existing header. Fixed header order when the tab has no header yet, e.g. ['title', 'url']. Remaining keys follow in first-seen order. Default: first-seen order. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "items": {
              "type": "string"
            }
          },
          "flattenNested": {
            "title": "Flatten nested objects and arrays: true or false",
            "type": "boolean",
            "description": "Default true flattens write objects/arrays into path columns; false uses JSON text. Read ignores this. Whether to flatten nested write values, e.g. true converts {\"address\":{\"city\":\"Prague\"}} to an 'address/city' column and arrays to 'tags/0'. false writes nested values as JSON text. Default true. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": true
          },
          "escapeFormulas": {
            "title": "Store formula-like text safely: true or false",
            "type": "boolean",
            "description": "Default true stores formula-like write text safely. Interacts with valueInputOption; read ignores this. Whether to prefix write strings starting with =, +, - or @ with an apostrophe, e.g. true stores '=SUM(A1)' as text. false allows Google to interpret these strings with USER_ENTERED. Default true. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": true
          },
          "valueInputOption": {
            "title": "Google value parsing: USER_ENTERED or RAW",
            "enum": [
              "USER_ENTERED",
              "RAW"
            ],
            "type": "string",
            "description": "Default USER_ENTERED lets Google parse write values; RAW retains sent values. escapeFormulas still applies. Read ignores this. Google write parsing, e.g. 'RAW' to retain values as sent or 'USER_ENTERED' to parse numbers/dates like typing in Sheets. escapeFormulas still applies when enabled. Default USER_ENTERED. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": "USER_ENTERED"
          },
          "dryRun": {
            "title": "Preview writes without changes: true or false",
            "type": "boolean",
            "description": "Default false writes rows. True previews without writing; read ignores this. Preview rows are uncharged. Whether to plan write rows without changing the sheet, e.g. true for a preview. Preview items have _dryRun: true; rowsWritten is 0. Read mode ignores this setting. Default false. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": false
          },
          "onWriteError": {
            "title": "Write failure handling: preview or fail",
            "enum": [
              "preview",
              "fail"
            ],
            "type": "string",
            "description": "Default preview returns uncharged planned rows with _dryRun and _writeError if write access fails. fail preserves the explicit failure contract. Action when write authentication or sheet access fails, e.g. 'preview' returns planned rows with _dryRun: true and _writeError; nothing is written. 'fail' ends the run with an error. Check OUTPUT.rowsWritten to confirm writes. Default preview. Uses maxItems row budget; bad/blocked/empty reads succeed with 0 items; write errors follow onWriteError.",
            "default": "preview"
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}