Skip to content

Resource names

The full name of every Sutra resource, and the rules for ids.

Every resource has a name: its full path, starting with its project. Responses return only full names. Requests may write the project part shorter.

Formats

All names start with the project:

tenants/{tenant}/organizations/{organization}/projects/{project}

The rest of the name depends on the resource:

Resource Name after the project
Sandbox sandboxes/{sandbox}
Process sandboxes/{sandbox}/processes/{process}
Port sandboxes/{sandbox}/ports/{port}
SSH access sandboxes/{sandbox}/sshAccess
Template templates/{template}
Template version templates/{template}/versions/{version}
Snapshot snapshots/{snapshot}
Volume volumes/{volume}
Operation operations/{operation}
Agent agents/{agent}
Agent revision agents/{agent}/revisions/{revision}
Session agents/{agent}/sessions/{session}
Service services/{service}
Service revision services/{service}/revisions/{revision}

A port’s id is its port number, so port 3000 of the sandbox demo is sandboxes/demo/ports/3000. A sandbox has one SSH access resource, so its name has no id.

The SDKs take the short id where the parent is clear, as in sutra.sandboxes.get("demo") or sandbox.ports.get(3000), and return the full name in name.

Shorter forms

Your API key belongs to one organization. A request can leave out the parts of a name that the key already gives:

Written Means
projects/{project}/sandboxes/{sandbox} The sandbox in a project of your organization.
organizations/{organization}/projects/{project}/sandboxes/{sandbox} The sandbox in a project of that organization.
tenants/{tenant}/organizations/{organization}/projects/{project}/sandboxes/{sandbox} The full name.

A project on its own can also be written as its id, {project}. Every field that takes a name accepts these forms, and so does the path of every REST call. Two spellings of one resource are the same resource, so a request repeated under another spelling is the same request.

Ids

You choose the id when you create a resource, or leave it out and Sutra assigns one. An assigned id is a short prefix for the kind of resource, a hyphen and 12 lowercase letters and digits, such as sbx-k3f9x2m7q4h8. A create repeated with the same requestId gets the same id.

  • An id is 1 to 63 characters from A-Z, a-z, 0-9, ., _, ~ and -.
  • The rule is the same for every resource.
  • An id is unique among its siblings. Once the delete of a resource has completed, you can reuse its id.

Every resource also has a uid that Sutra assigns and never reuses. Use it when you need to tell apart two resources that had the same name at different times.

Host names, such as a port’s address, are never made from ids, so an id does not show up in a URL.

Type to search…

↑↓ navigate↵ selectEsc close