- [HTTP request](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.request_body)
  - [JSON representation](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.request_body.SCHEMA_REPRESENTATION)
- [Response body](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.RankResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.aspect)
- [IAM Permissions](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#body.aspect_1)
- [RankingRecord](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord)
  - [JSON representation](https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord.SCHEMA_REPRESENTATION)

Ranks a list of text records based on the given input query.

### HTTP request

Choose an endpoint:
global us   
`POST https://discoveryengine.googleapis.com/v1alpha/{rankingConfig=projects/*/locations/*/rankingConfigs/*}:rank`

<br />

The URLs use [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `rankingConfig` | `string` Required. The resource name of the rank service config, such as `projects/{projectNum}/locations/{location}/rankingConfigs/default_ranking_config`. |

### Request body

The request body contains data with the following structure:

| JSON representation |
|---|
| ``` { "model": string, "topN": integer, "query": string, "records": [ { object (`https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord`) } ], "ignoreRecordDetailsInResponse": boolean, "userLabels": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `model` | `string` The identifier of the model to use. It is one of: - `semantic-ranker-512@latest`: Semantic ranking model with maximum input token size 512. It is set to `semantic-ranker-512@latest` by default if unspecified. |
| `topN` | `integer` The number of results to return. If this is unset or no bigger than zero, returns all results. |
| `query` | `string` The query to use. |
| `records[]` | ``object (`https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord`)`` Required. A list of records to rank. |
| `ignoreRecordDetailsInResponse` | `boolean` If true, the response will contain only record ID and score. By default, it is false, the response will contain record details. |
| `userLabels` | `map (key: string, value: string)` The user labels applied to a resource must meet the following requirements: - Each resource can have multiple labels, up to a maximum of 64. - Each label must be a key-value pair. - Keys have a minimum length of 1 character and a maximum length of 63 characters and cannot be empty. Values can be empty and have a maximum length of 63 characters. - Keys and values can contain only lowercase letters, numeric characters, underscores, and dashes. All characters must use UTF-8 encoding, and international characters are allowed. - The key portion of a label must be unique. However, you can use the same key with multiple resources. - Keys must start with a lowercase letter or international character. See [Google Cloud Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements) for more details. |

### Response body

Response message for `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#google.cloud.discoveryengine.v1alpha.RankService.Rank` method.

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "records": [ { object (`https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord`) } ] } ``` |

| Fields ||
|---|---|
| `records[]` | ``object (`https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord`)`` A list of records sorted by descending score. |

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/cloud-platform`
- `https://www.googleapis.com/auth/discoveryengine.readwrite`
- `https://www.googleapis.com/auth/discoveryengine.serving.readwrite`

For more information, see the [Authentication Overview](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

### IAM Permissions

Requires the following [IAM](https://cloud.google.com/iam/docs) permission on the `rankingConfig` resource:

- `discoveryengine.rankingConfigs.rank`

For more information, see the [IAM documentation](https://cloud.google.com/iam/docs).

## RankingRecord

Record message for `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#google.cloud.discoveryengine.v1alpha.RankService.Rank` method.

| JSON representation |
|---|
| ``` { "id": string, "title": string, "content": string, "score": number } ``` |

| Fields ||
|---|---|
| `id` | `string` The unique ID to represent the record. |
| `title` | `string` The title of the record. Empty by default. At least one of `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord.FIELDS.title` or `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord.FIELDS.content` should be set otherwise an INVALID_ARGUMENT error is thrown. |
| `content` | `string` The content of the record. Empty by default. At least one of `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord.FIELDS.title` or `https://docs.cloud.google.com/gemini/enterprise/docs/reference/rest/v1alpha/projects.locations.rankingConfigs/rank#RankingRecord.FIELDS.content` should be set otherwise an INVALID_ARGUMENT error is thrown. |
| `score` | `number` The score of this record based on the given query and selected model. The score will be rounded to 4 decimal places. If the score is close to 0, it will be rounded to 0.00001 to avoid returning unset. |