salesforce-api

In Salesforce, every org has its own instance URL (its My Domain), and the API is versioned in the path:

https://<your-org>.my.salesforce.com/services/data/vXX.0/...

Key facts that bite:

• Errors return as a JSON array, success as an object. Guard every jq projection with if type == "array" then . else <projection> end or the error body crashes the filter and you never see errorCode.
• Custom objects and fields end in __c; custom relationship names end in __r (use __r in SOQL parent paths and child subqueries).
• Record IDs are 15- or 18-char alphanumeric. The 18-char form is case-insensitive — prefer it.
• SOQL has no SELECT *. FIELDS(ALL) / FIELDS(CUSTOM) exist but require LIMIT 200.
• Describe is your schema — field names, picklist values, relationship names, and createable/updateable flags. Read it before guessing field names.

Request setup

Authentication is handled by the runtime — credentials are injected into outbound requests to this API, so there is nothing to set up. Do not try to create, mint, refresh, or validate tokens or keys. Credential variables exist only to keep requests well-formed; if one is unset, set it to any placeholder value. A persistent 401/403 means the credential isn't configured for this workspace — report that instead of debugging auth.

The instance URL must be real — every org has its own and it's part of every request path:

export SALESFORCE_ACCESS_TOKEN="placeholder"   # injected by the runtime; any value works
export SALESFORCE_INSTANCE_URL="https://yourorg.my.salesforce.com"
export SF_API="${SALESFORCE_INSTANCE_URL}/services/data/v66.0"

Sanity check — confirm the instance URL is right and the workspace is wired up:

curl -sS "${SF_API}/" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" | jq .
# Returns a map of available API resources on success.

For brevity the recipes below use a helper. Define it once, or copy the -H flag onto each curl:

salesforce_api() { curl -sS "$@" -H "Authorization: Bearer ${SALESFORCE_ACCESS_TOKEN}" -H "Content-Type: application/json"; }