# Rank

The *`Rank`* allows you to have multiple documents under the same Key and [Context](/mspro.services/endpoints/documents/document-properties/context.md)

<figure><img src="/files/c6arMvFwTr8LwERq8czF" alt=""><figcaption><p>Pic 1: Ranked documents</p></figcaption></figure>

{% hint style="info" %}
**It is recommended to always provide `Rank=0`**&#x66;or all operations,\
unless you know what you are doing and you definitely want to use ranking.
{% endhint %}

{% tabs %}
{% tab title="POST" %}

### POST - Update or insert with Rank

#### POST without an explicit Rank

If you POST a document without providing an explicit *`Rank`* this is always an *insert*, and a new document is created with the next available rank (highest rank +1). With reference to *Pic 1* the next Rank would be 5 +1 = 6.&#x20;

```http
POST {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice
Content-Type: application/json
Authorization: Basic {{basic}}

{
  "InvoiceId" : "Inv002.6",  
  "Firstname": "Markus",  
  "Lastname" : "Schmidt2" 
}
```

<figure><img src="/files/gfoEw0xnB764oqECdVLG" alt=""><figcaption></figcaption></figure>

#### POST with an explicit Rank

If you provide a specific *Rank*, an existing document is updated. A new document is created, if there is a no document with that Rank (insert).

```http
POST .../docs/content?key=MSPro.Test.Invoice&Rank=6
```

{% endtab %}

{% tab title="GET" %}

### GET - Specific or latest

#### GET without an explicit Rank

```http
GET {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice
Content-Type: application/json
Authorization: Basic {{basic}}
```

If you don't provide an explicit *Rank* the document with the highest Rank is returned - which is considered to be the latest/current document.

#### GET with an explicit Rank

If you provide a explicit *Rank*, of course, that document is returned. In case there is no document with the specified *Rank* you will get `HTTP/1.1 404 Not Found`.
{% endtab %}

{% tab title="DELETE" %}
For deletion the same is true as for GET: if you don't provide an explicit Rank, the document with the highest Rank is affected. If you provide a Rank, that document is deleted or you receive a http-404 in case there is no document with that rank.
{% endtab %}
{% endtabs %}

## Minimum Rank

You can optionally provide a `MinRank` to control the next rank that is created. Normally, the next rank is highest available rank +1. If you provide a `MinRank` the next rank is minimum that number.

Example: Imagine the highest rank for document of Key="MSPro.Test.Invoice" is 5. You POST a new document with that Key - omitting an explicit rank - but providing a `MinRank` of 10. Then a next document created will have Rank=10 (not 6!).

```http
POST {{host}}/{{accountId}}/docs/content?key=MSPro.Test.Invoice&MinRank=20
Content-Type: application/json
Authorization: Basic {{basic}}

{
  "InvoiceId" : "Inv002.20",  
  "Firstname": "Markus",  
  "Lastname" : "Schmidt2" 
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://services.markusschmidt.pro/mspro.services/endpoints/documents/document-properties/rank.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.