POST /v1/translate

What it does

Takes raw engineering changelog text and returns:

• Structured summaries for CS, support, and customer audiences
• Detected risk flags (breaking change, auth impact, migration required, etc.)
• Extracted change records with type, area, and description
• An impact level: low, medium, or high
• In AI mode: executive summary, partner email draft, impacted scopes, impacted partners

Authentication

Requires X-API-Key. AI mode requires a Pro key.

Request body

{
  "raw_text":        "string (required) — the changelog text to analyze",
  "audience":        ["cs", "support", "customer"] (required, at least one),
  "mode":            "basic" | "ai" (optional, default: "basic"),
  "tone":            "neutral" | "friendly" | "direct" (optional, default: "neutral"),
  "product_area":    "string (optional) — e.g. Auth, Billing, API",
  "constraints":     "string (optional) — e.g. no jargon, bullet points only",
  "persona":         "cs" | "support" | "customer" | "tam" | "pm" | "marketing" | "legal",
  "partner_accounts": [
    { "name": "string", "scopes": ["string"] }
  ]
}

Field details

raw_text (required) The engineering-first changelog text. Can be one sentence or several paragraphs. The more detail, the more accurate the extraction.

audience (required) Which audience outputs to generate. Pass any combination of cs, support, customer. All three is typical.

mode (optional, default: basic)

• basic — deterministic extraction only. Fast, always available, no AI dependency.
• ai — includes GPT-4o-mini enrichment. Pro key required.

partner_accounts (optional) Pass your partner list with their OAuth/API scopes. When provided, the AI mode can reason about which specific partners are affected.

Response

{
  "cs_summary":          ["string"],
  "support_notes":       ["string"],
  "customer_summary":    ["string"],
  "risk_flags":          ["string"],
  "follow_up_questions": ["string"],
  "extracted_changes": [
    {
      "type":        "added|changed|fixed|deprecated|security",
      "area":        "string",
      "description": "string"
    }
  ],
  "impact_level":     "low|medium|high",
  "ai_enhancement":   null | {
    "executive_summary":   "string",
    "customer_followups":  ["string"],
    "adoption_risks":      ["string"],
    "impacted_scopes":     ["string"],
    "impacted_partners":   ["string"],
    "partner_email_draft": "string"
  },
  "ai_provider":       "string | null",
  "ai_fallback_used":  false,
  "ai_model":          "string | null",
  "ai_error_message":  "string | null"
}

curl -X POST https://api.opsentry.ai/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "raw_text": "Deprecated scope auth:legacy. Introduced auth:token.rotate. Breaking: integrations using auth:legacy must migrate by June 30.",
    "audience": ["cs", "support"],
    "mode": "basic",
    "product_area": "Auth"
  }'

curl -X POST https://api.opsentry.ai/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "raw_text": "Deprecated scope auth:legacy. Introduced auth:token.rotate. Breaking change.",
    "audience": ["cs", "support", "customer"],
    "mode": "ai",
    "tone": "neutral",
    "product_area": "Auth",
    "persona": "cs",
    "partner_accounts": [
      { "name": "Northstar Bank", "scopes": ["auth:legacy"] },
      { "name": "Apex Solutions", "scopes": ["auth:token.rotate"] }
    ]
  }'