# API Usage

### Authentication and Relocation Tokens

After logging in, Over VPS authentication uses Access Tokens. The Access Token does not expire by itself, but you can regenerate it to invalidate the previous token.

The Access Token is required to generate a Relocation Token (reloc-token). The Relocation Token lasts for one hour and can be used to perform relocations and use other apis.

#### Access Tokens

* Purpose: Authenticate API requests to the Over VPS endpoints.
* Token lifecycle: Non-expiring in theory, but you should rotate (regenerate) tokens to revoke old ones and reduce risk.
* Regeneration: In your account settings, you can generate a new Access Token. Regenerating a token invalidates the previous one. After regenerating, use the new token for subsequent API calls.

#### Relocation Tokens (reloc-token)

* Purpose: Used to execute relocation operations on VPS instances.
* Lifetime: 1 hour from generation.
* Usage: Generate a reloc-token using a valid Access Token, then use the reloc-token to perform relocations within its lifetime.

#### Generating a reloc-token

* Endpoint: POST `https://vps.ovr.ai/api/vps/generate-reloc-token`
* Required header:
  * Access-Token: YOUR\_ACCESS\_TOKEN
* Example command (use your actual Access Token; do not share real tokens publicly):

```
curl --location --request POST 'https://vps.ovr.ai/api/vps/generate-reloc-token'
--header 'Access-Token: YOUR_ACCESS_TOKEN'
```

#### Regenerating a reloc-token with an Existing reloc-token

It is possible to generate a new reloc-token using an existing, unexpired reloc-token. The new reloc-token will extend your ability to perform relocations for the next hour.

* Endpoint: POST `https://vps.ovr.ai/api/vps/generate-reloc-token`
* Required header:
  * Reloc-Token: YOUR\_EXISTING\_RELOC\_TOKEN
* Response: A new reloc-token (and its expiry time). Use the new token for subsequent relocations.

```
curl --location --request POST 'https://vps.ovr.ai/api/vps/generate-reloc-token'
--header 'Reloc-Token: YOUR_EXISTING_RELOC_TOKEN'
```

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

### Get a model (mapping) for the VPS

* Purpose: retrieve the list of available mapping models for a given geographic area.\
  The returned models can later be loaded and used for VPS relocation operations.
* Endpoint: GET `https://vps.ovr.ai/api/vps/get-models`
* Query parameters:
  * `latitude` (float, required): latitude of the area of interest.
  * `longitude` (float, required): longitude of the area of interest.
* Headers:
  * Access-Token: YOUR\_ACCESS\_TOKEN

Example request:

```
curl --location 'https://vps.ovr.ai/api/vps/get-models?latitude=46.092748&longitude=13.231052'
--header 'Access-Token: YOUR_ACCESS_TOKEN'
```

### Load a model (mapping) for the VPS

* This step loads a model (mapping) that can be used by the VPS. The calls are authenticated with your reloc-token.
* Use the modelName (UUID) of the model you want to load, and specify the operation type (run or check).
* When you load or check, you will receive JSON responses indicating success and the model status.

#### Load the model (run)

* Purpose: load or initialize the model on the VPS so it can be used.
* Endpoint: POST `https://inference.ovr.ai/load-model`
* Headers:
  * Authorization: YOUR\_RELOC\_TOKEN

```
curl --location --request POST 'https://inference.ovr.ai/load-model'
--header 'Authorization: YOUR_RELOC_TOKEN'
--header 'Content-Type: application/json'
--form 'modelName="mapping_uuid"'--form 'type="run"'
```

#### Check if the model is loaded

* Purpose: verify whether the requested model is loaded and ready.
* Endpoint: POST `https://inference.ovr.ai/load-model`
* Headers:
  * Authorization: YOUR\_RELOC\_TOKEN

```
curl --location --request POST 'https://inference.ovr.ai/load-model'
--header 'Authorization: YOUR_RELOC_TOKEN'
--header 'Content-Type: application/json'
--form 'modelName="mapping_uuid"' --form 'type="check"'
```

### Relocate (execute relocation) using a loaded model

* This step performs an actual relocation (realignment) of a VPS using the loaded model. The API call is authenticated with your tokens, and you provide the model to relocate and the image to align.
* The response indicates whether the relocation happened and provides quality metrics and the resulting transformation.

#### API call

* Endpoint: POST `https://inference.ovr.ai/reloc`
* Headers:
  * Authorization: YOUR\_RELOC\_TOKEN

```
curl --location 'https://inference.ovr.ai/reloc'
--header 'Authorization: eyJhbGciOiJIUzI1NiJ9.eyJ1dWlkIjoiNzVlODkyMTAtYWY0NC0xMWViLWEzN2ItMDAxNjNlMDA1M2Y3IiwibWludXRlX2xpbWl0IjozLCJtb250bHlfbGltaXQiOm51bGwsInRvdGFsX2xpbWl0IjoxMDAwLCJ0b3RhbF9yZXNldF90aW1lIjoxNzY3MjI1NjAwLCJleHAiOjE3Njk3MDM3MDF9.CzXu9waM78L2_yc7SlvkNb9SJzjncjG8tlWZWrCiVds'
--form 'modelName="mapping_uuid"'
--form 'files=@"/path/to/your/image.jpg"' 
```

#### API Response

```json
{
    "relocated": true,
    "confidence": 1,
    "rotation": [
        0.9656321620605589,
        0.08099126911018109,
        0.24498222638860218,
        0.031283392972234154
    ],
    "translations": [
        -0.1027658376185608,
        1.8155874701079697,
        -0.7958327256135492
    ],
    "inliers_total": 3490,
    "inliers_valid": 2210
}
```


---

# 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://docs.overthereality.ai/over-wiki/over-vps/api-usage.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.