API reference

Operational AI Draft API

Request support replies, analytics explanations, promotion plans and automation ideas for human review.

Start with getting started Explore API docs

Choose the task, then review its evidence

support-draft requires a customerMessage and can use notes. analytics-summary accepts provided metrics or dashboardContext. promotion-plan accepts a goal or notes. automation-recommendations suggests ideas, not running workflows. Availability depends on configured AI service access and quota; disabled/configuration errors return 409 and generation limits return 429.

All operational tools require workspace.view, all-products scope and the permission for the requested tool. Selected-product teammates cannot use these workspace-wide tools. Context includes recent products; deals require marketing.view, while order aggregates and supplied dashboard metrics require analytics.view. Support-only requests do not query or send sales totals. The range input labels the context; it does not change the 30-day aggregate query. Suggestions are not audited financial reports, policy decisions or guarantees. Keep credentials, serials and unnecessary customer information out of prompts; automated redaction is not permission to share private records.

SoundSync

Illustrative support draft

Generate a reply for review, not sending

curl --fail-with-body -sS -X POST "$SOUNDSYNC_API_BASE/api/developer/ai/operations/support-draft" \
  -H "Authorization: Bearer $DEVELOPER_TOKEN" -H "Content-Type: application/json" \
  --data '{"customerMessage":"Where do I find my download?","notes":"Use the signed-in customer library."}'

Inspect persistence before continuing

Generation returns draftId, toolType, suggestions, provider, model and status. A persistenceWarning or null draftId means the suggestion is not safely represented as a stored draft. GET drafts filters by tool and captured context permissions before selecting up to 50 recent developer-scoped rows; raw IDs may be decimal strings. Reads and review changes require all-products scope. A draft generated with analytics or marketing context also requires those permissions later, even if it is a support-reply draft. Legacy drafts with unknown context require both analytics.view and marketing.view, plus the tool permission. A missing, foreign-workspace or unauthorized-tool/context draft returns 404 on mutation.

save, apply and dismiss update review status. DELETE marks discarded rather than erasing the row. apply does not send email, publish support content, create a promotion, change a price, refund an order, cancel a subscription or execute an automation. Perform any approved action separately through its own authorized workflow.

Keep the draft stores distinct

Operational support replies use this API. Product FAQ and support-items generation uses product setup drafts, with a separate persistence and review workflow. A product draft ID is not interchangeable with an operational draft ID. AI output needs review before customers see it.

SoundSync

Reviewed next steps

Support content

Save approved articles and routing.

Explore

Campaigns and marketing

Use the campaign workflow for actual sending.

Explore

AI use and data

Read assistance and data boundaries.

Explore

SoundSync

Requests and responses

POST /api/developer/ai/operations/support-draft

Draft a customer support reply

Auth: Account Bearer JWT
Scope: customers.view plus workspace.view and all-products scope.
Request fields: productId: integer
customerId: integer
campaignId: integer
customerMessage: string
customer_message: string
notes: string
goal: string
tone: string
range: string
metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
Returns: HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
Notes: Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "customerId": {
      "type": "integer",
      "minimum": 1
    },
    "campaignId": {
      "type": "integer",
      "minimum": 1
    },
    "customerMessage": {
      "type": "string"
    },
    "customer_message": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "range": {
      "type": "string"
    },
    "metrics": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "dashboardContext": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true,
  "anyOf": [
    {
      "required": [
        "customerMessage"
      ]
    },
    {
      "required": [
        "customer_message"
      ]
    }
  ]
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draftId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        {
          "type": "null"
        }
      ]
    },
    "toolType": {
      "type": "string"
    },
    "suggestions": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "provider": {
      "type": "string"
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "persistenceWarning": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 502, 503.

POST /api/developer/ai/operations/analytics-summary

Draft an explanation of current analytics

Auth: Account Bearer JWT
Scope: analytics.view plus workspace.view and all-products scope.
Request fields: productId: integer
customerId: integer
campaignId: integer
customerMessage: string
customer_message: string
notes: string
goal: string
tone: string
range: string
metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
Returns: HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
Notes: Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "customerId": {
      "type": "integer",
      "minimum": 1
    },
    "campaignId": {
      "type": "integer",
      "minimum": 1
    },
    "customerMessage": {
      "type": "string"
    },
    "customer_message": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "range": {
      "type": "string"
    },
    "metrics": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "dashboardContext": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draftId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        {
          "type": "null"
        }
      ]
    },
    "toolType": {
      "type": "string"
    },
    "suggestions": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "provider": {
      "type": "string"
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "persistenceWarning": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 502, 503.

POST /api/developer/ai/operations/promotion-plan

Draft a promotion plan

Auth: Account Bearer JWT
Scope: marketing.view plus workspace.view and all-products scope.
Request fields: productId: integer
customerId: integer
campaignId: integer
customerMessage: string
customer_message: string
notes: string
goal: string
tone: string
range: string
metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
Returns: HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
Notes: Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "customerId": {
      "type": "integer",
      "minimum": 1
    },
    "campaignId": {
      "type": "integer",
      "minimum": 1
    },
    "customerMessage": {
      "type": "string"
    },
    "customer_message": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "range": {
      "type": "string"
    },
    "metrics": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "dashboardContext": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draftId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        {
          "type": "null"
        }
      ]
    },
    "toolType": {
      "type": "string"
    },
    "suggestions": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "provider": {
      "type": "string"
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "persistenceWarning": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 502, 503.

POST /api/developer/ai/operations/automation-recommendations

Draft automation recommendations

Auth: Account Bearer JWT
Scope: marketing.manage plus workspace.view and all-products scope.
Request fields: productId: integer
customerId: integer
campaignId: integer
customerMessage: string
customer_message: string
notes: string
goal: string
tone: string
range: string
metrics: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
dashboardContext: object. Operation-specific extension data; do not put credentials or unnecessary personal information here.
Returns: HTTP 200: draftId, toolType, suggestions, provider, model, status, persistenceWarning.
Notes: Requires configured operational AI availability and quota. Returns suggestions for review, not a sent reply, campaign, automation or price change. Context includes recent products; deals require marketing.view, and 30-day order aggregates/provided metrics require analytics.view. Support-only callers receive neither sales aggregates nor supplied dashboard metrics. range is a label, not a reporting date filter. Body flags cannot grant context access. A null draftId with persistenceWarning means persistence is unavailable. customer_message is also accepted for support drafts.

Request, response and error reference

Request (application/json)

{
  "type": "object",
  "properties": {
    "productId": {
      "type": "integer",
      "minimum": 1
    },
    "customerId": {
      "type": "integer",
      "minimum": 1
    },
    "campaignId": {
      "type": "integer",
      "minimum": 1
    },
    "customerMessage": {
      "type": "string"
    },
    "customer_message": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "goal": {
      "type": "string"
    },
    "tone": {
      "type": "string"
    },
    "range": {
      "type": "string"
    },
    "metrics": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "dashboardContext": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    }
  },
  "additionalProperties": true
}

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draftId": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        {
          "type": "null"
        }
      ]
    },
    "toolType": {
      "type": "string"
    },
    "suggestions": {
      "type": "object",
      "additionalProperties": true,
      "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
    },
    "provider": {
      "type": "string"
    },
    "model": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string"
    },
    "persistenceWarning": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 409, 429, 500, 502, 503.

