sf-api

name	sf-api
description	Raw REST API and GraphQL requests via sf CLI. Use for custom endpoints, GraphQL queries/mutations, and arbitrary HTTP calls to Salesforce APIs.

sf api Operations

Commands for making raw API requests to Salesforce. These are essential for calling custom Apex REST endpoints, GraphQL queries/mutations, or any Salesforce API not covered by a dedicated sf data or sf project command.

[!NOTE] Both commands are currently in beta. The --json global flag is NOT supported consistently on these commands. sf api request rest --json is rejected by CLI 2.140.6; sf api request graphql --json can exit 0 with no stdout. Prefer raw output, --include, --stream-to-file, and shell piping (| python3 -m json.tool or | jq) for formatted output.

sf api request rest

Make an authenticated HTTP request using the Salesforce REST API. Authentication is handled automatically from the target org credentials.

# GET request - describe an object
sf api request rest "/services/data/v66.0/sobjects/Account/describe" \
  --target-org myOrg

# GET request - query record count
sf api request rest "/services/data/v66.0/limits/recordCount" \
  --target-org myOrg

# POST request - create a record via REST
sf api request rest "/services/data/v66.0/sobjects/Account" \
  --target-org myOrg \
  --method POST \
  --header "Content-Type:application/json" \
  --body '{"Name":"Test Account"}'

# Call a custom Apex REST endpoint
sf api request rest "/services/apexrest/ugent/v1/status" \
  --target-org myOrg \
  --method GET

# POST to custom Apex REST with body
sf api request rest "/services/apexrest/ugent/v1/session" \
  --target-org myOrg \
  --method POST \
  --header "Content-Type:application/json" \
  --body '{"org_id":"00D...","user_id":"005..."}'

# PATCH request - update record fields
sf api request rest "/services/data/v66.0/sobjects/Account/001..." \
  --target-org myOrg \
  --method PATCH \
  --header "Content-Type:application/json" \
  --body '{"Name":"Updated Name"}'

# DELETE request
sf api request rest "/services/data/v66.0/sobjects/Account/001..." \
  --target-org myOrg \
  --method DELETE

# Stream response to file (for large responses)
sf api request rest "/services/data/v66.0/sobjects/Account/describe" \
  --target-org myOrg \
  --stream-to-file account-describe.json

# Read body from stdin
echo '{"Name":"Pipe Account"}' | sf api request rest \
  "/services/data/v66.0/sobjects/Account" \
  --target-org myOrg \
  --method POST \
  --header "Content-Type:application/json" \
  --body -

Flags

Flag	Description
[URL]	Salesforce API endpoint (relative to instance URL)
-o, --target-org	Target org (required)
-X, --method	HTTP method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE
-H, --header	HTTP header in key:value format (repeatable)
-b, --body	Body content, @file to read from file, - for stdin, "" for empty
-f, --file	JSON file with header, body, method, and URL values
-S, --stream-to-file	Stream response to file
-i, --include	Include HTTP status and headers in output

URL patterns

The URL is relative to the org's instance URL:

• /services/data/v66.0/sobjects/{Object}/{Id} - SObject REST
• /services/data/v66.0/query?q=... - REST SOQL
• /services/data/v66.0/search?q=... - REST SOSL
• /services/data/v66.0/composite - Composite API
• /services/data/v66.0/composite/tree/{Object} - SObject Tree
• /services/apexrest/{path} - Custom Apex REST endpoints

sf api request graphql

Execute a GraphQL query or mutation against the Salesforce GraphQL API.

# Query accounts
sf api request graphql \
  --target-org myOrg \
  --body 'query { uiapi { query { Account { edges { node { Id Name { value } } } } } } }'

# Query with variables from stdin
echo '{"query":"query($id:ID!){uiapi{query{Account(filter:{Id:{eq:$id}}){edges{node{Name{value}}}}}}}","variables":{"id":"001..."}}' \
  | sf api request graphql \
  --target-org myOrg \
  --body -

# Mutation - create a record
sf api request graphql \
  --target-org myOrg \
  --body 'mutation { uiapi { AccountCreate(input:{Account:{Name:"GraphQL Account"}}){Record{Id Name{value}}} } }'

# Read query from file
sf api request graphql \
  --target-org myOrg \
  --body query.graphql

Flags

Flag	Description
-o, --target-org	Target org (required)
--body	GraphQL statement (required): inline text, file path, or - for stdin
--api-version	Override API version
-S, --stream-to-file	Stream response to file
-i, --include	Include HTTP status and headers in output

GraphQL tips

• API version 52.0+ required for GraphQL API
• The response wraps data in uiapi namespace
• Record fields return { value } objects, not raw values
• Mutations support Create, Update, Delete suffixes on object names
• Use @file to load complex queries from .graphql files

Output handling

Unlike most other sf commands, sf api does not consistently support --json. The REST or GraphQL response body is output directly, usually as JSON. To parse:

# Pretty-print JSON output
sf api request rest "/services/data/v66.0/sobjects/Account/describe" \
  --target-org myOrg | python3 -m json.tool

# Extract a field with jq
sf api request rest "/services/data/v66.0/sobjects/Account/describe" \
  --target-org myOrg | jq '.fields | length'

# Save to file
sf api request rest "/services/data/v66.0/sobjects/Account/describe" \
  --target-org myOrg > account-describe.json