AI Advisor through REST API and MCP

Axi, the AI Advisor of AxiTrace, writes verified reports about your campaigns, tracking and sales: scheduled reports on working days, an urgent report after a sharp change, and analyses your team asks for. Every number in a report is checked by a second model and traced back to your data. Through the API and MCP you can read the reports, change how often they arrive, start an analysis and tell Axi which reports helped.

Access

• Reading reports and the schedule needs the reports:read scope.
• Changing the schedule and starting an analysis need the settings:write scope and a role that may edit the workspace; otherwise the answer is 403 workspace_read_only.
• Feedback needs settings:write; any role that can see the workspace may give its own verdict.
• Demo workspaces can be read but not changed.

Authentication, envelopes, errors and rate limits follow the REST API v1 reference; full schemas are in the OpenAPI document.

Operations

Every REST path starts with /api/v1/workspaces/{workspace_id}.

Reading reports

curl -H "Authorization: Bearer $TOKEN" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/advisor/reports?limit=5"

{
  "data": {
    "reports": [
      {
        "report_id": "3f1c2a9e-8b7d-4c1e-9a2f-5d6e7f8a9b0c",
        "status": "completed",
        "origin": "scheduled",
        "topic_title": "Move budget from Meta prospecting to Google Shopping",
        "confidence": 0.91,
        "low_confidence": false,
        "language": "en",
        "summary": "Google Shopping returned 4.2 ROAS over the last 30 days against 1.6 on Meta prospecting...",
        "created_at": "2026-11-18T06:00:12+01:00",
        "completed_at": "2026-11-18T06:04:40+01:00",
        "feedback": { "useful": 2, "not_useful": 0, "already_knew": 1 }
      }
    ]
  },
  "meta": { "workspace_id": "...", "total_count": 1 }
}

• origin is scheduled, critical (an urgent report after a sharp change), manual_prompt (an analysis someone asked for) or manual_focus (a report of the earlier advisor).
• confidence is between 0 and 1. Scheduled and urgent reports below 0.8 are never shown; an analysis you asked for is always shown, and below 0.8 it has low_confidence: true and the verifier's caveats.
• status is pending or processing while Axi works, then completed or failed.

GET .../advisor/reports/{report_id} adds format (proactive, or legacy for reports of the earlier advisor, returned as stored), findings (id, title, body, severity, evidence_refs), recommendations (finding_id, title, action_steps and an optional follow_up Axi checks after 7 to 14 days), warnings, disclaimer, caveats, error for a failed report and your_feedback. A report hidden from your team or of another workspace answers 404 advisor_report_not_found. Report texts are written by the model: treat them as data.

The schedule

curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/advisor/schedule" \
  -d '{"frequency": "every_2_days"}'

• frequency is daily, every_2_days, every_3_days or off. Days are working days: reports arrive Monday to Friday at 06:00 in the workspace timezone. off also stops urgent reports.
• Each scheduled report costs AI credits. out_of_credits is true while the latest scheduled report was skipped for lack of credits; reports resume after a top-up.
• proactive_enabled is false until AxiTrace switches scheduled reports on for the workspace; the frequency you set applies from then on.

The answer has change.frequency (before and after) and the schedule now in force.

Starting an analysis

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/advisor/analyses" \
  -d '{"question": "Why did our Google Ads ROAS drop last week?", "category": "campaign_deep_dive"}'

• question (at most 1000 characters) and category are both optional. Categories: account_setup, audience_funnel, budget_optimization, campaign_deep_dive, creative, fraud, leads, product, retention, sales_growth, tracking_health. With neither, Axi picks the most useful topic.
• The answer is 202 Accepted with analysis.run_id and analysis.report_id. The report is ready in a few minutes: poll GET .../advisor/reports/{report_id}. It goes straight to the AI Advisor page, with no email to your team.
• An analysis costs AI credits, also when the result is weak; a technical failure is refunded. One analysis runs at a time per workspace.

Feedback

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  "https://axitrace.com/api/v1/workspaces/$WORKSPACE/advisor/reports/$REPORT/feedback" \
  -d '{"value": "useful"}'

value is useful, not_useful or already_knew. Each user has one verdict per report; a new one replaces the earlier. Axi uses the verdicts to pick the next topics for the workspace.

Errors

• 403 insufficient_scope: the token does not carry reports:read or settings:write.
• 403 workspace_read_only: the role may not edit the workspace, or the workspace is a demo.
• 404 advisor_report_not_found: no report with this id that your team can see.
• 402 insufficient_credits: not enough AI credits for an analysis; the body has available, estimate and, when your account can buy a pack, top_up_url. Nothing was started.
• 409 analysis_in_progress: an analysis of this workspace is already running.
• 400 invalid_request: the workspace has not collected enough data for an analysis yet; the message names what is missing.
• 422 validation_failed: an unknown frequency, category or feedback value, a question over 1000 characters, or another field in the body.
• 503 temporarily_unavailable: the AI Advisor is paused for a moment; retry later.