list available locations.md

List available Locations

Management API · Locations

GET https://app.mk.io/api/v1/locations

Listing, Sorting and Filtering Locations

This endpoint returns the list of locations.

Sorting

The results from this endpoint can be ordered using the $orderby query parameter. Specify a list of field names, separated by commas where each one can optionally specify asc or desc.

Sorting is valid on the following fields: displayName, id, name

Filtering

The $filter query parameter allows for locations to be filtered on the basis of fields in the schema using OData query syntax. See this document for more details on the syntax used.

Filters are valid on the following fields: cloud/name, cloud/region/name, displayName, id, name

Examples:

?$top=10 - Returns only the first 10 locations from the list.

?$orderby=name desc - Sorts locations by name in descending order.

?$filter=name eq 'descriptive name' - Returns locations that match the provided name.

RBAC Capability Required: core.location.get

Authentication

Authorization header — Bearer authentication of the form Bearer <token>.

Query parameters

Name	Type	Required	Description
`$orderby`	string	No	Specifies the key by which the result collection should be ordered.
`$filter`	string	No	Restricts the set of items returned.
`$top`	string	No	Specifies a non-negative integer `n` that limits the number of items returned from a collection.
`$skiptoken`	string	No	Specifies a start offset to support paginated results. Use `@odata.nextLink` in the result object to enumerate the collection - it will be present only if there's more than one page of entities.

Example request

curl -X GET "https://app.mk.io/api/v1/locations" \
  -H "Authorization: Bearer <token>"

Responses

200 — A list of locations

kind · string · Optional — The type of the resource.
value · list of objects · Required — A list of Locations
- Array items (object):
  - metadata · object · Required — Metadata.
    - displayName · string · Optional — The display name of the resource
    - id · string · Required · format: uuid — The ID of the resource
    - name · string · Optional — The name of the resource
  - spec · object · Required — Specification.
    - cloud · object · Optional — Cloud.
      - displayName · string · Required — The display name of the cloud.
      - name · string · Optional — The unique name of the cloud.
      - region · object · Optional — Cloud region.
        
        displayName · string · Required — The display name of the cloud region.
        
        name · string · Optional — The name of the cloud region (unique within the cloud).
    - organization · object · Optional — Organization information if applicable.
      - id · string or null · Optional · format: uuid — ID of the organization.
      - name · string · Required — Name of the organization.
    - type · enum · Required — Is the location one that is usable only by your organization?
      - Allowed values: SaaS, Dedicated

400 — Bad Request

error · object · Required — Pertinent information about the error
- code · string · Required — The error code.
- detail · string · Required — The error message.
- extraDetail · map from strings to any · Optional — Extra information regarding this error.
  - [any key] · any — map of additional properties
ref · string · Required — A reference to the request that caused the error.
status · integer · Required — The HTTP status code

401 — Unauthorized

403 — Forbidden

404 — Not Found

429 — Too Many Requests

500 — Internal Server Error

Source spec: management-api · operationId: [get]_/api/v1/locations