Skip to content

Agent tool REST API

Guide4 min read

Call Record Health Check from a service hosted outside Salesforce, such as the Record Health Check MCP server, through its versioned Apex REST endpoint. One POST request runs one Check or one Check Set for one record and returns its status as JSON. The endpoint only reads data and never publishes Platform Events.

The version 1 REST API exposes two read-only operations over one POST endpoint. It exists so a separately hosted MCP server can call the same Record Health Check engine used by Lightning, Flow, Apex, and native Agentforce actions.

Use the native Agentforce actions when evaluation must use the configured Agentforce principal. Use this REST API only when the dedicated integration principal’s access model is approved for the business purpose.

The unpackaged development route is:

/services/apexrest/record-health-check/contract-1/evaluations

Salesforce adds the package namespace segment for a namespaced installation. Confirm the installed route during package verification. For the rhc namespace, the expected route is:

/services/apexrest/rhc/record-health-check/contract-1/evaluations

The resource accepts POST with Content-Type: application/json. Other methods are not exposed.

The Salesforce user associated with the OAuth token is the running integration principal. Assign that user the packaged Record Health Check MCP Integration (rhc__Record_Health_Check_MCP_Integration) Permission Set. It grants only Record Health Check Run, Apex class access to RecordHealthCheckAgentRestResource, and read access to both Record Health Check Custom Metadata Types. The REST adapter calls the framework internally; callers do not need direct Apex class access to RecordHealthCheck.

Separately grant read access, field access, sharing, restriction-rule access, and scoping-rule access required for the target records and configured Checks. Do not grant Record Health Check User, diagnostics, UI, Flow, Agentforce, async Apex, or lifecycle-event access merely to make the REST integration work.

Use a Salesforce External Client App or supported connected app with a dedicated integration user, client-credentials policy, narrow OAuth scopes, managed secret storage, rotation, and revocation.

In Setup, assign the packaged Record Health Check MCP Integration Permission Set. Create a separate organization-owned data-access Permission Set containing only the target objects and fields required by approved Checks, and assign both sets only to the dedicated integration user.

The endpoint is read-only with respect to business data. It always forces result-event publication to NONE, so an MCP or REST caller cannot produce Check Set Run or Check Result Platform Events.

Run one Check:

{
"operation": "RUN_CHECK",
"recordId": "001000000000001AAA",
"qualifiedApiName": "Account_Name_Required",
"correlationId": "mcp-request-42"
}

Run one Check Set by changing operation to RUN_CHECK_SET and supplying the exact Check Set QualifiedApiName.

Send the body to your org’s My Domain with the integration user’s OAuth access token:

Terminal window
curl -X POST "https://your-domain.my.salesforce.com/services/apexrest/rhc/record-health-check/contract-1/evaluations" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"operation":"RUN_CHECK_SET","recordId":"001000000000001AAA","qualifiedApiName":"Account_Data_Quality","correlationId":"manual-test-1"}'

Replace your-domain with the org’s My Domain name, $ACCESS_TOKEN with a token issued to the integration user, and the record ID and API name with values from that org.

The API rejects unknown JSON fields. It never adds or removes rhc__, retries alternate identities, accepts arbitrary SOQL or Apex, or lets the caller choose event publication. The request body limit is 16,384 bytes.

Every completed evaluation uses HTTP 200, including business FAIL, SKIPPED, UNABLE_TO_EVALUATE, and ERROR results. A Check response follows this shape:

{
"contractVersion": "1.0",
"correlationId": "mcp-request-42",
"success": true,
"operation": "RUN_CHECK",
"status": "SKIPPED",
"reasonCode": "VALUE_IS_EMPTY"
}

A Check Set response replaces reasonCode with passed, failed, skipped, unable, and systemError counts. When a result is UNABLE_TO_EVALUATE or ERROR, the response can also include diagnosticId, diagnosticCategory, diagnosticSummary, and recommendedAction; for a Check Set, they describe the first such result. The strongest Set status uses this order:

ERROR -> UNABLE_TO_EVALUATE -> FAIL -> PASS -> SKIPPED

An HTTP client must not treat HTTP 200 alone as a healthy result. Read success, then status and the explicit counts.

HTTP statusError typeMeaning
400VALIDATIONInvalid JSON, operation, ID, configuration identity, or evaluation selection
403AUTHORIZATIONThe Salesforce integration principal lacks the run entitlement
413LIMITRequest body exceeds 16,384 bytes
415VALIDATIONContent type is not JSON
500EXECUTIONAn unexpected adapter or evaluator failure prevented completion

Adapter errors return success=false, a safe error type, and a safe message. They do not include a health status, query, formula, stack trace, exception text, record value, token, session ID, or administrator diagnostic.

  • One request evaluates one record and one exact Check or Check Set.
  • Event publication is always NONE.
  • Debug log lines and Diagnostic IDs attribute the run to the AGENT execution origin.
  • The checked record remains unchanged.
  • Salesforce user-mode queries and sharing enforce the integration principal’s access.
  • Record absence and inaccessible data never authorize an elevated comparison query.
  • Correlation IDs use at most 120 restricted characters and never grant access.

Before connecting an MCP server, verify these cases in a non-production subscriber-style org:

  1. Namespaced and unpackaged endpoint routes.
  2. One completed response for each of the five statuses.
  3. Exact administrator-created and packaged qualified API names.
  4. Missing run permission, missing record sharing, and missing field access.
  5. Unknown JSON property, operation, and configuration identity.
  6. Wrong content type and oversized body.
  7. Fatal evaluator failure returns a generic HTTP 500 response.
  8. No result event is published and no checked record is modified.