Search and retrieve documents

This document shows you how to use the Developer Knowledge API to programmatically search and retrieve Google's public developer documentation. Instead of manually scraping web pages, the API helps your applications find relevant text snippets or fetch full Markdown documents.

In this document, you'll find examples for the following tasks:

Searching the documentation corpus.
Paginating through search results.
Applying complex filters to your search.
Retrieving full document content.
Optimizing response payloads to reduce latency.

Before you begin, set up your environment for your preferred tool:

gcloud

Install and configure the gcloud CLI, and enable the Developer Knowledge API.

REST

Enable the API and generate a Developer Knowledge API key. Then, save your key to an environment variable:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Replace YOUR_API_KEY with your Developer Knowledge API key.

Search for documents

Use the gcloud developer-knowledge documents search-chunks command or the documents.searchDocumentChunks REST method to find document chunks that match a query string. The results include chunks of content from matching documents, alongside a parent reference that you can use to retrieve the full content of those documents.

The following example searches for documents matching "BigQuery":

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery"

REST

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&key=$DEVELOPERKNOWLEDGE_API_KEY"

The output is similar to the following:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "BigQuery overview",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z"
      },
      "relevanceScore": 0.92
    }
  ]
}

Each result in the results list includes:

parent: the document resource name (for example, documents/docs.cloud.google.com/bigquery/docs/introduction).
id: the chunk identifier within the document (for example, chunk_0).
content: the matched text snippet from the document.
document: metadata about the source document, such as its title, uri, dataSource, and updateTime.
relevanceScore: the relevance score of the chunk to the search query, in the range [0.0, 1.0].

For more information about the response schema and all available metadata fields, see the documents.searchDocumentChunks API reference.

Paginate search results

When a search query returns multiple matches, you can navigate through the result set using pagination parameters:

--page-size (gcloud CLI) or pageSize (integer): specifies the maximum number of results to return per page. If unspecified, the API defaults to five results. The maximum allowed value is 100; values greater than 100 are coerced to 100.
--limit (gcloud CLI) or pageToken (string): in the gcloud CLI, use --limit to control the total number of results returned across pages. In REST requests, pass the pageToken value received in a previous response to fetch the next page of results.

gcloud

Pass the --page-size and --limit flags to control the number of results per page and the total number of results returned:

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --page-size=5 \
  --limit=10

REST

To request the first page, pass the pageSize parameter in your request:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&key=$DEVELOPERKNOWLEDGE_API_KEY"

If additional results are available, the response includes a nextPageToken:

{
  "results": [
    {
      "parent": "documents/docs.cloud.google.com/bigquery/docs/introduction",
      "id": "chunk_0",
      "content": "BigQuery is a fully managed enterprise data warehouse...",
      "document": {
        "name": "documents/docs.cloud.google.com/bigquery/docs/introduction",
        "uri": "https://docs.cloud.google.com/bigquery/docs/introduction",
        "title": "What is BigQuery?",
        "dataSource": "docs.cloud.google.com",
        "updateTime": "2025-01-15T12:00:00Z",
        "view": "DOCUMENT_VIEW_BASIC"
      },
      "relevanceScore": 0.88
    }
  ],
  "nextPageToken": "CAUQABgB"
}

To retrieve subsequent pages, pass the value of nextPageToken to the pageToken parameter in your next request:
```
curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&pageSize=5&pageToken=CAUQABgB&key=$DEVELOPERKNOWLEDGE_API_KEY"
```
When you reach the last page of results, nextPageToken is omitted from the response.

Filter search results

Use the --query-filter flag in the gcloud CLI or the filter parameter in REST requests to apply a strict filter to search results. The filter expression is applied to the metadata of the parent document for each chunk.

The filter expression has a 500-character limit.

Supported fields

You can filter your search results using the following parent document fields:

