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

# Resource paths

> Human-readable references for resources across the API and CLI

A resource path is a human-readable, colon-separated reference for a resource. Resource paths let
you reference resources across the API and CLI without memorizing IDs.

Not every resource has a resource path. You reference resources like [orders](https://docs.sfcompute.com/preview/orders.md),
which have no user-settable name, by ID only.

## Format

Most resource paths take 1 of 2 forms.

```text theme={null}
sfc:<type>:<organization>:<workspace>:<name>     # workspace-scoped
sfc:<type>:<organization>:<name>                 # organization-scoped
```

The `sfc:` prefix identifies the resource as belonging to SF Compute. The hierarchy moves from
broader scope (left) to narrower scope (right). Each segment contains only letters, numbers, and the
characters `.`, `_`, and `-`, so a colon always marks a segment boundary. Colons are URL-safe, so
resource paths can appear directly in URL path parameters without encoding.

## Examples by resource type

| Resource | Scope | Resource path |
| - | - | - |
| Pool | workspace | `sfc:pool:acme:production:training-pool` |
| Instance | workspace | `sfc:instance:acme:production:trainer-1` |
| Instance template | workspace | `sfc:instance_template:acme:production:gpu-worker` |
| Image | workspace | `sfc:image:acme:production:cuda-12-7` |
| Workspace | organization | `sfc:workspace:acme:production` |

## IDs vs resource paths

Every resource has a stable ID (e.g., `pool_k3R-nX9vLm7Qp2Yw5Jd8F`). IDs never change for the
lifetime of the resource. The API derives resource paths from the resource's name, workspace, and
organization, so they change when any of those change. If you rename a pool from `training-pool` to
`inference-pool`, its ID stays the same but its resource path changes.

Use IDs for automation and integrations that need stable references. Use resource paths for
convenience in the CLI and ad-hoc API calls.

API responses include both.

```json theme={null}
{
  "object": "pool",
  "id": "pool_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:pool:acme:production:training-pool",
  "workspace": {
    "id": "wksp_7Yb-Ht2mNq4Rx8Wc1Ke5P",
    "name": "production"
  },
  "name": "training-pool"
}
```

## Using resource paths in the CLI

The CLI accepts resource paths wherever you would use a name.

```bash theme={null}
# Get an instance from another workspace by resource path
sf instances get sfc:instance:acme:staging:worker-1

# Transfer compute across workspaces using resource paths
sf pools transfers create \
  --from sfc:pool:acme:ml-team:unallocated \
  --to sfc:pool:acme:inference-team:unallocated \
  --count 10 \
  --start-at "tomorrow" \
  --duration 7d \
  --sku sku_4UpxzQw7A8N
```

## Using resource paths in the API

Anywhere the API accepts a resource ID, it also accepts a resource path. This includes path
parameters, request body fields, and query parameters. The API resolves a resource path to the
underlying ID before processing the request. These 2 requests are equivalent.

```http theme={null}
GET /v2/pools/pool_k3R-nX9vLm7Qp2Yw5Jd8F
GET /v2/pools/sfc:pool:acme:production:training-pool
```

Resource paths also work in request bodies that reference other resources. This is useful for
cross-workspace references, where you can target a resource in another workspace without switching
context. Fields that reference resources without user-settable names, like `sku`, take IDs only. For
example, this `POST /v2/instances` body references a pool and an image in another workspace by
resource path.

```json theme={null}
{
  "pool": "sfc:pool:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7",
  "sku": "sku_9Fd-Lz6pQw3Vn1Ay8Rk4T"
}
```

## Next steps

* [Workspaces](https://docs.sfcompute.com/preview/workspaces.md) explains the workspace layer that scopes most resource paths.
* [Pools](https://docs.sfcompute.com/preview/pools.md) covers the pools these examples reference.
* [Using the API](https://docs.sfcompute.com/preview/using-the-api.md) covers authentication and request basics.
