# How to Make a Developer Knowledge REST API Call: Complete Guide

> Learn to make Developer Knowledge REST API calls. Authenticate with gcloud or API key, then POST or GET to endpoints like answerQuery for programmatic Google documentation access.

- Repository: [Google/skills](https://github.com/google/skills)
- Tags: how-to-guide
- Published: 2026-09-02

---

**To execute a Developer Knowledge REST API call, authenticate using a gcloud bearer token or API key, then POST or GET to `https://developerknowledge.googleapis.com/v1` endpoints such as `:answerQuery` or `documents:searchDocumentChunks` to retrieve Google documentation programmatically.**

The Google Skills repository provides a direct HTTP fallback for querying technical documentation when Model Context Protocol (MCP) tools are unavailable. By making a **Developer Knowledge REST API call** to the `developerknowledge.googleapis.com` endpoint, you can perform natural language queries, retrieve specific documents, or batch-fetch multiple resources. This implementation is documented in [`skills/developers/retrieving-developer-knowledge/SKILL.md`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md) and the REST specification in [`references/api-fallback.md`](https://github.com/google/skills/blob/main/references/api-fallback.md).

## Understanding the Developer Knowledge REST API

The service exposes a single base URL—**`https://developerknowledge.googleapis.com/v1`**—that supports four primary operations when MCP alternatives (`search_documents`, `get_documents`, `answer_query`) are inaccessible. Unlike the MCP interface, this REST fallback requires explicit credential management and direct HTTP client configuration.

The four supported operations are:

- **Answer Query** (`POST /v1:answerQuery`) – Accepts natural language questions and returns synthesized answers
- **Search Document Chunks** (`GET /v1/documents:searchDocumentChunks`) – Retrieves relevant documentation fragments for short keyword queries (2–5 terms)
- **Get Document** (`GET /v1/documents/{document-id}`) – Returns the full content of a specific document by ID
- **Batch Get Documents** (`POST /v1/documents:batchGet`) – Fetches multiple documents in a single request

## Authentication Methods

Before executing any Developer Knowledge REST API call, you must configure authentication using one of two supported flows documented in the skill's credential handling logic.

### Active gcloud Credentials (Preferred)

The recommended method uses the active gcloud CLI session. Retrieve a bearer token using `gcloud auth print-access-token` and include the `X-Goog-User-Project` header to ensure proper quota attribution against your project. If this token returns a 401 or 403 error, fall back to the application-default credentials via `gcloud auth application-default print-access-token`.

### API Key Authentication

For environments without gcloud CLI, set the `DEVELOPERKNOWLEDGE_API_KEY` environment variable and pass the key as a query parameter (`?key=YOUR_KEY`). This method is ideal for automated scripts but may have different rate limiting than OAuth-based requests.

## Core API Operations and Examples

Each operation requires a specific HTTP method and endpoint path. The following examples demonstrate proper request formatting using `curl`.

### Answer Query

Use the `:answerQuery` endpoint for natural language questions. This operation requires a POST request with a JSON payload containing the query string.

```bash
curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-User-Project: $(gcloud config get-value project 2>/dev/null)" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I configure public read access on Cloud Storage?"}'

```

If the above returns 401 or 403, retry with the application-default token:

```bash
curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I configure public read access on Cloud Storage?"}'

```

Alternatively, use API key authentication:

```bash
curl -s -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=${DEVELOPERKNOWLEDGE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I configure public read access on Cloud Storage?"}'

```

### Search Document Chunks

For targeted keyword searches, use the `documents:searchDocumentChunks` endpoint with a GET request. This returns specific fragments rather than synthesized answers.

```bash
curl -s "https://developerknowledge.googleapis.com/v1/documents:searchDocumentChunks?query=gcloud+logging+metrics+create&key=${DEVELOPERKNOWLEDGE_API_KEY}"

```

### Get Document

Retrieve a complete document by its resource identifier using the `documents/{document-id}` path. This is optimal when you know the exact documentation URL.

```bash
curl -s "https://developerknowledge.googleapis.com/v1/documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run?key=${DEVELOPERKNOWLEDGE_API_KEY}"

```

### Batch Get Documents

Fetch multiple documents efficiently by POSTing to `documents:batchGet` with an array of document names in the request body.

```bash
curl -s -X POST "https://developerknowledge.googleapis.com/v1/documents:batchGet?key=${DEVELOPERKNOWLEDGE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"names": ["documents/docs.cloud.google.com/run/docs/overview/what-is-cloud-run","documents/docs.cloud.google.com/storage/docs/public-access"]}'

```

## Error Handling and Credential Fallback

Robust implementations must handle authentication failures gracefully. According to [`skills/developers/retrieving-developer-knowledge/SKILL.md`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md), implement the following fallback sequence:

1. Attempt authentication with `gcloud auth print-access-token`
2. On 401/403 errors, retry with `gcloud auth application-default print-access-token`
3. If both OAuth methods fail, verify the `DEVELOPERKNOWLEDGE_API_KEY` environment variable and switch to API key authentication

Validate that successful responses contain the expected payload fields: `answer` for query operations, or `document`/`documents` for retrieval endpoints. Treat any missing fields or non-200 status codes as lookup failures.

## Summary

- The **Developer Knowledge REST API** base URL is `https://developerknowledge.googleapis.com/v1`
- **Authentication** supports gcloud bearer tokens (preferred) with the `X-Goog-User-Project` header, or API keys via the `key` query parameter
- **Primary operations** include `:answerQuery`, `documents:searchDocumentChunks`, `documents/{id}`, and `documents:batchGet`
- **Credential fallback** requires retrying with application-default tokens when primary gcloud tokens fail with 401/403 errors
- Implementation details are defined in [`skills/developers/retrieving-developer-knowledge/SKILL.md`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md) and [`references/api-fallback.md`](https://github.com/google/skills/blob/main/references/api-fallback.md)

## Frequently Asked Questions

### What is the base URL for the Developer Knowledge REST API?

The base URL is `https://developerknowledge.googleapis.com/v1`. All endpoints extend from this path, including `:answerQuery` for natural language queries and `documents:searchDocumentChunks` for keyword searches.

### How do I authenticate if gcloud CLI is not available?

Export your API key to the `DEVELOPERKNOWLEDGE_API_KEY` environment variable and append `?key=$DEVELOPERKNOWLEDGE_API_KEY` to your request URLs. This method requires no OAuth flow or gcloud installation.

### When should I use searchDocumentChunks instead of answerQuery?

Use `searchDocumentChunks` for precise, short keyword queries (2–5 terms) requiring specific documentation fragments. Use `answerQuery` for broad, natural language questions that require synthesized answers from multiple documentation sources.

### Where are the official REST fallback examples documented?

The canonical curl examples and authentication flows are documented in [`skills/developers/retrieving-developer-knowledge/references/api-fallback.md`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/references/api-fallback.md) within the `google/skills` repository, with additional workflow details in [`skills/developers/retrieving-developer-knowledge/SKILL.md`](https://github.com/google/skills/blob/main/skills/developers/retrieving-developer-knowledge/SKILL.md).