Skip to content
2 min read · 381 words

API — Tasks & Email Analysis

POST /agents/{id}/email/analyze — analyze an email

Requires the email_analyzer tool → otherwise 403 {"detail": "This agent does not have email_analyzer tool enabled"}.

Body: {"email_text": "string"}

bash
curl -X POST http://localhost:8001/agents/1/email/analyze \
  -H "Content-Type: application/json" \
  -d '{"email_text": "We need the Q3 report by Friday, and please book a review call."}'
json
{
  "analysis": {
    "summary": "Request for the Q3 report by Friday plus a review call.",
    "intent": "request",
    "priority": "high",
    "deadline": "Friday",
    "action_items": ["Prepare Q3 report", "Book review call"],
    "suggested_reply": "Thank you for your message..."
  },
  "tasks_created": [
    {
      "id": 7, "agent_id": 1, "title": "Prepare Q3 report",
      "description": "Created from email analysis. Intent: request",
      "priority": "high", "status": "open", "due_date": "Friday",
      "source_type": "email", "created_at": "2026-07-16T10:05:00"
    }
  ]
}

Behavior:

  • analysis is the raw LLM extraction (shape guaranteed by the analyzer prompt, not by a response model).
  • tasks_created is empty unless the agent also has task_creator — then one task per action_item, with due_date passed through normalize_due_date.
  • Side effects: email_analyzer ToolCall (+ task_creator ToolCall when tasks were created).
  • 500 on LLM/parse failure — a failed ToolCall is committed first (Error Handling).

The richer alternative (dedicated reply + quality review + full trace) is the workflow endpoint.

GET /agents/{id}/tasks — list tasks

200 → TaskResponse[], newest first. 404 if the agent is missing.

FieldNotes
priorityfrom analysis: low / medium / high (default medium)
statusopen (initial) / in_progress / completed
due_datefree-form string or null — see ORM Models
source_typealways "email" today

PUT /agents/tasks/{task_id}/status — update task status

Body: {"status": "open" | "in_progress" | "completed"}

bash
curl -X PUT http://localhost:8001/agents/tasks/7/status \
  -H "Content-Type: application/json" -d '{"status": "completed"}'

200 → the updated TaskResponse. 400 {"detail": "Invalid status. Use: open, in_progress, completed"} for anything else. 404 if the task doesn't exist.

Note the path — task ID only, not nested under an agent (/agents/tasks/{task_id}/status). Any status→status transition is allowed (including completed back to open); there is no transition graph.

PreviousAgents & ChatNextWorkflows