GET /api/developer/ai/operations/drafts

List the latest 50 permitted workspace operational drafts

Auth: Account Bearer JWT
Scope: workspace.view, all-products scope and each returned tool permission.
Returns: HTTP 200: drafts.
Notes: Filters before LIMIT by support_reply:customers.view, analytics_summary:analytics.view, promotion_plan:marketing.view and automation_recommendation:marketing.manage, plus the analytics/marketing context permissions captured at generation. Legacy drafts with unknown context require both analytics.view and marketing.view as well as their tool permission. A caller with no eligible tools receives an empty list. Other workspaces are never included.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "drafts": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "integer",
                "minimum": 1
              },
              {
                "type": "string",
                "pattern": "^[1-9][0-9]*$"
              }
            ],
            "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
          },
          "tool_type": {
            "type": "string"
          },
          "generated_payload_json": {
            "type": "object",
            "additionalProperties": true,
            "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
          },
          "provider": {
            "type": [
              "string",
              "null"
            ]
          },
          "model": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string"
          },
          "applied_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "dismissed_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "discarded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "additionalProperties": true
      }
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/developer/ai/operations/drafts/{id}/save

Mark an operational draft save

Auth: Account Bearer JWT
Scope: workspace.view plus all-products scope and the permission for the stored tool type.
Returns: HTTP 200: draft.
Notes: Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        "tool_type": {
          "type": "string"
        },
        "generated_payload_json": {
          "type": "object",
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "applied_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "dismissed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "discarded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/developer/ai/operations/drafts/{id}/apply

Mark an operational draft apply

Auth: Account Bearer JWT
Scope: settings.manage and all-products scope plus all-products scope and the permission for the stored tool type.
Returns: HTTP 200: draft.
Notes: Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        "tool_type": {
          "type": "string"
        },
        "generated_payload_json": {
          "type": "object",
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "applied_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "dismissed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "discarded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

POST /api/developer/ai/operations/drafts/{id}/dismiss

Mark an operational draft dismiss

Auth: Account Bearer JWT
Scope: workspace.view plus all-products scope and the permission for the stored tool type.
Returns: HTTP 200: draft.
Notes: Updates the stored draft review status only. Applying does not execute the suggested action or send anything. The stored context permissions must also be satisfied; legacy drafts with unknown context require analytics.view and marketing.view. Missing, foreign-workspace and unauthorized-tool/context drafts return 404 without modification.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        "tool_type": {
          "type": "string"
        },
        "generated_payload_json": {
          "type": "object",
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "applied_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "dismissed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "discarded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.

DELETE /api/developer/ai/operations/drafts/{id}

Mark an operational draft discarded

Auth: Account Bearer JWT
Scope: settings.manage, workspace.view, all-products scope and the permission for the stored tool type.
Returns: HTTP 200: draft.
Notes: Soft status change to discarded, not physical record erasure or cancellation of previously executed work.

Request, response and error reference

No request body fields are read by this operation.

HTTP 200 response (application/json)

{
  "type": "object",
  "properties": {
    "draft": {
      "type": "object",
      "properties": {
        "id": {
          "anyOf": [
            {
              "type": "integer",
              "minimum": 1
            },
            {
              "type": "string",
              "pattern": "^[1-9][0-9]*$"
            }
          ],
          "description": "A positive identifier. PostgreSQL bigint fields can be decimal strings; preserve them without lossy numeric conversion."
        },
        "tool_type": {
          "type": "string"
        },
        "generated_payload_json": {
          "type": "object",
          "additionalProperties": true,
          "description": "Operation-specific extension data; do not put credentials or unnecessary personal information here."
        },
        "provider": {
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "applied_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "dismissed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "discarded_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

Documented failures: 400, 401, 403, 404, 409, 500, 503.