Resource paths - San Francisco Compute Docs

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, which have no user-settable name, by ID only.

Format

Most resource paths take 1 of 2 forms.

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`
Deployment	workspace	`sfc:deployment:acme:production:inference`
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.

{
  "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.

# 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" \
  --end-at "in 7d" \
  --instance-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.

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.

{
  "pool": "sfc:pool:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7",
  "sku": "sku_9Fd-Lz6pQw3Vn1Ay8Rk4T"
}

Next steps

Workspaces explains the workspace layer that scopes most resource paths.
Pools covers the pools these examples reference.
Using the API covers authentication and request basics.

​Format

​Examples by resource type

​IDs vs resource paths

​Using resource paths in the CLI

​Using resource paths in the API

​Next steps