// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.developers.knowledge.v1alpha;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";

option go_package = "google.golang.org/genproto/googleapis/developers/knowledge/v1alpha;knowledge";
option java_multiple_files = true;
option java_outer_classname = "DeveloperKnowledgeProto";
option java_package = "com.google.developers.knowledge.v1alpha";

// The Developer Knowledge API provides programmatic access to Google's public
// developer documentation, enabling you to integrate this knowledge base into
// your own applications and workflows.
//
// The API is designed to be the canonical source for machine-readable access to
// Google's developer documentation.
//
// A typical use case is to first use
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks]
// to find relevant page URIs based on a query, and then use
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
// or
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
// to fetch the full content of the top results.
//
// All document content is provided in Markdown format.
service DeveloperKnowledge {
  option (google.api.default_host) = "developerknowledge.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Searches for developer knowledge across Google's developer documentation.
  // Returns [DocumentChunk][google.developers.knowledge.v1alpha.DocumentChunk]s
  // based on the user's query. There may be many chunks from the same
  // [Document][google.developers.knowledge.v1alpha.Document].  To retrieve full
  // documents, use
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // with the
  // [DocumentChunk.parent][google.developers.knowledge.v1alpha.DocumentChunk.parent]
  // returned in the
  // [SearchDocumentChunksResponse.results][google.developers.knowledge.v1alpha.SearchDocumentChunksResponse.results].
  rpc SearchDocumentChunks(SearchDocumentChunksRequest)
      returns (SearchDocumentChunksResponse) {
    option (google.api.http) = {
      get: "/v1alpha/documents:searchDocumentChunks"
    };
  }

  // Retrieves a single document with its full Markdown content.
  rpc GetDocument(GetDocumentRequest) returns (Document) {
    option (google.api.http) = {
      get: "/v1alpha/{name=documents/**}"
    };
    option (google.api.method_signature) = "name";
  }

  // Retrieves multiple documents, each with its full Markdown content.
  rpc BatchGetDocuments(BatchGetDocumentsRequest)
      returns (BatchGetDocumentsResponse) {
    option (google.api.http) = {
      get: "/v1alpha/documents:batchGet"
    };
  }
}

// Request message for
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks].
message SearchDocumentChunksRequest {
  // Required. Provides the raw query string provided by the user, such as "How
  // to create a Cloud Storage bucket?".
  string query = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Specifies the maximum number of results to return. The service
  // may return fewer than this value.
  //
  // If unspecified, at most 5 results will be returned.
  //
  // The maximum value is 20; values above 20 will result in an INVALID_ARGUMENT
  // error.
  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Contains a page token, received from a previous
  // `SearchDocumentChunks` call. Provide this to retrieve the subsequent page.
  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [DeveloperKnowledge.SearchDocumentChunks][google.developers.knowledge.v1alpha.DeveloperKnowledge.SearchDocumentChunks].
message SearchDocumentChunksResponse {
  // Contains the search results for the given query. Each
  // [DocumentChunk][google.developers.knowledge.v1alpha.DocumentChunk] in this
  // list contains a snippet of content relevant to the search query. Use the
  // [DocumentChunk.parent][google.developers.knowledge.v1alpha.DocumentChunk.parent]
  // field of each result with
  // [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
  // or
  // [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments]
  // to retrieve the full document content.
  repeated DocumentChunk results = 1;

  // Optional. Provides a token that can be sent as `page_token` to retrieve the
  // next page. If this field is omitted, there are no subsequent pages.
  string next_page_token = 2 [(google.api.field_behavior) = OPTIONAL];
}

// Request message for
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument].
message GetDocumentRequest {
  // Required. Specifies the name of the document to retrieve.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];
}

// Request message for
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message BatchGetDocumentsRequest {
  // Required. Specifies the names of the documents to retrieve. A maximum of 20
  // documents can be retrieved in a batch. The documents are returned in the
  // same order as the `names` in the request.
  //
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  repeated string names = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];
}

// Response message for
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message BatchGetDocumentsResponse {
  // Contains the documents requested.
  repeated Document documents = 1;
}

// A Document represents a piece of content from the Developer Knowledge corpus.
message Document {
  option (google.api.resource) = {
    type: "developerknowledge.googleapis.com/Document"
    pattern: "documents/{document}"
    plural: "documents"
    singular: "document"
  };

  // Identifier. Contains the resource name of the document.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Provides the URI of the content, such as
  // `docs.cloud.google.com/storage/docs/creating-buckets`.
  string uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Contains the full content of the document in Markdown format.
  string content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides a description of the document.
  string description = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Provides the title of the document.
  string title = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A DocumentChunk represents a piece of content from a
// [Document][google.developers.knowledge.v1alpha.Document] in the
// DeveloperKnowledge corpus. To fetch the entire document content, pass the
// `parent` to
// [DeveloperKnowledge.GetDocument][google.developers.knowledge.v1alpha.DeveloperKnowledge.GetDocument]
// or
// [DeveloperKnowledge.BatchGetDocuments][google.developers.knowledge.v1alpha.DeveloperKnowledge.BatchGetDocuments].
message DocumentChunk {
  // Output only. Contains the resource name of the document this chunk is from.
  // Format: `documents/{uri_without_scheme}`
  // Example: `documents/docs.cloud.google.com/storage/docs/creating-buckets`
  string parent = 1 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {
      type: "developerknowledge.googleapis.com/Document"
    }
  ];

  // Output only. Specifies the ID of this chunk within the document. The chunk
  // ID is unique within a document, but not globally unique across documents.
  // The chunk ID is not stable and may change over time.
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Contains the content of the document chunk.
  string content = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}