Resource paths - San Francisco Compute Docs

This feature is in public preview.

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, 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.

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

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

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

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.

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

​Format

​Examples by resource type

​IDs vs resource paths

​Using resource paths in the API

​CLI usage

Format

Examples by resource type

IDs vs resource paths

Using resource paths in the API

CLI usage