Machines of the connected account, ranked against one server

GET

/marketplaces/links/candidates

const url = 'https://api.flotera.com/api/v1/marketplaces/links/candidates?server_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&marketplace=vast';
const options = {
  method: 'GET',
  headers: {cookie: '__Host-erm_session=<__Host-erm_session>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.flotera.com/api/v1/marketplaces/links/candidates?server_id=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&marketplace=vast' \
  --cookie __Host-erm_session=<__Host-erm_session>

Asks the marketplace which machines the account owns and says, for each of them, which facts about this server they agree on. This endpoint exists because automatic binding turned out to be impossible for the reason nobody expected: the platform does not hand the host its machine number. On Vast the file that looks like it holds one holds machine_api_key instead, and the number arrives from their server at registration and is never written down. So the number is known only to the platform, and the only way to get it is to ask. What comes back is evidence, not a score. A percentage cannot be checked by the person reading it; “hostname, address and GPU agree, the disk does not” can. The count is there to order the list, and the choice stays with the operator — suggested highlights a row, it never binds anything. The platform is queried live, without a cache: this is a rare, human-initiated action, and a list served from yesterday would offer to bind a machine the owner has already removed.

Authorizations

sessionCookie
pat

Parameters

Query Parameters

server_id

required

string format: uuid

The server the candidates are ranked against.

marketplace

required

string

Allowed values: vast clore

Responses

200

Candidates, strongest first.

application/json

object

candidates

required

Array<object>

<= 512 items

object

external_machine_id

required

string

<= 128 characters

hostname

string | null

<= 253 characters

gpu

string | null

<= 128 characters

gpu_count

integer | null

gpu_occupancy

Card occupancy, one character per card, exactly as the platform prints it. Undocumented on their side, so a string whose length disagrees with the card count means “not understood” and the card map is not drawn at all — an invented layout is worse than none.

string | null

<= 64 characters

linked_server_id

Already bound to this server. Null means the machine is free to take.

string | null format: uuid

evidence

required

Facts that agree, one by one. A missing fact on either side never counts as a match: otherwise two machines nobody knows anything about would look more alike than any real pair.

object

hostname

required

boolean

public_ip

required

boolean

gpu

required

Model and count together — the model alone means little across a fleet of identical cards.

boolean

disk

required

Compared with a wide tolerance: the platform advertises the space it sells, not the size of the drive.

boolean

ports

required

Compared by the SIZE of the range, not its bounds. Two machines behind one router cannot share a range, which would make this the strongest fact of the five — but the platform reports only how many ports a machine has, so neighbours with equally sized ranges stay indistinguishable here.

boolean

matched

required

How many facts agree. Ordering only — the decision is the operator’s, and a number cannot be checked by the person reading it.

integer

<= 5

suggested

required

Enough evidence to highlight the row. Three agreeing facts, not two: hostname and public address are shared by every machine of one owner behind one NAT, so on their own they cannot tell neighbours apart. Highlighting is all it does — nothing is bound without a click.

boolean

known

required

What this side knew about the server while comparing. Shown next to the list, because a list where nothing matches has two very different explanations — the machine is not there, or we know nothing about our own server — and they are indistinguishable from the candidates alone.

object

hostname

string | null

<= 253 characters

public_ip

string | null

<= 45 characters

gpu

string | null

<= 128 characters

gpu_count

integer | null

gpu_occupancy

string | null

<= 64 characters

disk_gb

integer | null

port_range

string | null

<= 32 characters

Example^generated

{
  "candidates": [
    {
      "external_machine_id": "example",
      "hostname": "example",
      "gpu": "example",
      "gpu_count": 1,
      "gpu_occupancy": "example",
      "linked_server_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
      "evidence": {
        "hostname": true,
        "public_ip": true,
        "gpu": true,
        "disk": true,
        "ports": true
      },
      "matched": 1,
      "suggested": true
    }
  ],
  "known": {
    "hostname": "example",
    "public_ip": "example",
    "gpu": "example",
    "gpu_count": 1,
    "gpu_occupancy": "example",
    "disk_gb": 1,
    "port_range": "example"
  }
}

401

Missing/invalid credentials (code=unauthorized).

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

Allowed values: unauthorized forbidden csrf_rejected not_found conflict idempotency_conflict validation_failed rate_limited payload_too_large unsupported_agent_version temporarily_unavailable offline_queue_full online_queue_full plan_required server_limit_reached feature_not_entitled account_in_grace account_frozen payment_pending payment_expired payment_amount_mismatch change_already_pending change_already_applied change_effective reserve_not_covered direction_changed

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

403

Authenticated but not permitted. code=forbidden — role/scope mismatch; code=feature_not_entitled — the plan does not include the capability; code=account_frozen — the account is frozen and this operation is declared x-ermeon-frozen: deny. The three are deliberately distinct: only the last one is fixed by a top-up (13 §5.6).

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

404

Resource does not exist in this tenant. Foreign identifiers also return 404 (anti-enumeration).

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

422

Request failed validation (code=validation_failed), with per-field errors.

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

503

A dependency the endpoint needs is not configured or is temporarily unavailable (code=unavailable). The rest of the API keeps working — an absent external integration must not take the service down.

application/problem+json

RFC 9457 problem document with a stable machine code.

object

type

required

string format: uri

title

required

string

<= 256 characters

status

required

integer

>= 100 <= 599

code

required

Stable machine-readable error code (03 §2.4).

string

detail

string

<= 2048 characters

instance

string

<= 512 characters

request_id

UUID (v7 for new entities; v4 accepted during migration).

string format: uuid

errors

Array<object>

<= 100 items

object

path

required

JSON Pointer to the offending field.

string

<= 512 characters

code

required

string

<= 64 characters

Example

{
  "type": "https://ermeon.com/problems/validation",
  "code": "unauthorized"
}

Machines of the connected account, ranked against one server

Authorizations

Parameters

Query Parameters

Responses

200

Examplegenerated

401

Example

403

Example

404

Example

422

Example

503

Example

Example^generated