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

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 and the REST specification in 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.

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:

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:

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.

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.

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.

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, 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 and 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 within the google/skills repository, with additional workflow details in skills/developers/retrieving-developer-knowledge/SKILL.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}