🤖 EasyRoadmap API - AI Agent Guide

This guide is specifically designed for AI coding assistants (GitHub Copilot, Cursor, Claude, etc.) to effectively use the EasyRoadmap API for project management and development tracking.

Overview

EasyRoadmap API enables AI agents to manage development roadmaps, track progress, and maintain a "development memory" of decisions and changes. The API is optimized for AI workflows with bulk operations and automatic journaling.

Key Principles

1. Context First: Always start by fetching workspace context
2. Bulk Operations: Use the workflow/bulk endpoint for efficiency
3. Document Changes: Include reasoning with _context for automatic journaling
4. Track Decisions: Record significant architectural choices

Authentication

Authorization: Bearer er_live_your_api_key

Required Scopes

Scope	Description
workspaces:read	View workspaces, lanes, items
workspaces:write	Create, update, delete workspaces
items:read	View items and comments
items:write	Create, update, delete items
memory:read	View journal and decisions
memory:write	Create journal entries and decisions

Recommended Workflow

Step 1: Get Workspace Context

Start every session by understanding the current state:

GET /api/v1/workspaces/{workspaceId}/workflow/context

Returns:

• All lanes with their items
• Recent journal entries
• Important decisions
• Pending action items

Step 2: Review Recent Decisions

Check what architectural decisions have been made:

GET /api/v1/workspaces/{workspaceId}/decisions?limit=10

Step 3: Make Changes with Bulk Operations

Use the bulk endpoint to make multiple changes atomically:

POST /api/v1/workspaces/{workspaceId}/workflow/bulk

{
  "operations": [
    {
      "op": "createItem",
      "lane": "In Progress",
      "data": {
        "title": "Implement user authentication",
        "priority": "high",
        "description": "Add OAuth2 login flow"
      }
    },
    {
      "op": "updateItem",
      "itemId": "it_abc123",
      "data": {
        "status": "done",
        "progress": 100
      }
    }
  ],
  "_context": {
    "reasoning": "Starting auth implementation, marking research as complete",
    "autoJournal": true
  }
}

Step 4: Record Important Decisions

When making architectural decisions, record them:

POST /api/v1/workspaces/{workspaceId}/decisions

{
  "title": "Use PostgreSQL over MongoDB",
  "category": "technology",
  "status": "accepted",
  "context": "Need strong ACID compliance for financial data",
  "decision": "PostgreSQL with TypeORM for the data layer",
  "consequences": [
    "Better transaction support",
    "Requires schema migrations",
    "Team familiar with SQL"
  ]
}

Available Operations

Bulk Operation Types

Operation	Required Fields	Description
createItem	lane, data.title	Create a new item in a lane
updateItem	itemId, data	Update an existing item
deleteItem	itemId	Delete an item
moveItem	itemId, toLane	Move item to different lane
createLane	data.name	Create a new lane

Item Properties

Property	Type	Description
title	string	Item title (required)
description	string	Markdown description
priority	low | medium | high | critical	Priority level
status	planned | in_progress | done | blocked	Current status
progress	0-100	Completion percentage
startDate	ISO 8601	Start date
endDate	ISO 8601	End date
assignee	string	Assigned person/team
tags	string[]	Labels for categorization

Best Practices for AI Agents

1. Always Provide Context

Include _context.reasoning to explain why changes are being made:

"_context": {
  "reasoning": "User requested feature X, creating tasks to implement it",
  "autoJournal": true
}

2. Use Lane Names, Not IDs

The bulk API accepts lane names for convenience:

{
  "op": "createItem",
  "lane": "In Progress",
  "data": { "title": "New task" }
}

3. Batch Related Changes

Group related changes in a single bulk operation for atomicity:

{
  "operations": [
    { "op": "createLane", "data": { "name": "Sprint 5" } },
    { "op": "createItem", "lane": "Sprint 5", "data": { "title": "Task 1" } },
    { "op": "createItem", "lane": "Sprint 5", "data": { "title": "Task 2" } }
  ]
}

4. Record Architectural Decisions

When suggesting significant changes, create a decision record:

POST /api/v1/workspaces/{id}/decisions
{
  "title": "Adopt React Query for data fetching",
  "category": "technology",
  "status": "proposed",
  "context": "Current fetch logic is scattered and hard to maintain",
  "decision": "Use React Query for all API calls"
}

Error Handling

All errors follow RFC 7807 Problem Details:

{
  "type": "https://easyroadmap.app/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "title is required",
  "errors": [
    { "field": "title", "message": "Required field missing" }
  ]
}

Common Error Types

Status	Type	Cause
400	validation-error	Invalid request data
401	unauthorized	Missing or invalid API key
403	forbidden	Insufficient scopes
404	not-found	Resource doesn't exist
429	rate-limited	Too many requests

Quick Reference