content_length_bytes (integer): the length of the document's content field in bytes.
data_source (string): the source domain of the document, such as docs.cloud.google.com or firebase.google.com. See the corpus reference for all supported data sources.
update_time (timestamp): the timestamp when the document was last updated. Values must use RFC 3339 format (for example, "2025-01-01T00:00:00Z").
uri (string): the full URI of the document (for example, https://docs.cloud.google.com/bigquery/docs/tables).

Supported operators

The filter expression parser supports different operators depending on the field's data type:

String fields (data_source, uri): support = (equals) and != (not equals) for exact string matching. Partial, prefix, and regular expression matches aren't supported.
Timestamp fields (update_time): support =, <, <=, >, and >=.
Integer fields (content_length_bytes): support =, !=, <, <=, >, and >=.
Logical operators: combine conditions using AND, OR, and NOT (or -).

Filter examples

The following examples demonstrate how to construct filter expressions. When using the gcloud CLI, pass the expression to the --query-filter flag. When calling the REST API with curl, make sure to URL-encode the filter parameter or use --data-urlencode.

Match a single data source

Restrict search results to a single documentation domain:

data_source = "docs.cloud.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Functions deployment" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Functions deployment" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Match multiple data sources

Use OR to include documents from multiple sources:

data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="database" \
  --query-filter='data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=database" \
  --data-urlencode 'filter=data_source = "docs.cloud.google.com" OR data_source = "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filter by timestamp

Use comparison operators with RFC 3339 timestamps to find content updated after a specific date:

update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="BigQuery" \
  --query-filter='update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=BigQuery" \
  --data-urlencode 'filter=update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Filter by content length

Use comparison operators with content_length_bytes to find documents based on their byte size:

content_length_bytes < 5000

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="Cloud Storage" \
  --query-filter='content_length_bytes < 5000'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=Cloud Storage" \
  --data-urlencode 'filter=content_length_bytes < 5000' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Combine data source, timestamp, and grouping

Combine AND, OR, and parentheses (...) to restrict results to specific sources updated after a given date:

(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="service worker" \
  --query-filter='(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=service worker" \
  --data-urlencode 'filter=(data_source = "developer.chrome.com" OR data_source = "web.dev") AND update_time >= "2025-01-01T00:00:00Z"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Exclude data sources

Use NOT or != to exclude results from a specific source:

data_source != "firebase.google.com"

gcloud

gcloud developer-knowledge documents search-chunks \
  --query="authentication" \
  --query-filter='data_source != "firebase.google.com"'

REST

curl -G "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks" \
  --data-urlencode "query=authentication" \
  --data-urlencode 'filter=data_source != "firebase.google.com"' \
  --data-urlencode "key=$DEVELOPERKNOWLEDGE_API_KEY"

Retrieve a document

Use the gcloud developer-knowledge documents describe command or the documents.get REST method to retrieve the full content of a single document.

The following example retrieves a document by its resource name:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?key=$DEVELOPERKNOWLEDGE_API_KEY"

The response is a Document resource containing metadata and the full Markdown content in the content field.

Resource names versus URIs

When referencing documents in the Developer Knowledge API, note the difference between resource names and web URIs:

Resource name (parent, name): formatted as documents/{uri_without_scheme} (for example, documents/docs.cloud.google.com/storage/docs/creating-buckets). Pass this value as the positional argument in gcloud developer-knowledge documents describe, the path parameter in GetDocument, or in the names parameter of BatchGetDocuments.
Web URI (uri): full web URL including the scheme (for example, https://docs.cloud.google.com/storage/docs/creating-buckets). Use this format for the uri field when constructing --query-filter or filter expressions (for example, uri = "https://docs.cloud.google.com/storage/docs/creating-buckets").

Retrieve multiple documents with `BatchGetDocuments`

Use the documents.batchGet method to retrieve up to 20 documents by name in a single API call. This is more efficient than making multiple GetDocument requests.

The following example retrieves two documents by name:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&key=$DEVELOPERKNOWLEDGE_API_KEY"

The response contains a list of the requested Document resources in the order you requested.

Optimize response payloads

Document content in Markdown format can be large. If your application only needs metadata (such as page titles, URIs, or timestamps) or specific fields, you can optimize payload sizes to reduce bandwidth and latency.

Use document views

The --view flag in the gcloud CLI or the view parameter in REST requests controls which fields are populated in Document messages.

The --view flag and DocumentView enum support the following values:

--view=basic (gcloud CLI) or DOCUMENT_VIEW_BASIC: returns only basic metadata fields (name, uri, dataSource, title, description, updateTime, and view). The content field is omitted.
--view=content (gcloud CLI) or DOCUMENT_VIEW_CONTENT: returns metadata fields along with the Markdown content field. This is the default for gcloud developer-knowledge documents describe, GetDocument, and BatchGetDocuments.
--view=full (gcloud CLI) or DOCUMENT_VIEW_FULL: returns all document fields.

To retrieve only document metadata without downloading large Markdown content, specify the basic document view:

gcloud

gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets \
  --view=basic

REST

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

You can also use view=DOCUMENT_VIEW_BASIC with BatchGetDocuments:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&names=documents/firebase.google.com/docs/firestore/quickstart&view=DOCUMENT_VIEW_BASIC&key=$DEVELOPERKNOWLEDGE_API_KEY"

Use field masks

To further limit response payloads to specific fields, use the standard Google APIs fields query parameter (field mask).

Filter fields in `GetDocument`

To retrieve only the title, uri, and updateTime fields of a document:

curl "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/storage/docs/creating-buckets?fields=title,uri,updateTime&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filter fields in `BatchGetDocuments`

To retrieve only specific fields for each document in a batch:

curl "https://developerknowledge.googleapis.com/v1/documents:batchGet?names=documents/docs.cloud.google.com/storage/docs/creating-buckets&fields=documents(name,title,uri)&key=$DEVELOPERKNOWLEDGE_API_KEY"

Filter fields in `SearchDocumentChunks`

To return only the chunk id and content, parent document title and uri, and the nextPageToken from a search:

curl "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=BigQuery&fields=results(id,content,document(title,uri)),nextPageToken&key=$DEVELOPERKNOWLEDGE_API_KEY"

Handle errors

The Developer Knowledge API returns standard HTTP status codes. The following functional examples map HTTP status codes and their causes in the Developer Knowledge API:

400 INVALID_ARGUMENT:
- The filter expression string exceeds 500 characters.
- The update_time timestamp is invalid (must use RFC 3339 format).
- More than 20 document names were provided in a BatchGetDocuments request.
401 UNAUTHENTICATED: the request is missing an API key or uses an invalid key. See Authentication.
404 NOT_FOUND: the requested document name does not exist or belongs to a domain that isn't included in the corpus.
429 RESOURCE_EXHAUSTED: the project has exceeded its quota. See Quota and limits.

What's next

Refer to Generate answers from documentation.
Connect to the Developer Knowledge MCP server and install the retrieving-developer-knowledge agent skill to help your AI coding assistant search and read official documentation.
Explore how to use client libraries in Python, Node.js, Go, or Java.
Explore how to use the gcloud CLI.
Browse the corpus reference to view all supported documentation sources.
Review the REST API reference for complete method specifications.
Check quota and limits for API rate limits and quotas.

Search and retrieve documents Stay organized with collections Save and categorize content based on your preferences.

gcloud

REST

Search for documents

gcloud

REST

Paginate search results

gcloud

REST

Filter search results

Supported fields

Supported operators

Filter examples

Match a single data source

gcloud

REST

Match multiple data sources

gcloud

REST

Filter by timestamp

gcloud

REST

Filter by content length

gcloud

REST

Combine data source, timestamp, and grouping

gcloud

REST

Exclude data sources

gcloud

REST

Retrieve a document

gcloud

REST

Resource names versus URIs

Retrieve multiple documents with BatchGetDocuments

Optimize response payloads

Use document views

gcloud

REST

Use field masks

Filter fields in GetDocument

Filter fields in BatchGetDocuments

Filter fields in SearchDocumentChunks

Handle errors

What's next

Search and retrieve documents

Retrieve multiple documents with `BatchGetDocuments`

Filter fields in `GetDocument`

Filter fields in `BatchGetDocuments`

Filter fields in `SearchDocumentChunks`