Ask the Copilot

Run the Arabic-aware Marketing Copilot for one instruction and get back its answer plus a live, multi-step plan.

POST/api/v1/copilot/ask

Requirescopilot

Run eWasl's Marketing Copilot — an Arabic-aware agent that analyses your ad performance, retrieves your brand voice, policy-checks copy, and plans multi-step work — for a single instruction. The agent calls read tools across your ads and social data as needed (up to 8 tool rounds) and returns its final answer plus the live todo plan it produced.

Pass the returned sessionId back on your next call to continue the same plan.

Ad write actions (pausing campaigns, toggling auto-pilot) are only available when your API key also holds the ads:write scope. With the copilot scope alone, the copilot is read + planning only — it can never change a live ad platform.

Body Parameters

messagestringRequired

Your instruction or question for the copilot. Max 4000 characters. Arabic or English.

sessionIdstring (uuid)Required

Continue an existing session/plan. Omit to start a new session — the response returns the new sessionId.

locale'ar' | 'en'Optional

Default: ar

Reply language. Defaults to Arabic.

Response

data.sessionIdstring (uuid)

The session this turn belongs to. Reuse it to continue the plan.

data.replystring

The copilot's final natural-language answer.

data.todosarray

The live, ordered plan the copilot produced — each item has position, text, and status (pending | in_progress | done | skipped).

data.usageobject | null

Token usage for the turn (inputTokens, outputTokens).

Response Example

{
  "data": {
    "sessionId": "9c3f0a1e-7b2d-4e54-9c2a-1f3b6d8e0a44",
    "reply": "راجعت آخر 7 أيام: حملة \"عروض رمضان\" هي الأفضل (ROAS 4.1). أقترح خطة من 3 خطوات…",
    "todos": [
      { "position": 0, "text": "تحليل أداء آخر 7 أيام", "status": "done" },
      { "position": 1, "text": "اقتراح إعادة توزيع الميزانية", "status": "in_progress" },
      { "position": 2, "text": "صياغة نص إعلاني متوافق مع السياسات", "status": "pending" }
    ],
    "usage": { "inputTokens": 5123, "outputTokens": 412 }
  }
}

Status Codes

200 Copilot ran successfully.

403 API key is missing the copilot scope, or the plan is not Professional/Enterprise.

422 Validation error (e.g. empty or over-long message).

502 The copilot could not complete — safe to retry.

503 Copilot temporarily unavailable.

Example

curl -X POST https://app.ewasl.com/api/v1/copilot/ask \
  -H "Authorization: Bearer ewasl_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "message": "كيف أداء حملاتي هذا الأسبوع وما الذي تنصح بتعديله؟", "locale": "ar" }'