# 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="https://122322679-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fkyf19U064qDKiwqcT3EU%2Fuploads%2FQjjQVYmRjAbhlYOvAxmb%2FScreenshot%202026-01-29%20alle%2013.03.15.png?alt=media&#x26;token=f4d6cd76-f2aa-4494-9a26-9df1ccf3f9b1" 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
}
```