Scopes, URLs, and request format

This reference describes how REST API URLs are built, which headers requests and responses carry, and how request and response bodies are formatted. For the operations themselves, see the API reference.

URL structureCopy Anchor Link

A request URL has these parts:

https://<api-host>/api/v1/scopes/<project-id>/<service>/<collection>/<resource-id>/actions/<action>

Some examples:

Encode each path segment that you insert, such as an ID or a name, for use in a URL.

Find a project's IDCopy Anchor Link

The scope ID in a path is the ID of a project. You can find it in two places:

• The console's address. Every page of a project has an address of the form /t/<tenant-id>/s/<subscription-id>/project/<project-id>/…, after the language code. The part after /project/ is the project ID.
• The API. GET /account/whoami returns the tenants, subscriptions, and projects that you can access, with their IDs.

{
  "tenants": [
    {
      "id": "acme",
      "name": "Acme Corp",
      "subscriptions": [
        {
          "id": "acme-production",
          "tenantId": "acme",
          "name": "Production",
          "currency": "TRY",
          "defaultRegion": "ist-1",
          "projects": [
            {
              "id": "acme-production-web-platform",
              "subscriptionId": "acme-production",
              "name": "web-platform",
              "region": "ist-1"
            }
          ]
        }
      ]
    }
  ]
}

Subscription and project IDs don't change when you rename them. Read them from GET /account/whoami instead of deriving them from names.

When you call whoami with an API token or a service account key, it lists only the tenant that the credential belongs to.

ServicesCopy Anchor Link

A size is called a flavor in the API: flavors lists the sizes. A few paths aren't under a project:

A path that matches no service returns 404 Not Found.

MethodsCopy Anchor Link

Request headersCopy Anchor Link

Response headersCopy Anchor Link

Body formatCopy Anchor Link

• JSON. Request and response bodies are JSON. Field names are in camel case, such as deletionProtection or subscriptionId.
• Fields without a value. In a response, an optional field that has no value is left out rather than set to null. A field that the schema always includes is present, and is null when it has no value.
• Timestamps. ISO 8601 strings in UTC, such as 2026-10-08T09:30:00Z.
• IDs. Opaque strings. Use them exactly as the API returns them.
• Lists. A list operation returns { "data": [...], "meta": {...} }. See Pagination.
• Errors. An error response has its own body. See Errors.

AmountsCopy Anchor Link

Amounts of money are integers in ten-thousandths of the currency unit. A field whose name ends in Minor carries such an integer, and a money object carries one in amount, with the currency in currency:

{ "amount": 125000, "currency": "TRY" }

This amount is 12.5 units of its currency: divide by 10,000 to get the amount in the currency unit. Don't read these integers as cents.

ExampleCopy Anchor Link

curl "https://<api-host>/api/v1/scopes/<project-id>/compute/instances?page=1&pageSize=50" \
  -H "Authorization: Bearer $PC_TOKEN"

• <api-host>: the host name of the API.
• <project-id>: the ID of the project.
• PC_TOKEN: an environment variable that holds your API token.

RelatedCopy Anchor Link

• REST API overview
• Authenticate with API tokens
• Pagination
• API reference