Add sources

September 29, 2026 (October 15, 2026)

Table of contents

  1. Request Headers
  2. Request Body
  3. Source kinds and statuses
  4. Responses
  5. Model
  6. Examples
  7. Try It

Add sources to a notebook: web pages, YouTube videos, pasted text, files from Google Drive and ebooks from the account’s Google Play Books library, in one call. Sources are what chat answers from and what Studio artifacts are generated from.

To add a file (PDF, Word, PowerPoint, EPUB, Markdown, text, CSV, audio, video or an image) use POST /sources/upload. Create the notebook first with POST /notebooks.

Google processes every new source before it can be used. The response carries each source’s current status, and GET /notebooks/notebook shows it later. Chat and Studio use only sources whose status is ready.

How many sources a notebook can hold depends on the account’s Google plan. GET /accounts/email shows it as limits.sourcesPerNotebook.

https://api.useapi.net/v1/gemini-notebook/sources

Request Headers 
Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data
Request Body 
{
  "notebook": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55",
  "urls": [
    "https://en.wikipedia.org/wiki/Apollo_11",
    "https://www.nasa.gov/mission/apollo-11/",
    "https://www.youtube.com/watch?v=xUcYQ7slmRw"
  ],
  "text": "Three minutes before landing, Eagle's computer raised a 1202 alarm...",
  "title": "Why Apollo 11 almost did not land"
}
  • notebook is required, the notebook id returned by POST /notebooks or GET /notebooks. The id names its account, so no email is needed.
  • urls is optional, an array of 1 to 50 http(s) URLs. A URL on youtube.com (any subdomain) or youtu.be is added as a YouTube source, any other URL as a web page. Google reads a YouTube video from its captions. A video with no captions at all, which happens with some official music videos, ends with status: "error" and its URL as the title, and Google gives no reason (September 2026). Upload the audio or video file with POST /sources/upload instead, and Google transcribes it.
    With multipart/form-data, urls carries a single URL.
  • text is optional, pasted text added as one text source.
    Maximum length: 500,000 characters.
  • title is optional, the title of the text source. Sending title without text returns 400.
    Default: Pasted text. Maximum length: 200 characters.

  • drive is optional, an array of 1 to 50 Google Drive files, each { fileId, mimeType, name }. All three fields are required. fileId is the Drive file id, mimeType its MIME type, and name (up to 200 characters) becomes the source’s title. A Google Doc has the MIME type application/vnd.google-apps.document and is added as kind google_docs. A .docx or .pptx from Drive is added as kind drive. Send the file’s exact MIME type: in our tests a Google Doc sent with the .docx type was added as a plain drive file that cannot sync, and a generic type such as application/octet-stream left the source stuck in preparing. The account must be able to open the file in its Google Drive, otherwise the API answers 409. drive needs a JSON body.
    Example: [{ "fileId": "1Qx7Lm2VtR8pKc4NwE9bYs3HfJ6uGdA0zT5iOv1eWnXk", "mimeType": "application/vnd.google-apps.document", "name": "Apollo 11 landing notes" }]

  • books is optional, an array of 1 to 20 Google Play Books ids from GET /sources/books. Each book is added as one source of kind book holding the whole ebook. The account must own the book, and its publisher must allow it (addable: true). A book that is not in the account’s library returns 404, and a book Google does not allow returns 422. In both cases nothing is added.
    Example: ["-OQ2q5JqOdEC"]

Provide urls, text, drive, books or any combination. Books are added after the other sources. If a book fails after other sources were added, the error message lists what was already added.

A Drive source is a copy of the file as it was when added. GET /sources/source shows whether it still matches the file (inSync), and POST /sources/sync re-imports it after a change.

Source kinds and statuses

Every source object carries a kind (what Google made of it) and a status. The same values appear on sources added via POST /sources/upload and listed by GET /notebooks/notebook.

kind Source
web Web page URL
youtube YouTube video URL
text Pasted text, or an uploaded .txt file
pdf PDF file
docx Word document
pptx PowerPoint presentation
epub EPUB e-book
markdown Markdown file, a note converted with POST /notes/source, or a Deep Research report added with POST /research/import
csv CSV file
media Audio or video file (e.g. .mp3, .mp4)
image Image file (e.g. .jpg)
google_docs A Google Doc from Google Drive (drive parameter)
drive A Google Drive file that is not a Google Doc, such as a .docx or .pptx (drive parameter)
book An ebook from the account’s Google Play Books library (books parameter)

A kind Google adds later is returned as kind<N>, with Google’s own number.

status Meaning
preparing The file was received and is waiting to be processed. New uploads start here.
processing Google is reading the source.
ready The source can be used by chat and Studio.
error Google could not process the source.

An unrecognised status is returned as status<N>.

