---
title: "Create a hosted Google Picker session"
method: POST
path: "/v1/files/picker-sessions"
tags: ["Files"]
---

# Create a hosted Google Picker session

`POST /v1/files/picker-sessions`

## Request

- Base URL: `https://zernio.com/api`
- URL: `https://zernio.com/api/v1/files/picker-sessions`
- Auth: HTTP bearer

Creates a hosted Google Picker session so your end user can grant Zernio access to Drive files.

Google accounts are connected with `drive.file`, so Zernio opens only files it created or the user picked (see the Files tag).

1. Create a session.
2. Send the user to `url`.
3. They pick files in Google Picker on a Zernio-hosted page.

### Redirect

When they finish, the browser is sent to `redirectUrl` with these query params added (existing params are kept):

- `status=picked`, `pickerSessionId`, `fileIds` (comma-separated Drive file ids, already checked against Drive), or
- `status=cancelled`, `pickerSessionId` when the user pressed Cancel.

A `file.picked` webhook fires on every successful pick, so `redirectUrl` is optional for server-side integrations. Closing the picker without picking keeps the session open; the user can try again until it expires.

### Limits

- The URL is single-use and expires after 30 minutes; create a new session for every pick.
- Google accounts only: Microsoft accounts answer 400 `platform_not_supported` because OneDrive needs no picker.
- Picks are permanent grants: once picked, a file stays readable through the Files endpoints until the user removes Zernio from their Google account.

## Request body

- object
  - `accountId` string, required: A Google account connected with `scopes=files`.
  - `redirectUrl` string, uri: Where the browser goes when the user finishes. Absolute `http(s)` URL or a custom app scheme (`myapp://...`); relative, protocol-relative and script URLs are refused. Optional when you rely on the `file.picked` webhook.
  - `fileIds` string[]: Drive file ids to show the user first (Google Picker `DocsView.setFileIds`), for example to ask for access to files your app already knows about. Pre-navigation only: the user still has to pick them.
  - `mimeTypes` string[]: Only show files of these exact media types.
  - `multiselect` boolean: false limits the pick to one file.

## Response `201`

The session

- object
  - `data` FilePickerSession
    - `id` string, required: Public session id, echoed as `pickerSessionId` on the redirect and as `picker.sessionId` on the webhook.
    - `url` string, uri, required: The hosted picker page. Open it in the end user's browser (redirect or new tab, not an iframe). It is a credential: single-use and valid until `expiresAt`.
    - `expiresAt` string, date-time, required: 30 minutes after creation.

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key. `code` is `missing_credentials` when no Authorization header was sent and `invalid_credentials` when the key is unknown, revoked or expired.
- `404`: Resource not found
- `412`: The connected account cannot serve this request until something outside the request changes. Two codes: - `account_scope_missing`: the account was connected without the area this endpoint needs (`details.grantedAreas`, `details.missingArea`), or Google reports the grant lacks a permission. Reconnect with a wider `scopes=`. - `admin_consent_required` (Microsoft): the tenant requires an administrator's approval. `details.adminConsentUrl` is the Microsoft Entra admin-consent link to hand to one; it opens in a browser with no API key and stays valid for one hour. `GET /v1/connect/microsoft/admin-consent` mints a fresh one.

## Changes

- **2026-10-27** `0a24331f5431`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/files/picker-sessions/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) - [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) - [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/c319eb5d95b6?raw)