---
title: "Resource names"
description: "The full name of every Sutra resource, and the rules for ids."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.jgcp.mistrivedev.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Resource names

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:

```text
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.

:::note[Today]
Today responses return names that start with `organizations/{organization}/projects/{project}`.

A port is a `preview binding` today, named `sandboxes/{sandbox}/previewBindings/{key}`, and SSH access is named `sandboxes/{sandbox}/accessBindings/{key}`. Sutra assigns ids to sandboxes (`sbx-`), apps (`app-`), volumes (`vol-`) and snapshots (`snap-`). The id of a deleted sandbox cannot be used again.

The SDKs take a bare id for a sandbox, an app, a volume or a snapshot when the client has a `project`. The CLI takes a sandbox by its id and a process or a port as `<sandbox>/<id>`.

A port's host is made from the sandbox id, the port's key and its number. See [Ports](https://docs.jgcp.mistrivedev.com/sandboxes/ports/).
:::

Source: https://docs.jgcp.mistrivedev.com/reference/resource-names/index.mdx
