Browse a connected Google Drive

documents.google_files

GET/api/v1/households/{household_id}/documents/google/files

Route

Lists one page of a Google Drive folder through a connected Google Drive account, folders first and then by name, 100 to a page. parent_id is root (My Drive), shared (Shared with me) or a folder's Drive ID. Refused with 404 integration_not_found (not connected, or not a Google Drive account), 409 integration_needs_reconnect (Google no longer accepts Rigel's access; reconnect in settings) or 502 provider_failed (Google could not be reached or answered with an error; try again).

Parameters#

Browse a connected Google Drive: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`integration_id`querystringrequired	The connected Google Drive account.
`parent_id`querystringoptional	root, shared, or the Drive ID of the folder to list. pattern ^(root\|shared\|[A-Za-z0-9_-]{1,200})$Default `"root"`
`page_token`querystringoptional	The next_page_token of the previous page. 1 to 4,000 characters

Response#

200 One page of the folder.

Browse a connected Google Drive: response fields
Field	Description
`items`array of objectsrequired	One page, folders first and then by name.
`items[].id`stringrequired	The Drive file's ID, to pass to `documents.google.import`.
`items[].name`stringrequired	The file's name in Drive.
`items[].kind`one of: folder, google_doc, filerequired	folder, google_doc (a Google Doc, imported as a document) or file (anything else, imported as a file).
`items[].mime_type`stringrequired	Drive's media type, such as application/pdf or application/vnd.google-apps.folder.
`items[].modified_at`integerrequired	When it last changed in Drive, UTC milliseconds (0 if Drive didn't say).
`items[].size`integer or nullrequired	Size in bytes; null for Google's own formats, which have none.
`next_page_token`string or nullrequired	Pass as page_token for the next page; null on the last.

Errors#

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

Browse a connected Google Drive: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	Read error.code	Described above.
`502`	Read error.code	Described above.

Examples#

These are real. Each was recorded from a sample household, the Okafors, running through the whole API when this site was built.

Browse a connected Google Drive

One page of a Drive folder, folders first. parent_id is root, shared or a folder's Drive ID.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTBJ85CVWQJBRMQ9BWS0

{
  "items": [
    {
      "id": "1pYk4VsT0nQe7HwXz2cLrJd8uGmA5bFoI",
      "name": "Okafor family",
      "kind": "folder",
      "mime_type": "application/vnd.google-apps.folder",
      "modified_at": 1794064671686,
      "size": null
    },
    {
      "id": "1Qa8LsWe4DnYr2KtZc6VbMx0JhUfG9oTp",
      "name": "Household budget",
      "kind": "file",
      "mime_type": "application/vnd.google-apps.spreadsheet",
      "modified_at": 1794064671687,
      "size": null
    }
  ],
  "next_page_token": null
}

Open a folder in Drive

The Drive ID of a folder from the last page goes in parent_id; ids of files go to documents.google.import.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42&parent_id=1pYk4VsT0nQe7HwXz2cLrJd8uGmA5bFoI' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42&parent_id=1pYk4VsT0nQe7HwXz2cLrJd8uGmA5bFoI", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01M6V9CSTQDH5WHAHGST73CA42&parent_id=1pYk4VsT0nQe7HwXz2cLrJd8uGmA5bFoI HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CTBP7G8HE57HNPC8AQC2

{
  "items": [
    {
      "id": "1Hn6VcBy8RtKq4LxZe2WjDs9PaFuM3gOi",
      "name": "Chore chart",
      "kind": "google_doc",
      "mime_type": "application/vnd.google-apps.document",
      "modified_at": 1794064671686,
      "size": null
    },
    {
      "id": "1Ek3TuXo9MvAc5RbNy7LwHq2ZdJgS8fPi",
      "name": "Insurance card.pdf",
      "kind": "file",
      "mime_type": "application/pdf",
      "modified_at": 1794064671687,
      "size": 29
    },
    {
      "id": "1Zr7NwQd3LhEc9KtYb5XvMp2JaUgS0fTo",
      "name": "Visit with Grandma Okafor",
      "kind": "google_doc",
      "mime_type": "application/vnd.google-apps.document",
      "modified_at": 1794064671686,
      "size": null
    }
  ],
  "next_page_token": null
}

Browse an account that isn't Drive

Only a connected Google Drive account can be browsed.

Request, curl

curl 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01JC0000000000000000000000' \
  -H "Cookie: rigel_session=$RIGEL_SESSION"

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01JC0000000000000000000000", {
  headers: {
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
});
const data = await response.json();

Request, HTTP

GET /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/documents/google/files?integration_id=int_01JC0000000000000000000000 HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01M6V9CTBT08Y9YB8AK473PXNK

{
  "error": {
    "code": "integration_not_found",
    "message": "That Google Drive account isn't connected.",
    "details": {},
    "recovery": "Connect Google Drive first.",
    "request_id": "req_01M6V9CTBT08Y9YB8AK473PXNK"
  }
}