AI enhancement

Rewrite agent configuration text with AI.

Improve one agent prompt field

POST /ai-enhancement/enhance-field

Rewrites one agent configuration text (identity, personality, task, greeting, closing, escalation protocol or pronunciation guide) into a clearer, more effective version using the AI model. Nothing is saved; apply the result to your agent yourself.

Scope: ai:enhance

Body (application/json)

Field	Type	Required	Description
fieldType	string: agentIdentity, agentPersonality, agentTask, greetingMessage, closingMessage, escalationProtocol, pronunciationGuide	yes
text	string	yes	The current text to improve.

Example request

curl -X POST "https://api.foan.ai/api/v1/ai-enhancement/enhance-field" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fieldType":"greetingMessage","text":"hello this is acme calling about ur order"}'

Response 200

{
  "success": true,
  "data": {
    "fieldType": "greetingMessage",
    "originalText": "hello this is acme calling about ur order",
    "enhancedText": "Hello, this is Nina from Acme Stores. I'm calling about your recent order. Is this a good time to talk?"
  },
  "message": "Field enhanced successfully"
}

Errors

Code	When
400	Invalid body: unknown fieldType, empty text, or (multi) not 1 to 7 fields
401	Missing, invalid or revoked API key
403	Key lacks the ai:enhance scope
429	Rate limited: 30 per minute per IP and 20 per minute per API key (defaults)
500	The AI model call failed; the error message is passed through

Improve several agent prompt fields

POST /ai-enhancement/enhance-fields

Same as enhance-field for up to 7 fields at once; each field is rewritten independently and in parallel. If any one fails, the whole request fails.

Scope: ai:enhance

Body (application/json)

Field	Type	Required	Description
fields	array of object	yes

Example request

curl -X POST "https://api.foan.ai/api/v1/ai-enhancement/enhance-fields" \
  -H "Authorization: Bearer $FOAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":[{"fieldType":"agentIdentity","text":"you are ruhi from acme"},{"fieldType":"closingMessage","text":"ok bye"}]}'

Response 200

{
  "success": true,
  "data": {
    "results": [
      {
        "fieldType": "agentIdentity",
        "originalText": "you are ruhi from acme",
        "enhancedText": "You are Nina, a friendly customer care representative at Acme Stores."
      },
      {
        "fieldType": "closingMessage",
        "originalText": "ok bye",
        "enhancedText": "Thank you for your time. Have a wonderful day!"
      }
    ]
  },
  "message": "Fields enhanced successfully"
}

Errors

Code	When
400	Invalid body: unknown fieldType, empty text, or (multi) not 1 to 7 fields
401	Missing, invalid or revoked API key
403	Key lacks the ai:enhance scope
429	Rate limited: 30 per minute per IP and 20 per minute per API key (defaults)
500	The AI model call failed; the error message is passed through