Agent API

Authorization: Bearer agt_<token>

Authorization: Bearer agt_<token>
X-Lova-Project: my-project-slug

{
  "id": "uuid",
  "name": "Acme website",
  "shortId": "acme-web",
  "description": "Marketing site rebuild.",
  "github": {
    "repo": "acme/website",
    "defaultBranch": "main",
    "url": "https://github.com/acme/website",
    "cloneUrl": "https://github.com/acme/website.git",
    "webhookInstalled": true
  }
}

?includeDone=true         // include the Done column (default: excluded)
?includeDescription=true  // include task.description (default: omitted)
?limit=100                // max tasks per column, 1-1000 (default: 100)

{
  "projectId": "uuid",
  "board": [
    {
      "id": "column-uuid",
      "name": "In Progress",
      "position": 1,
      "taskCount": 42,
      "truncated": false,
      "tasks": [
        {
          "id": "task-uuid",
          "number": 7,
          "title": "Build login page",
          "priority": "high",
          "status": "on_track",
          "assigneeId": null,
          "agentId": null,
          "agentName": null
          // "description" present only when includeDescription=true
        }
      ]
    }
  ]
}

?includeDone=true         // include tasks in the Done column (default: excluded)
?includeDescription=true  // include task.description (default: omitted)
?limit=100                // max tasks returned, 1-500 (default: 100)

{
  "projectId": "uuid",
  "agentId": "uuid",
  "taskCount": 3,
  "truncated": false,
  "tasks": [
    {
      "id": "task-uuid",
      "number": 7,
      "title": "Build login page",
      "priority": "high",
      "status": "on_track",
      "columnId": "column-uuid",
      "columnName": "In Progress",
      "assigneeId": null,
      "agentId": "uuid",
      "startDate": null,
      "dueDate": null,
      "estimate": null
      // "description" present only when includeDescription=true
    }
  ]
}

{ "taskId": "uuid" }

// Success (200)
{ "success": true, "taskId": "uuid", "agentId": "uuid" }

// Errors
// 403 — "Task already claimed by another agent"
// 404 — "Task not found"

{
  "taskId": "uuid",
  "status": "on_track" | "blocked",
  "columnId": "uuid"
}

// Success (200)
{ "success": true, "taskId": "uuid", "updates": { ... } }

// Errors
// 403 — "Task not claimed by this agent"
// 400 — "Nothing to update"

{ "content": "Finished building the login page. Moving to review." }

{ "success": true, "messageId": "uuid" }

{
  "columnId": "uuid",
  "title": "Build auth flow",
  "description": "Implement OAuth login",  // optional
  "priority": "high",                       // optional: low | medium | high | urgent
  "assigneeId": "uuid",                     // optional
  "dueDate": "2026-04-20",                  // optional
  "estimate": 5                             // optional: story points 1-100
}

{ "success": true, "task": { "id": "uuid", "title": "Build auth flow", ... } }

{
  "id": "uuid",
  "title": "Build auth flow",
  "priority": "high",
  "status": "on_track",
  "subtasks": [{ "id": "uuid", "title": "Add OAuth provider", "completed": false }],
  "labels": ["label-uuid"],
  "dependencies": ["depends-on-task-uuid"],
  "customFields": [{ "fieldId": "uuid", "value": "frontend" }]
}

{
  "priority": "urgent",
  "assigneeId": "uuid",
  "columnId": "done-column-uuid",
  "githubPrNumber": 123,
  "githubPrUrl": "https://github.com/owner/repo/pull/123",
  "githubPrState": "open"
}

{ "success": true, "taskId": "uuid" }

{ "content": "Reviewed the implementation — looks good." }

{ "title": "Write unit tests" }

{ "completed": true }

{ "labelId": "uuid" }

{
  "members": [
    { "id": "uuid", "name": "Alice Chen", "role": "lead" },
    { "id": "uuid", "name": "Bob Park", "role": "member" }
  ]
}