Responses

  • 201 Created

    One entry per source added.

    {
  "notebook": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55",
  "sources": [
    {
      "source": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55:c1182943-b7f0-4e89-82bc-8b3614cfb78f",
      "title": "Apollo 11 - Wikipedia",
      "kind": "web",
      "status": "ready",
      "words": 25492,
      "url": "https://en.wikipedia.org/wiki/Apollo_11",
      "created": "2026-09-27T23:24:43.000Z"
    },
    {
      "source": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55:f8e48390-9349-485d-b816-38649a28aa5d",
      "title": "Apollo 11 - NASA",
      "kind": "web",
      "status": "ready",
      "words": 2639,
      "url": "https://www.nasa.gov/mission/apollo-11/",
      "created": "2026-09-27T23:24:43.000Z"
    },
    {
      "source": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55:9732772d-0111-447b-ba78-9eec2c1c2ffe",
      "title": "A New Look at the Apollo 11 Landing Site",
      "kind": "youtube",
      "status": "ready",
      "words": 13,
      "url": "https://www.youtube.com/watch?v=xUcYQ7slmRw",
      "created": "2026-09-27T23:24:43.000Z"
    },
    {
      "source": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55:bd69e802-65bf-4ee7-9088-d9ee5724204c",
      "title": "Why Apollo 11 almost did not land",
      "kind": "text",
      "status": "ready",
      "words": 90,
      "created": "2026-09-27T23:24:43.000Z"
    }
  ]
}

  • 400 Bad Request

    A missing or malformed parameter, nothing to add, or title without text.

    {
  "error": "Provide urls, text, drive and/or books",
  "code": 400
}

  • 401 Unauthorized

    Invalid API token.

    {
  "error": "useapi.net ⁝ Unauthorized",
  "code": 401
}

  • 403 Forbidden

    The notebook id was issued to a different API token.

    {
  "error": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55 does not belong to this API token",
  "code": 403
}

  • 404 Not Found

    The account named in the notebook id is no longer configured, Google no longer has the notebook, or a books id is not in the account’s Google Play Books library.

    {
  "error": "Account [email protected] of user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55 is not configured",
  "code": 404
}

  • 409 Conflict

    A drive file the account cannot open: it is not in the account’s Google Drive and not shared with it.

    {
  "error": "Google refused the request in the item's current state (izAoDd grpc 9)",
  "code": 409
}

  • 422 Unprocessable Content

    A books id Google does not allow as a source. GET /sources/books lists it with addable: false.

    {
  "error": "Google does not allow these books as sources: Hfn4AAAAQBAJ \"The Raven (Illustrated)\" (the publisher opted out)",
  "code": 422
}

  • 596 Account Error

    Google reported the account as signed out. While we re-check it, the answer is the first message below. Retry in about a minute. If it stays signed out, the account is paused, you receive an email, and the answer becomes the second message until you re-add it via Setup Gemini Notebook.

    {
  "error": "Google reported this account as signed out. We are re-checking it — please retry in about a minute. If it stays signed out, you will receive a re-add email.",
  "code": 596
}

    {
  "error": "Account [email protected]: Google signed this account out. Re-add it at https://useapi.net/docs/start-here/setup-gemini-notebook",
  "code": 596
}

  • 503 Service Unavailable

    Google is temporarily unavailable or is challenging our network. Retry in a few minutes. A 502 means Google answered with an unexpected error.

    {
  "error": "Google is temporarily unavailable (izAoDd grpc 14), please retry",
  "code": 503
}
Model 
{ // TypeScript, all fields are optional
  notebook: string            // user:<id>-<email>-notebook:<uuid>
  sources: {
    source: string            // user:<id>-<email>-source:<notebook uuid>:<source uuid>
    title: string
    kind: string              // see Source kinds above
    status: string            // preparing | processing | ready | error
    words?: number            // word count, once Google has read the source
    url?: string              // web page or YouTube URL
    mimeType?: string         // file sources
    driveFileId?: string      // Google Drive sources: the Drive file id
    created?: string          // ISO 8601
  }[]
}
Examples 
  • curl -X POST "https://api.useapi.net/v1/gemini-notebook/sources" \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer …" \
   -d '{
     "notebook": "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55",
     "urls": ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"],
     "text": "Three minutes before landing, Eagle'\''s computer raised a 1202 alarm...",
     "title": "Why Apollo 11 almost did not land"
   }'

  • const token = "API token";
const notebook = "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55";
const apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources";
const response = await fetch(apiUrl, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    notebook,
    urls: ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"],
    text: "Three minutes before landing, Eagle's computer raised a 1202 alarm...",
    title: "Why Apollo 11 almost did not land"
  })
});
const result = await response.json();
console.log("response", {response, result});

  • import requests
token = "API token"
notebook = "user:[email protected]:d02c903b-17f8-4241-a263-2be9e7359d55"
apiUrl = "https://api.useapi.net/v1/gemini-notebook/sources"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
data = {
    "notebook": notebook,
    "urls": ["https://en.wikipedia.org/wiki/Apollo_11", "https://www.youtube.com/watch?v=xUcYQ7slmRw"],
    "text": "Three minutes before landing, Eagle's computer raised a 1202 alarm...",
    "title": "Why Apollo 11 almost did not land"
}
response = requests.post(apiUrl, headers=headers, json=data)
print(response, response.json())
Try It