A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Salesforce API is how an app or AI agent works with a Salesforce org: reading and writing records like accounts and contacts, running a SOQL query, searching across objects, or batching several changes into one call. Access is granted through an OAuth token whose scopes, like api or full, set the kinds of calls allowed, while the object and field permissions of the user behind the token bound which records it can actually touch. Salesforce ships three dated releases a year and can push a change event onto an event bus whenever a record is created, updated, or deleted.
How an app or AI agent connects to Salesforce determines what it can reach. There is a route for reading and writing records and running queries, a route for receiving record changes as they happen, and a local server that exposes Salesforce developer tools to agents, and each is governed by the OAuth scopes on the token and the object and field permissions of the user behind it.
The REST API reads and writes records, runs SOQL queries and SOSL searches, and describes object metadata, at /services/data/v67.0/ on the org's My Domain host. It returns JSON by default (XML is supported), authenticates with an OAuth 2.0 Bearer token, and names the dated version in the path so an integration can pin a version. Composite resources bundle several calls into one request.
The Pub/Sub API is a gRPC interface for subscribing to and publishing platform events and Change Data Capture change events, delivering Avro-encoded messages over HTTP/2 with bidirectional streaming. A subscriber learns about record changes in near real time without polling. The older CometD-based Streaming API delivers the same change events as JSON. Events are retained on the event bus for 72 hours for replay.
The Salesforce DX MCP Server is a first-party, open-source Model Context Protocol server, in Beta, that exposes Salesforce developer tools to AI agents and agentic IDEs. It runs locally and works against orgs authenticated through Salesforce CLI, with tools for tasks like querying org metadata, running tests, and deploying code. It is aimed at pro-code developer workflows rather than general record access.
The standard authorization-code flow: a user logs in and consents, the app receives an authorization code, and exchanges it for an access token and a refresh token. The token represents that user and is bounded by their object and field permissions and the OAuth scopes granted to the app. Best when a real person authorizes the integration.
A server-to-server flow with no user interaction. The app signs a JWT with a certificate registered on the external client app or connected app and exchanges it for an access token for a pre-authorized user. There is no refresh token; the app mints a new JWT when the token expires. Best for backend integrations and scheduled jobs.
A server-to-server flow where the app authenticates with its own client ID and secret and acts as a single configured integration user, with no end user involved. The resulting token is bounded by that integration user's permissions. Best for trusted backend services that always run as one identity.
The Salesforce REST API works on records of standard and custom objects, called sObjects, such as accounts, contacts, opportunities, and leads. An agent reads, creates, updates, and deletes records, describes an object's fields, runs SOQL queries and SOSL searches, and batches several writes into one request.
Methods for reading, creating, updating, and deleting records of an object.
Methods for listing objects and describing an object's fields and relationships.
Methods for running SOQL queries and SOSL text searches.
Methods for bundling several reads and writes into one request.
Methods for listing API versions, resources, and the org's current limit usage.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Records (sObject Rows)Methods for reading, creating, updating, and deleting records of an object.7 | ||||||
| GET | /services/data/v67.0/sobjects/{SObject}/{id} | Retrieve a record of the specified object by its ID, optionally limiting the fields returned. | read | Read on object | Current | |
Needs the api OAuth scope and Read on the object plus field-level security on the requested fields. Acts onsObject record Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services/data/v67.0/sobjects/{SObject} | Create a new record of the specified object from field values in the request body. | write | Create on object | Current | |
Needs the api scope and Create on the object. Returns 201 with the new record ID. Acts onsObject record Permission (capability) Create on objectVersionAvailable since the API’s base version Webhook event cdc-createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /services/data/v67.0/sobjects/{SObject}/{id} | Update the fields of an existing record by its ID. | write | Edit on object | Current | |
Needs the api scope and Edit on the object. Returns 204 No Content on success. Acts onsObject record Permission (capability) Edit on objectVersionAvailable since the API’s base version Webhook event cdc-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /services/data/v67.0/sobjects/{SObject}/{id} | Delete a record by its ID, sending it to the Recycle Bin. | write | Delete on object | Current | |
Needs the api scope and Delete on the object. Returns 204 No Content. Acts onsObject record Permission (capability) Delete on objectVersionAvailable since the API’s base version Webhook event cdc-deleteRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /services/data/v67.0/sobjects/{SObject}/{externalIdField}/{value} | Create or update a record (upsert) matched by the value of an external ID field rather than the Salesforce ID. | write | Edit on object | Current | |
Needs the api scope plus Create and Edit on the object. A non-unique external ID returns 300 with the matching records. Acts onsObject record Permission (capability) Edit on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/sobjects/{SObject}/updated/ | List the IDs of records of an object created or updated within a given time range. | read | Read on object | Current | |
Needs the api scope and Read on the object. Used for incremental sync via start and end parameters. Acts onsObject change list Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/sobjects/{SObject}/deleted/ | List the IDs of records of an object deleted within a given time range. | read | Read on object | Current | |
Needs the api scope and Read on the object. Acts onsObject change list Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Object metadata (Describe)Methods for listing objects and describing an object's fields and relationships.3 | ||||||
| GET | /services/data/v67.0/sobjects/{SObject} | Retrieve basic metadata for an object, including recent items and links to its describe and row resources. | read | Read on object | Current | |
Needs the api scope. Returns object-level metadata, not record data. Acts onsObject metadata Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/sobjects/{SObject}/describe | Completely describe an object's fields, picklists, URLs, and child relationships. | read | Read on object | Current | |
Needs the api scope. Supports If-Modified-Since to skip unchanged metadata. Acts onsObject describe Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/sobjects | List all objects available to the logged-in user, with basic metadata for each. | read | api | Current | |
Needs the api scope. Also returns the org encoding and maximum query batch size. Acts onobject list Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Query & searchMethods for running SOQL queries and SOSL text searches.4 | ||||||
| GET | /services/data/v67.0/query/?q={soql} | Run a SOQL query and return the matching records, paged through a nextRecordsUrl cursor. | read | Read on object | Current | |
Needs the api scope and Read on every object and field referenced. Filters out deleted records. Acts onquery result Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/queryAll/?q={soql} | Run a SOQL query that also returns deleted, merged, and archived records. | read | Read on object | Current | |
Needs the api scope and Read on the referenced objects. Unlike Query, includes records removed by delete or merge. Acts onquery result Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/search/?q={sosl} | Run a SOSL text search across one or more objects and return matching records. | read | Read on object | Current | |
Needs the api scope and Read on the searched objects. The search string must be URL-encoded. Acts onsearch result Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/parameterizedSearch/?q={searchString} | Run a simple text search using URL parameters instead of a SOSL clause, or POST a request body for a complex search. | read | Read on object | Current | |
Needs the api scope and Read on the searched objects. Acts onsearch result Permission (capability) Read on objectVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Composite (batch)Methods for bundling several reads and writes into one request.7 | ||||||
| POST | /services/data/v67.0/composite | Run up to 25 REST subrequests in order in one request, passing the output of one into the next. | write | api | Current | |
Needs the api scope. Each subrequest is still bounded by the user's object and field permissions. Acts oncomposite request Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services/data/v67.0/composite/batch | Run up to 25 independent REST subrequests in a single request. | write | api | Current | |
Needs the api scope. Subrequests don't share state and each is permission-checked. Acts onbatch request Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services/data/v67.0/composite/sobjects | Create up to 200 records of one or more object types in a single request. | write | Create on object | Current | |
Needs the api scope and Create on each object. allOrNone controls whether a partial failure rolls everything back. Acts onsObject collection Permission (capability) Create on objectVersionAvailable since the API’s base version Webhook event cdc-createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /services/data/v67.0/composite/sobjects | Update up to 200 records of one or more object types in a single request. | write | Edit on object | Current | |
Needs the api scope and Edit on each object. Each record must include its Id. Acts onsObject collection Permission (capability) Edit on objectVersionAvailable since the API’s base version Webhook event cdc-updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /services/data/v67.0/composite/sobjects | Delete up to 200 records, passing their IDs as a parameter, in a single request. | write | Delete on object | Current | |
Needs the api scope and Delete on each object. Acts onsObject collection Permission (capability) Delete on objectVersionAvailable since the API’s base version Webhook event cdc-deleteRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services/data/v67.0/composite/graph | Run composite requests with explicit dependency ordering between related records as a graph. | write | api | Current | |
Needs the api scope. Handles larger sets of related records than Composite, with up to 500 nodes per graph. Acts oncomposite graph Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /services/data/v67.0/composite/tree/{SObject} | Create one or more sObject trees, each a root record with nested parent-child records, in a single request. | write | Create on object | Current | |
Needs the api scope and Create on each object in the tree. Up to 200 records total per request. Acts onsObject tree Permission (capability) Create on objectVersionAvailable since the API’s base version Webhook event cdc-createRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Service & limitsMethods for listing API versions, resources, and the org's current limit usage.3 | ||||||
| GET | /services/data/ | List the API versions available for the org, each with its label, version number, and base URL. | read | — | Current | |
No scope required; this resource is available without authentication. Acts onversion list Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/ | List the REST resources available for a given API version, with their relative URLs. | read | api | Current | |
Needs the api scope. Acts onresource list Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /services/data/v67.0/limits | List the org's limits and remaining allocation for each, including daily API requests. | read | api | Current | |
Needs the api scope and the View Setup and Configuration permission. Acts onlimits Permission (capability) apiVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Salesforce can notify an app when a record changes through Change Data Capture, which publishes a create, update, delete, or undelete event for an object onto an event bus. A subscriber receives those events over the Pub/Sub API or the older streaming interface, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
Change Data Capture: CREATE | A record of a Change Data Capture enabled object was created. The change event carries the new record's fields and a header naming the change type, published onto the event bus. | /services/data/v67.0/sobjects/{SObject}/services/data/v67.0/sobjects/{SObject}/{externalIdField}/{value}/services/data/v67.0/composite/sobjects |
Change Data Capture: UPDATE | A record was updated. The change event carries the changed fields and the record ID, so a subscriber can sync the change to an external system. | /services/data/v67.0/sobjects/{SObject}/{id}/services/data/v67.0/sobjects/{SObject}/{externalIdField}/{value}/services/data/v67.0/composite/sobjects |
Change Data Capture: DELETE | A record was deleted. The change event carries the record ID and change type, so a subscriber can remove or flag the corresponding record downstream. | /services/data/v67.0/sobjects/{SObject}/{id}/services/data/v67.0/composite/sobjects |
Salesforce meters total API calls across an org over a rolling 24-hour window, with the allocation set by edition and license count, and separately caps how many long-running requests run at once.
Salesforce meters total API calls, not a per-method cost. An org gets an allocation of API requests over a rolling 24-hour window, shared across REST, SOAP, Bulk, and Connect, that scales with edition and license count (a paid edition like Enterprise starts at 100,000 per 24 hours, a Developer Edition org at 15,000). It is a soft limit Salesforce lets an org exceed for a while, but sustained overuse is blocked with HTTP 403 and the REQUEST_LIMIT_EXCEEDED error code. A separate concurrency limit caps how many long-running requests (those over 20 seconds) run at once, at 25 in production and 5 in a Developer or sandbox org.
A SOQL query returns records in batches. When more remain, the response includes a nextRecordsUrl field and a done flag set to false; an integration requests that URL to fetch the next batch and repeats until done is true. The default query batch size is 2,000 records and can be lowered with the Sforce-Query-Options header. Composite Batch runs up to 25 subrequests in one call, and sObject Collections acts on up to 200 records per request.
A single request URI plus headers is capped at 16,384 bytes, returning 414 or 431 if exceeded. sObject Collections handles up to 200 records per call, and Composite Batch up to 25 subrequests. Change Data Capture and high-volume platform events are retained on the event bus for 72 hours so a disconnected subscriber can catch up.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 300 | MULTIPLE_CHOICES | An external ID used in an upsert matched more than one record. The response body lists the matching records. | Make the external ID field unique, or use a value that matches a single record, then retry. |
| 400 | MALFORMED_QUERY / INVALID_FIELD | The request couldn't be understood, usually because the JSON or XML body, a SOQL query, or a field name is invalid. | Read the errorCode and message, fix the body, query, or field, and resend. The request isn't retryable as-is. |
| 401 | INVALID_SESSION_ID | The OAuth token or session has expired or is invalid. | Refresh the access token (or re-run the OAuth flow) and resend the request with the new Bearer token. |
| 403 | REQUEST_LIMIT_EXCEEDED / INSUFFICIENT_ACCESS | The request was refused, either because the org's 24-hour API allocation was exceeded, or because the user lacks permission for the object or record. | For a limit error, slow down and spread calls, or raise the allocation. For an access error, grant the needed object or field permission to the user. |
| 404 | NOT_FOUND | The requested resource or record couldn't be found, or isn't visible to this user because of sharing. | Check the URI and record ID, and confirm the user has sharing access to the record. |
| 405 | METHOD_NOT_ALLOWED | The HTTP method isn't allowed for this resource, like a POST to a read-only resource. | Use the method the resource supports (GET to read, PATCH to update, DELETE to delete). |
| 410 | GONE | The API version requested has been retired and removed. | Move the integration to a supported, current API version and update any references to the old version. |
| 412 | PRECONDITION_FAILED | A conditional request header, like If-Match or If-Unmodified-Since, wasn't satisfied because the record changed. | Re-fetch the record, get its current ETag or modified date, and retry the conditional request. |
| 500 | INTERNAL_SERVER_ERROR | An error occurred within the Lightning Platform and the request couldn't be completed. | Retry with backoff, and contact Salesforce Customer Support if it persists. |
Salesforce versions its API with a dated number tied to each of its three yearly releases, Spring, Summer, and Winter, and an older version keeps working for at least three years before retirement.
The current API version, matching the Summer '26 release. Salesforce ships three dated releases a year (Spring, Summer, Winter), and every REST request names its version in the path, like /services/data/v67.0/.
The Spring '26 release. From this release, new connected apps can no longer be created; existing connected apps keep working and external client apps replace them for new integrations.
The Winter '26 release. A backward-compatible version that adds features without breaking older versions.
The Summer '25 release. With this release, API versions 21.0 through 30.0 were retired and now return 410 GONE.
The Winter '25 release, an earlier supported version still accepted by current orgs.
Pin a version in the request path and move up on a schedule that suits the integration.
Salesforce REST API release notes ↗Bollard AI sits between a team's AI agents and Salesforce. Grant each agent exactly the access it needs, read or write, object by object, and every call is checked and logged.