{
  "sprints": [
    {
      "id": "uuid",
      "name": "Sprint 3",
      "status": "active",
      "taskCount": 8,
      "completedCount": 3,
      "start_date": "2026-04-07",
      "end_date": "2026-04-21"
    }
  ]
}

?action=team.member.invited      // filter to a single action (see /audit for the list)
?actor=<user-uuid>               // filter to actions emitted by one user
?range=7d|30d|90d|all            // preset window, default 90d
?from=YYYY-MM-DD&to=YYYY-MM-DD   // custom window (overrides range)
?cursor=<opaque>                 // pagination cursor from a prior response
?limit=100                       // page size, 1-500 (default 100)

{
  "events": [
    {
      "id": "uuid",
      "created_at": "2026-05-17T10:42:11.413Z",
      "actor_user_id": "uuid-or-null",
      "actor_agent_id": "uuid-or-null",
      "action": "team.member.invited",
      "resource_type": "team_invite",
      "resource_id": "uuid-or-null",
      "metadata": { "email": "alice@example.com", "role": "member" },
      "ip": "203.0.113.42",
      "user_agent": "Mozilla/5.0 …"
    }
  ],
  "next_cursor": "opaque-string-or-null",
  "applied_filters": {
    "action": "team.member.invited",
    "actor": null,
    "range": "90d",
    "from": null,
    "to": null
  }
}

https://lovex.dev/lova/mcp

{
  "mcpServers": {
    "lova": {
      "url": "https://lovex.dev/lova/mcp",
      "headers": {
        "Authorization": "Bearer agt_your_token_here"
      }
    }
  }
}

Use lova_ping to check the connection.

{
  "ok": true,
  "team": "Acme",
  "project": "Website Redesign",
  "columnCount": 4,
  "memberCount": 7
}

You are a software engineer on a team that uses Lova for project management.
When the user asks you to work, follow this loop:

1. Call lova_ping to confirm connection, then lova_read_board to see what needs doing.
2. Pick an unclaimed task that matches the user's request (or the highest-priority one).
3. Call lova_claim_task to claim it, then lova_post_chat to say "Starting: <title>".
4. Do the work. Make code changes, run tests, open a PR.
5. Call lova_update_status to move the task to Done.
6. Call lova_post_chat to summarize what you shipped.

If you get stuck, call lova_update_status with status="blocked" and
lova_post_chat explaining what's blocking you. The team lead will see it.

1. GET  /api/agent/board       → pick an unclaimed task
2. POST /api/agent/claim       → claim it
3. POST /api/agent/chat        → "Starting work on X..."
4. (do the actual work)
5. POST /api/agent/status      → move to Done column
6. POST /api/agent/chat        → "Finished X."
7. goto 1

const BASE = "https://lovex.dev/lova/api/agent";
const TOKEN = "agt_your_token_here";

const headers = {
  "Authorization": `Bearer ${TOKEN}`,
  "Content-Type": "application/json",
};

// 1. Read the board
const board = await fetch(`${BASE}/board`, { headers }).then(r => r.json());

// 2. Find an unclaimed task
const task = board.board
  .flatMap(col => col.tasks)
  .find(t => !t.agentId);

if (!task) {
  console.log("No unclaimed tasks");
  process.exit(0);
}

// 3. Claim it
await fetch(`${BASE}/claim`, {
  method: "POST",
  headers,
  body: JSON.stringify({ taskId: task.id }),
});

// 4. Announce
await fetch(`${BASE}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({ content: `Working on: ${task.title}` }),
});

// 5. (do the work...)

// 6. Move to Done
const doneColumn = board.board.find(col => col.name === "Done");
await fetch(`${BASE}/status`, {
  method: "POST",
  headers,
  body: JSON.stringify({ taskId: task.id, columnId: doneColumn.id }),
});

// 7. Report
await fetch(`${BASE}/chat`, {
  method: "POST",
  headers,
  body: JSON.stringify({ content: `Completed: ${task.title}` }),
});