Service Cloud REST API

Service Cloud REST API

This skill activates when a practitioner needs to call Salesforce Service Cloud REST APIs — either the Knowledge REST API (both the internal authoring surface and the guest-facing SEO retrieval surface) or the Messaging for In-App and Web (MIAW) Enhanced Chat API. It covers endpoint selection, authentication differences, data category filtering, legacy Chat REST API migration, and common integration patterns.

Before Starting

Gather this context before working on anything in this domain:

• API version: The URL-name lookup for Knowledge articles requires API version 44.0 or later. Confirm the org's minimum API version before building integrations.
• Authentication context: The /knowledgeManagement/ endpoint family requires an authenticated session (internal users, agents, or Apex callouts with a session ID). The /support/knowledgeWithSEO/ endpoint family supports unauthenticated guest access — used for Experience Cloud portals and self-service sites. Using the wrong endpoint for the wrong context causes 401 errors or missing article results.
• Chat API version in use: Determine whether the org still uses the legacy Chat REST API (force.com/chat/rest/) or has migrated to Enhanced Chat API (Messaging for In-App and Web, MIAW). The legacy Chat REST API was retired on February 14, 2026. Any org still calling legacy Chat REST endpoints after that date receives failures.
• Data category structure: Knowledge article retrieval via data category filter requires knowing the data category group developer name and the category developer name. These must be URL-encoded in query parameters.
• Knowledge article type metadata: The v1 Knowledge REST API uses article type-specific endpoints. The v2 (unified) Knowledge REST API treats all articles uniformly under a single knowledge__kav object type.

Core Concepts

Knowledge REST API — Two Distinct Endpoint Families

Salesforce exposes two separate REST API families for Knowledge, each with a different authentication model and purpose:

Internal/Authoring (/knowledgeManagement/):

• Base path: /services/data/vXX.X/knowledgeManagement/
• Requires a valid authenticated Salesforce session (OAuth access token or Apex session ID)
• Used for: drafting, publishing, translating, managing article lifecycle, retrieving article content for agents
• Key resources: /articles, /articles/{articleId}, /articleTypes, /articleTypes/{articleTypeName}/suggestedArticles
• Returns full article field content including internal-only fields

Guest/SEO Retrieval (/support/knowledgeWithSEO/):

• Base path: /services/data/vXX.X/support/knowledgeWithSEO/
• Supports unauthenticated access when used with an Experience Cloud site that has guest user access enabled
• Used for: self-service portals, public knowledge bases, Experience Cloud deflection pages
• Returns articles filtered to those published and accessible to the guest user profile
• URL-name-based lookup available from API v44+: /support/knowledgeWithSEO/articles?urlName=my-article-url-name

Mixing up these two families is the most common integration error: an Apex callout using /knowledgeManagement/ will fail in an Aura/LWC guest context; a portal site using /support/knowledgeWithSEO/ will not return unpublished drafts.

Data Category Filtering

Knowledge articles are organized into data categories (hierarchical classification trees). The REST API supports filtering by data category using query parameters:

• categoryGroup — developer name of the data category group (e.g., Products)
• category — developer name of the specific category (e.g., Laptops)
• navigationType — standard (default) or classifyingArticles — controls whether parent/child categories are included

Example query string: ?categoryGroup=Products&category=Laptops

Data category names are case-sensitive and must match the developer name exactly, not the label. A mismatch returns an empty result set with no error, which is a common silent failure mode.

Visibility of articles by data category is also governed by the user's data category visibility settings. An authenticated user who lacks visibility to a category will receive an empty result even if articles exist — there is no permission error thrown.

Legacy Chat REST API vs. Enhanced Chat API (MIAW)

Salesforce had two separate live-chat REST API surfaces:

Legacy Chat REST API (retired February 14, 2026):

• Base path: https://<instance>.salesforce.com/chat/rest/
• Used the X-LIVEAGENT-API-VERSION header and X-LIVEAGENT-SESSION-KEY header pair
• Required a separate chat endpoint hostname distinct from the Salesforce instance URL
• Session lifecycle: /System/SessionId → /Chasitor/ChasitorInit → polling /System/Messages

Enhanced Chat API — Messaging for In-App and Web (MIAW):

• Part of the Salesforce Omni-Channel Messaging platform
• Uses standard OAuth 2.0 bearer tokens — no custom headers required
• Conversation lifecycle managed via Salesforce Platform Event streaming and REST resources under /services/data/vXX.X/connect/messaging/
• Supports persistent conversation history, async messaging, and rich media — capabilities not available in legacy Chat REST API
• Agent-facing events flow through Omni-Channel rather than a long-poll loop

After February 14, 2026, any integration still targeting legacy Chat REST endpoints (/chat/rest/) receives HTTP errors. Migrating requires replacing the entire client session lifecycle — there is no backward-compatible wrapper.

Common Patterns

Pattern 1: Knowledge Article Retrieval with Data Category Filter (Authenticated)

When to use: An Apex class, Visualforce page, or LWC (in authenticated context) needs to programmatically fetch Knowledge articles filtered to a specific product line or topic.

How it works:

1. Obtain an OAuth access token or use the current session ID in Apex (UserInfo.getSessionId()).
2. Construct the request to /services/data/v62.0/knowledgeManagement/articles with query params.
3. Pass categoryGroup and category as query parameters.
4. Deserialize the JSON response into Apex wrapper classes.

Key request shape:

GET /services/data/v62.0/knowledgeManagement/articles?categoryGroup=Products&category=Laptops&pageSize=10
Authorization: Bearer <access_token>

Response contains articles array with id, title, summary, urlName, articleType, publishStatus, lastPublishedDate.

