REST API

// Execute a pipeline via REST:
// POST /services/apexrest/fm/v1/actions/{pipelineId}
// Authorization: Bearer {session_token_or_access_token}
// Content-Type: application/json

// Request body:
{
  "input": {
    "accountId": "001000000000001",
    "prompt": "Write a 3-bullet AE briefing"
  },
  "async": false
}

// Synchronous response (async: false):
{
  "executionId": "a0b000000000001",
  "status": "Completed",
  "output": {
    "content": "• Revenue grew 23% YoY...",
    "model": "anthropic/claude-sonnet-4-6",
    "inputTokens": 412,
    "outputTokens": 187
  },
  "durationMs": 3241,
  "totalCost": 0.000085
}

// Async response (async: true — returns immediately):
{
  "executionId": "a0b000000000002",
  "status": "Pending"
}

// Poll for async execution result:
// GET /services/apexrest/fm/v1/executions/{executionId}
// Authorization: Bearer {access_token}

// Response:
{
  "executionId": "a0b000000000002",
  "status": "Running",
  "progress": 0.33,
  "durationMs": 1820
}

// Final response when completed:
{
  "executionId": "a0b000000000002",
  "status": "Completed",
  "progress": 1.0,
  "output": { ... },
  "durationMs": 8940,
  "totalCost": 0.00021
}

// AI Chat endpoint — conversational interface:
// POST /services/apexrest/fm/v1/chat
// Authorization: Bearer {access_token}

// Request:
{
  "message": "What's the renewal status on this account?",
  "context": {
    "recordId": "001000000000001",
    "history": [
      { "role": "user",      "content": "Tell me about this account" },
      { "role": "assistant", "content": "Acme Corp is a 500-seat enterprise customer..." }
    ]
  },
  "provider": "anthropic"
}

// Response:
{
  "reply": "The renewal is due in 47 days. Based on the last three calls...",
  "model": "claude-sonnet-4-6",
  "inputTokens": 1203,
  "outputTokens": 284
}

// Admin endpoints (require FlowMason_Provider_Admin or FlowMason_Config_Admin):

// List all pipelines:
// GET /services/apexrest/fm/v1/admin/pipelines

// Get execution history:
// GET /services/apexrest/fm/v1/admin/executions?limit=50&status=Failed

// Analytics summary (7-day window):
// GET /services/apexrest/fm/v1/analytics/summary

// Response:
{
  "totalRuns": 1423,
  "successRate": 0.987,
  "totalCostUsd": 14.23,
  "avgDurationMs": 3812,
  "topPipelines": [
    { "id": "account-summarize-v1", "runs": 892, "cost": 7.81 },
    { "id": "case-classify-v2",     "runs": 531, "cost": 6.42 }
  ]
}

// FlowMason REST endpoints use Salesforce's standard authentication.
// Two options:

// Option 1: Connected App (OAuth 2.0) — for external integrations
// 1. Setup → App Manager → New Connected App
// 2. Enable OAuth Settings
// 3. Add scopes: api, refresh_token
// 4. Use the client_credentials or username-password flow to get an access token
// 5. Include it in requests: Authorization: Bearer {access_token}

// Option 2: Session Id — for same-org Apex/LWC calls
// Standard Salesforce session authentication applies automatically
// when calling from within the same org.

// REST endpoints enforce the caller's permission set.
// Users without FlowMason_Full_Access get HTTP 403.

// Calling from an external system (Node.js example):
const response = await fetch(
  'https://yourorg.my.salesforce.com/services/apexrest/fm/v1/actions/account-summarize-v1',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + accessToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input: { accountId: '001000000000001' },
      async: false
    })
  }
);
const result = await response.json();
console.log(result.output.content);