POST /v1/advice

Generate structured, psychometric-aware behavioral reasoning for workplace communication scenarios.

Endpoint

POST https://sil-api.sotsai.co/v1/advice

Auth

Send your organization API key in X-Sotsai-Api-Key.
Never expose this key to LLMs or browsers.

Rate limits

120/min per API key (organization).
Exceeding this limit returns 429.

Headers

Header	Required	Value
`X-Sotsai-Api-Key`	yes	`sotsai_...`
`Content-Type`	yes	`application/json`

Request body

Overview

context_summary and user_profile are required
interlocutor_profile is optional but recommended when a specific person is involved
If you do not have a user profile, do not call this endpoint

Fields

context_summary required string

Short, sanitized English summary of the situation.

Length: 10–1200 characters recommended
Include: observable behavior, stakes, intent, constraints
Avoid: names, emails, identifiers, secrets, full transcripts

Good

> “The user needs to give corrective feedback to a direct report who keeps missing deadlines. The user wants to be firm without demotivating their direct report.”

Avoid

> “Alice told Bob at ACME Corp his Q4 numbers are terrible…”

user_profile required object

Psychometric profile of the person asking for advice.

Profiles must be provided explicitly.
SotsAI never infers or guesses profiles.

user_profile.tool required string

Psychometric framework identifier.

Example: disc

user_profile.raw_scores required object

Provider-specific scores used to derive the profile.

Example (disc):

{
  "natural": { "D": 78, "I": 64, "S": 22, "C": 36 },
  "adapted": { "D": 70, "I": 58, "S": 30, "C": 42 }
}

interlocutor_profile optional object

Psychometric profile of the other person involved.

If omitted:

SotsAI focuses on self-adaptation only
interpersonal dynamics will be limited

interlocutor_profile.tool required (if interlocutor_profile is present) string

ame structure as user_profile.tool.

interlocutor_profile.raw_scores required (if interlocutor_profile is present) object

Same structure as user_profile.raw_scores.

relationship_type optional string

Relationship between the user and the interlocutor.

Typical values:

manager
direct_report
peer
self
other

Used to frame power dynamics and expectations.

situation_type_hint optional string

Optional semantic hint for the situation.

Examples:

giving_feedback
conflict_management
persuasion
change_management

SotsAI may still classify internally if omitted.

language optional string default: 'en'

ISO language code of the end-user language (e.g. en, fr).

SotsAI returns structured reasoning; your LLM renders final text. This value can help your orchestration layer choose the right rendering prompt.

Example request

curl -X POST "https://sil-api.sotsai.co/v1/advice" \
  -H "Content-Type: application/json" \
  -H "X-Sotsai-Api-Key: <YOUR_API_KEY>" \
  -d '{
    "context_summary": "The user needs to give corrective feedback to a direct report who keeps missing deadlines. The user wants to be firm without demotivating their direct report.",
    "relationship_type": "direct_report",
    "user_profile": {
      "tool": "disc",
      "raw_scores": {
        "natural": {
          "D": 78,
          "I": 64,
          "S": 22,
          "C": 36
        },
        "adapted": {
          "D": 70,
          "I": 58,
          "S": 30,
          "C": 42
        }
      }
    },
    "interlocutor_profile": {
      "tool": "disc",
      "raw_scores": {
        "natural": {
          "D": 18,
          "I": 32,
          "S": 70,
          "C": 76
        },
        "adapted": {
          "D": 22,
          "I": 28,
          "S": 74,
          "C": 80
        }
      }
    },
    "language": "fr"
  }'

// Example (server-side only). Do NOT expose X-Sotsai-Api-Key in browsers.

const res = await fetch("https://sil-api.sotsai.co/v1/advice", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Sotsai-Api-Key": process.env.SOTSAI_API_KEY!,
  },
  body: JSON.stringify({
    context_summary: "The user needs to give corrective feedback to a direct report who keeps missing deadlines. The user wants to be firm without demotivating their direct report.",
    relationship_type: "direct_report",
    user_profile: {
      tool: "disc",
      raw_scores: {
        natural: {
          D: 78,
          I: 64,
          S: 22,
          C: 36
        },
        adapted: {
          D: 70,
          I: 58,
          S: 30,
          C: 42
        },
      },
    },
    interlocutor_profile: {
      tool: "disc",
      raw_scores: {
        natural: {
          D: 18,
          I: 32,
          S: 70,
          C: 76
        },
        adapted: {
          D: 22,
          I: 28,
          S: 74,
          C: 80
        },
      },
    },
    language: "fr",
  }),
});

