Skip to main content

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.

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

ResourceScopeResource path
Capacityworkspacesfc:capacity:acme:production:training-pool
Instanceworkspacesfc:instance:acme:production:trainer-1
InstanceTemplateworkspacesfc:instance_template:acme:production:gpu-worker
Imageworkspacesfc:image:acme:production:cuda-12-7
Procurementworkspacesfc:procurement:acme:production:auto-refill
Deploymentworkspacesfc:deployment:acme:production:inference
Workspaceaccountsfc:workspace:acme:production

​
IDs vs resource paths

Every resource has a stable ID (e.g., cap_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 capacity 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": "capacity",
  "id": "cap_k3R-nX9vLm7Qp2Yw5Jd8F",
  "resource_path": "sfc:capacity: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/capacities/cap_k3R-nX9vLm7Qp2Yw5Jd8F
GET /v2/capacities/sfc:capacity: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",
  "capacity": "sfc:capacity:acme:shared:training-pool",
  "image": "sfc:image:acme:shared:cuda-12-7"
}

POST /v2/orders
{
  "capacity": "sfc:capacity: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 capacity across workspaces using resource paths
sf capacities transfers create \
  --source-capacity sfc:capacity:acme:ml-team:unallocated \
  --destination-capacity sfc:capacity:acme:inference-team:unallocated \
  --node-count 10 \
  --start-at "tomorrow" \
  --end-at "in 7d"