Why not SOQL directly: SOQL on Knowledge__kav does not respect data category visibility for guests, and does not produce SEO-friendly URL name lookups. REST API respects the full sharing and visibility stack.

Pattern 2: Guest-Facing Article Lookup by URL Name (Experience Cloud)

When to use: An Experience Cloud self-service site needs to render a full Knowledge article using its URL slug (e.g., /help/how-to-reset-password), without requiring the visitor to log in.

How it works:

1. Enable Knowledge for the Experience Cloud site and set the guest user profile's data category visibility.
2. Make an unauthenticated REST call (or via Connected App with the site's guest user context) to:

   GET /services/data/v62.0/support/knowledgeWithSEO/articles?urlName=how-to-reset-password
   

3. The response returns the full article body, metadata, and related categories for the matching URL name.
4. If the URL name does not match any article visible to the guest profile, the response returns an empty articles array (not a 404).

Why not the authoring endpoint: /knowledgeManagement/ requires authentication and returns draft articles — unsuitable for public-facing rendering.

Pattern 3: Migrating Legacy Chat REST API to Enhanced Chat API (MIAW)

When to use: Any org that has live code or integrations using the legacy Chat REST API (/chat/rest/) that must be migrated before or after the February 14, 2026 retirement deadline.

How it works:

1. Audit all integration points calling <instance>.salesforce.com/chat/rest/ — check Apex HttpRequest callouts, external middleware, and mobile SDKs.
2. Provision an Enhanced Messaging Channel in Setup > Messaging Settings. Select "In-App and Web" channel type.
3. Replace X-LIVEAGENT-* header-based session initiation with an OAuth 2.0 Connected App flow.
4. Replace the long-poll GET /System/Messages loop with Platform Event subscription to ConversationIntelligenceEvent__e or use the MIAW SDK for web/mobile.
5. Map legacy transcript objects (LiveChatTranscript) to their MIAW equivalents (MessagingSession).

Why not keep legacy Chat REST: The endpoint is retired and returns errors post-February 14, 2026. There is no official compatibility shim.

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Identify authentication context — Determine whether the integration will run as an authenticated internal user/agent or as an unauthenticated guest. This determines which endpoint family (/knowledgeManagement/ vs. /support/knowledgeWithSEO/) to use and whether a Connected App with OAuth is needed.
2. Confirm API version — Verify the org's minimum API version. URL-name lookup requires v44+. Use the highest available API version (e.g., v62.0 for Spring '25) to access the latest resource shapes.
3. Check data category configuration — For any category-filtered retrieval, confirm the data category group and category developer names in Setup > Data Categories. Verify the user or guest profile has the correct data category visibility assignments.
4. Audit legacy Chat REST usage — Run a codebase search for /chat/rest/ and X-LIVEAGENT-API-VERSION. Any hit requires MIAW migration. Document each call site with its session lifecycle step.
5. Construct and test REST calls — Build the endpoint URL, add required headers (Authorization: Bearer, Content-Type: application/json), and validate the response shape in Workbench or Postman before implementing in Apex.
6. Implement Apex callout with proper error handling — Wrap Http.send() in try/catch, check HttpResponse.getStatusCode() for 200/201 vs. 4xx/5xx, parse the JSON body, and handle the empty-array case for data category mismatches.
7. Validate with a Review Checklist pass — Confirm no legacy Chat REST references remain, no hardcoded category names, correct endpoint family for the auth context, and that test coverage includes the empty-result case.

Review Checklist

Run through these before marking work in this area complete:

• Correct endpoint family used for authentication context (/knowledgeManagement/ for authenticated, /support/knowledgeWithSEO/ for guest)
• API version is v44+ if URL-name lookup is used
• Data category developer names (not labels) used in query parameters
• No remaining references to legacy Chat REST API (/chat/rest/ or X-LIVEAGENT-* headers)
• Empty-array response handled explicitly (not treated as an error, but not silently ignored)
• OAuth access token or session ID is not exposed in client-side JavaScript
• Apex test class mocks the HttpResponse for both success and empty-result scenarios

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Data category mismatch returns empty array, not an error — If the categoryGroup or category parameter value does not match an existing developer name (including case), the API returns {"articles": [], "total": 0} with HTTP 200. There is no error message. This silently breaks filtering and is indistinguishable from "no articles exist" without inspecting Setup.
2. Legacy Chat REST API is retired — Any callout to <instance>.salesforce.com/chat/rest/ after February 14, 2026 returns an error. There is no deprecation grace period or backward-compatible redirect. Orgs that missed the migration deadline must treat this as an emergency remediation.
3. /knowledgeManagement/ returns drafts; /support/knowledgeWithSEO/ does not — The authoring endpoint includes draft and archived articles in results when the publishStatus filter is omitted. A portal that accidentally uses the authoring endpoint (with an admin session) may display unpublished articles to visitors.
4. Guest user data category visibility must be explicitly configured — Even if articles are published, an Experience Cloud guest user will receive an empty result from /support/knowledgeWithSEO/ unless the guest user profile has been granted data category visibility in Setup > Data Category Visibility. This is a separate setting from the article's publication status.
5. URL-name uniqueness is not enforced across article types — If two articles of different types share the same urlName, the /support/knowledgeWithSEO/articles?urlName=<slug> endpoint may return multiple results or only the first match depending on API version. Use article-type-specific filtering when URL names are not guaranteed unique.

Output Artifacts

Related Skills

• architect/service-cloud-architecture — Service Cloud solution architecture including Knowledge as a deflection engine and channel strategy
• agentforce/einstein-copilot-for-service — Einstein Article Recommendations and Service Replies that consume Knowledge articles internally