> ## 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

<Warning>
  This feature is in [public preview](/preview/roadmap).
</Warning>

A resource path (RP) is a human-readable, colon-separated reference for a resource. Resource paths
provide a convenient way to reference resources across the API and CLI without memorizing IDs.

Only resources with user-settable names have resource paths. Resources like
[orders](/preview/orders), which don't have user-assigned names, are referenced by ID only.

## Format

```
sfc:<type>:<account>:<workspace>:<name>              # workspace-scoped
sfc:<type>:<account>:<name>                          # account-scoped
```

The `sfc:` prefix identifies the resource as belonging to SF Compute. The hierarchy moves from
broader scope (left) to narrower scope (right). 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`           |
| InstanceTemplate | workspace | `sfc:instance_template:acme:production:gpu-worker` |
| Image            | workspace | `sfc:image:acme:production:cuda-12-7`              |
| Procurement      | workspace | `sfc:procurement:acme:production:auto-refill`      |
| Deployment       | workspace | `sfc:deployment:acme:production:inference`         |
| Workspace        | account   | `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. Resource paths are derived from the resource's name, workspace, and
account, 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",
  "owner": "acme",
  "workspace": "production",
  "name": "training-pool"
}
```

## 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. Resource paths are resolved server-side to
the underlying ID before the request is processed.

Because resource paths change on rename or workspace move, prefer IDs for stored references and
webhooks. Resource paths are best for interactive use and one-off requests.

```bash theme={null}
# These are equivalent
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.

```json theme={null}
POST /v2/instances
{
  "workspace": "production",
  "pool": "sfc:pool:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7"
}
```

```json theme={null}
POST /v2/orders
{
  "pool": "sfc:pool:acme:staging:batch",
  "side": "buy",
  "node_count": 4,
  "start_at": 1738972800,
  "end_at": 1739059200,
  "limit_price_dollars_per_node_hour": "20.00"
}
```

### CLI usage

The CLI accepts resource paths wherever a name is expected.

```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 \
  --node-count 10 \
  --start-at "tomorrow" \
  --end-at "in 7d"
```