Skip to content
Rigel docs
Open Rigel

Import from Google Drive

documents.google.import

POST/api/v1/households/{household_id}/commands/documents.google.import

  • Command
  • Rigel runs it
  • Waits for the server

Imports chosen Google Drive folders and files as documents. Folders are recreated, Google Docs become Markdown (or HTML when Markdown would lose something), other files come over as files, and anything already imported is skipped. Returns the import's ID straight away; the work happens in the background and the import's progress is on its document_import row. Refused with integration_not_found (not connected, or not a Google Drive account) or folder_not_found.

Parameters#

Import from Google Drive: parameters
FieldDescription
household_idpathstringrequired

The household's ID.

Idempotency-Keyheaderstringoptional

The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Import from Google Drive: request body fields
FieldDescription
integration_idstringrequired

The connected Google Drive account.

google_file_idsarray of stringsrequired

The Drive folders or files to import.

1 to 500 items
folder_idstringoptional

The folder to put them in; leave out for the top level.

Response#

200 The command was applied.

Import from Google Drive: response fields
FieldDescription
resultobjectrequired

What the command returned, such as the IDs it created.

result.import_idstringrequired

The new import; its progress is on its row.

versionintegerrequired

The household version after the command.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Import from Google Drive: errors
StatusCodeWhen
400validation_failedA field is missing, misspelled or out of range. details.fields lists each problem.
401unauthenticatedThe request has no valid session.
404folder_not_foundA folder that is gone.
404integration_not_found
  • An integration that isn't connected.
  • An integration for another service.
404not_foundThe household doesn't exist, or you aren't a member of it.
409idempotency_key_reusedThe Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

One file starts one run

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0ANGC2VWWH053NFT4

{
  "result": {
    "import_id": "dim_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A destination folder is kept

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc",
    "def"
  ],
  "folder_id": "fld_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
      "def",
    ],
    folder_id: "fld_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc",
    "def"
  ],
  "folder_id": "fld_01JC0000000000000000000001"
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0QP9FJVYDV78VQYCY

{
  "result": {
    "import_id": "dim_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

An ID chosen twice is imported once

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc",
    "abc"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
      "abc",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc",
    "abc"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0QW8ZJABDJTAHT9VV

{
  "result": {
    "import_id": "dim_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

Thirty items start two runs

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "f00",
    "f01",
    "f02",
    "f03",
    "f04",
    "f05",
    "f06",
    "f07",
    "f08",
    "f09",
    "f10",
    "f11",
    "f12",
    "f13",
    "f14",
    "f15",
    "f16",
    "f17",
    "f18",
    "f19",
    "f20",
    "f21",
    "f22",
    "f23",
    "f24",
    "f25",
    "f26",
    "f27",
    "f28",
    "f29"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "f00",
      "f01",
      "f02",
      "f03",
      "f04",
      "f05",
      "f06",
      "f07",
      "f08",
      "f09",
      "f10",
      "f11",
      "f12",
      "f13",
      "f14",
      "f15",
      "f16",
      "f17",
      "f18",
      "f19",
      "f20",
      "f21",
      "f22",
      "f23",
      "f24",
      "f25",
      "f26",
      "f27",
      "f28",
      "f29",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "f00",
    "f01",
    "f02",
    "f03",
    "f04",
    "f05",
    "f06",
    "f07",
    "f08",
    "f09",
    "f10",
    "f11",
    "f12",
    "f13",
    "f14",
    "f15",
    "f16",
    "f17",
    "f18",
    "f19",
    "f20",
    "f21",
    "f22",
    "f23",
    "f24",
    "f25",
    "f26",
    "f27",
    "f28",
    "f29"
  ]
}
Response, 200
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0T38FDXJMVEZC0S11

{
  "result": {
    "import_id": "dim_01JC4N0000MBGE5RJ6Q7V6V6T8"
  },
  "version": 1
}

A folder that is gone

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ],
  "folder_id": "fld_01JC0000000000000000000001"
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
    ],
    folder_id: "fld_01JC0000000000000000000001",
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ],
  "folder_id": "fld_01JC0000000000000000000001"
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0AW609NCPMXFSQADW

{
  "error": {
    "code": "folder_not_found",
    "message": "That folder isn't there any more. No changes were applied.",
    "details": {
      "folder_id": "fld_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0AW609NCPMXFSQADW"
  }
}

An integration that isn't connected

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0T70KGB0H0VY2ESWB

{
  "error": {
    "code": "integration_not_found",
    "message": "That Google Drive account isn't connected. No changes were applied.",
    "details": {
      "integration_id": "int_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0T70KGB0H0VY2ESWB"
  }
}

An integration for another service

Request, curl
curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}'
Request, TypeScript
const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    integration_id: "int_01JC0000000000000000000001",
    google_file_ids: [
      "abc",
    ],
  }),
});
const data = await response.json();
Request, HTTP
POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/documents.google.import HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "integration_id": "int_01JC0000000000000000000001",
  "google_file_ids": [
    "abc"
  ]
}
Response, 404
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0310364V5J8PRGY6Z

{
  "error": {
    "code": "integration_not_found",
    "message": "That Google Drive account isn't connected. No changes were applied.",
    "details": {
      "integration_id": "int_01JC0000000000000000000001"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0310364V5J8PRGY6Z"
  }
}

For Rigel#

Rigel's tool for this command is documents_google_import. Rigel runs this on its own, then says what it did. The agent guide has the rest.

Rigel is in early access, and sign-up is by invitation. Open Rigel