const json = await res.json();

# Example (server-side only). Do NOT expose X-Sotsai-Api-Key in client apps.
import os
import requests

resp = requests.post(
    "https://sil-api.sotsai.co/v1/advice",
    headers={
        "Content-Type": "application/json",
        "X-Sotsai-Api-Key": os.environ["SOTSAI_API_KEY"],
    },
    json={
        "context_summary": "I need to give corrective feedback to a direct report who keeps missing deadlines. I want to be firm without demotivating them.",
        "relationship_type": "direct_report",
        "user_profile": {
            "tool": "disc",
            "raw_scores": {
                "natural": {"D": 78, "I": 64, "S": 22, "C": 36},
                "adapted": {"D": 70, "I": 58, "S": 30, "C": 42},
            },
        },
        "interlocutor_profile": {
            "tool": "disc",
            "raw_scores": {
                "natural": {"D": 18, "I": 32, "S": 70, "C": 76},
                "adapted": {"D": 22, "I": 28, "S": 74, "C": 80},
            },
        },
        "language": "fr",
    },
    timeout=15,
)

resp.raise_for_status()
data = resp.json()

Responses

Status codes

Status	Meaning
200	OK
400	Invalid payload
401	Missing or invalid API key
403	Organization inactive / forbidden
429	Rate limited
500	Internal error

Success response 200

Example response body

{
  "status": "ok",
  "metadata": {
    "personalization_level": "partial",
    "strength_score": 79
  },
  "content": {
    "ir_version": "1.0.0",
    "primary_tension_frame": "friction",
    "tone_guidance": ["be_clear", "ground", "soften"],
    "impact_estimate": "high",
    "user_profile_lens": {
      "style_summary": "Direct, big-picture oriented, and assertive in communication, with a strong focus on results.",
      "dominant_drivers": ["achieving results", "innovation"],
      "sensitive_zones": ["perceived lack of progress", "feeling unheard"]
    },
    "interlocutor_profile_lens": {
      "present": false,
      "style_summary": "Not available",
      "dominant_drivers": [],
      "sensitive_zones": []
    },
    "dynamics_lens": {
      "friction_axes": [
        {
          "axis_id": "directness",
          "intensity": "high",
          "description": "High directness may be perceived as harsh in a feedback context.",
          "likely_effect": "Defensive reactions or withdrawal."
        }
      ],
      "synergy_axes": [
        {
          "axis_id": "assertiveness",
          "intensity": "high",
          "description": "Clear assertiveness helps communicate expectations.",
          "likely_effect": "Better understanding of priorities."
        }
      ]
    },
    "behavioral_levers": [
      {
        "lever_id": "balance_directness_with_empathy",
        "related_axes": ["directness"],
        "description": "Maintain clarity while softening delivery.",
        "intended_effect": "Reduce perceived harshness while keeping expectations clear."
      }
    ],
    "risk_patterns_if_ignored": [
      {
        "pattern_id": "harsh_feedback",
        "description": "Feedback remains blunt and unbuffered.",
        "consequences": ["defensive reactions", "relationship strain"]
      }
    ],
    "reflection_handles": [
      {
        "handle_id": "reflect_on_feedback_style",
        "focus": "How does your delivery style affect the other person’s openness to feedback?"
      }
    ]
  }
}

Error response (shape)

Example error response body

{
  "status": "error",
  "error_code": "INVALID_PAYLOAD",
  "message": "Request body is missing required field: user_profile"
}

Notes

Idempotency

This endpoint is deterministic and side-effect free.

safe to retry on network/timeouts/5xx
safe to cache when context and profiles are unchanged

Idempotency keys are not required.

Logging and privacy

Avoid logging:

raw context_summary
full psychometric profiles

Safe to log:

HTTP status
latency
full DISC profiles
metadata.personalization_level
metadata.strength_score