Salesforce API

REST API (sf-rest)

Endpoint(s)

1. Data Cloud Query API (SQL/SOQL)

• Base URL: https://{TSE_Instance_Url}/services/data/v64.0/ssot/
• Synchronous SQL Query: POST /query-sql
  • Usage: Executing standard ANSI SQL against Data Model Objects (DMOs).
• Asynchronous Query Management:
  • POST /query-sql (with async: true) returns a queryId.
  • GET /query-sql/{queryId}: To check status.
  • GET /query-sql/{queryId}/rows: To fetch the paginated result set.

2. Profile & Calculated Insights API

• Base URL: https://{TSE_Instance_Url}/api/v1/
• Profile Lookup: GET /profile/{dataModelName}
  • Note: Use this for OData-style filtering (e.g., ?filters=[EmailAddress__c='user@example.com']).
• Calculated Insights: GET /calculated-insights/{insightName}
  • Usage: Retrieving specific KPIs calculated by the Data Cloud engine.

3. Vector Search API (For RAG)

• Vector Search Index: POST /services/data/v64.0/ssot/search-vector
  • Payload: Includes queryText and indexName. The engine returns chunks of text and similarity scores which your Rust host will then inject into the LLM prompt.

Implementation Mapping for busbar-sf-api

Handle the Token Exchange flow. Data Cloud often requires a "secondary" token (the Offcore Token) for the TSE endpoints.

Response Schemas

Note that as of late 2025, Salesforce rebranded these as Data 360 APIs, but the internal URI paths usually retain ssot or c360a.

1. The Core Query Endpoint (SQL)

This is the most critical endpoint for your petgraph engine to fetch structured context.

• Endpoint: POST /services/data/v64.0/ssot/query-sql
• Purpose: Executes ANSI SQL against your DMOs (Data Model Objects).
• JSON Schema Requirement:
  • Request: Contains the sql string and optional pageSize.
  • Response: Since 2025/2026, Salesforce has standardized on a "Metadata + Rows" structure.

Recommended Rust Structs (serde):

Rust

#[derive(Deserialize, Debug)]
pub struct QueryResponse {
    pub data: Vec<serde_json::Value>, // Array of objects (rows)
    pub metadata: QueryMetadata,
    pub done: bool,
    pub queryId: Option<String>,
    pub nextBatchId: Option<String>,
}

#[derive(Deserialize, Debug)]
pub struct QueryMetadata {
    pub columns: Vec<ColumnInfo>,
}

#[derive(Deserialize, Debug)]
pub struct ColumnInfo {
    pub name: String,
    pub type: String, // e.g., "numeric", "varchar", "timestamp_with_timezone"
}

Warning for 2026: Be sure your parser handles case-insensitive column names. Recent updates changed the default output from lowercase to the original API name casing (e.g., ssot__Id__c instead of ssot__id__c).

2. The Vector Search Endpoint (RAG)

• Endpoint: POST /services/data/v64.0/ssot/search-vector
• Request Payload:

JSON

{
  "indexName": "Knowledge_Articles_Index",
  "queryText": "How do I reset my API key?",
  "topK": 5
}

• Response: Returns a list of chunks, scores, and the original record IDs. Your runtime will use these IDs to then fetch the full record via the Query API if needed.

3. The Unified Profile API (v1)

• Endpoint: GET /api/v1/profile/{dataModelName}
• Key Filters: You need to support the ?filters=[Field='Value'] syntax.

4. Metadata Discovery API

If you want your Rust engine to "know" what fields are available (for auto-complete or validation), you need the metadata endpoint.

• Endpoint: GET /api/v1/metadata
• Filter: ?entityType=DataModelObject
• Response: Provides the primary keys, field types, and relationships (essential for building your petgraph representation of the data schema).

Summary Table for busbar-sf-api

Salesforce Documentation

https://developer.salesforce.com/docs/data/connectapi/references/spec

Description

Add support for common Data 360 endpoints

Implementation Hints

No response

Acceptance Criteria

No response