Skip to content
SoundSyncAudio software platform

API reference

Operational AI Draft API

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

Start with getting startedExplore 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.

Context includes limited recent products and deals plus 30-day order aggregates. The range input labels the context; it does not change that 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 returns up to 50 recent developer-scoped rows; raw IDs may be decimal strings.

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.
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 a limited recent product/deal set and 30-day order aggregates; range is a label, not a general reporting date filter. A null draftId with persistenceWarning means persistence failed or is unavailable; do not treat it as a saved draft. 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.

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

Draft an explanation of current analytics

Auth
Account Bearer JWT
Scope
analytics.view.
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 a limited recent product/deal set and 30-day order aggregates; range is a label, not a general reporting date filter. A null draftId with persistenceWarning means persistence failed or is unavailable; do not treat it as a saved draft. 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.

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

Draft a promotion plan

Auth
Account Bearer JWT
Scope
marketing.view.
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 a limited recent product/deal set and 30-day order aggregates; range is a label, not a general reporting date filter. A null draftId with persistenceWarning means persistence failed or is unavailable; do not treat it as a saved draft. 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.

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

Draft automation recommendations

Auth
Account Bearer JWT
Scope
marketing.manage 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 a limited recent product/deal set and 30-day order aggregates; range is a label, not a general reporting date filter. A null draftId with persistenceWarning means persistence failed or is unavailable; do not treat it as a saved draft. 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.

GET /api/developer/ai/operations/drafts

List the latest 50 workspace operational drafts

Auth
Account Bearer JWT
Scope
workspace.view.
Returns
HTTP 200: drafts.
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.

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

Mark an operational draft save

Auth
Account Bearer JWT
Scope
workspace.view.
Returns
HTTP 200: draft.
Notes
Updates the stored draft review status only. Applying does not execute the suggested action or send anything. IDs remain developer-scoped; a missing/foreign draft returns 404.
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.

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

Mark an operational draft apply

Auth
Account Bearer JWT
Scope
settings.manage and all-products scope.
Returns
HTTP 200: draft.
Notes
Updates the stored draft review status only. Applying does not execute the suggested action or send anything. IDs remain developer-scoped; a missing/foreign draft returns 404.
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.

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

Mark an operational draft dismiss

Auth
Account Bearer JWT
Scope
workspace.view.
Returns
HTTP 200: draft.
Notes
Updates the stored draft review status only. Applying does not execute the suggested action or send anything. IDs remain developer-scoped; a missing/foreign draft returns 404.
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.

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

Mark an operational draft discarded

Auth
Account Bearer JWT
Scope
settings.manage and all-products scope.
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.