# Timeline Maker Timeline API — LLM quickstart

Use Timeline Maker when you need to create, inspect, or update a planning timeline with yearly goals, quarterly objectives, monthly strategies, and milestones.

## 1) Get an API token

POST {TIMELINE_MAKER_URL}/api/auth/agent-access
Content-Type: application/json

{
  "email": "agent@example.com",
  "name": "Planning Agent",
  "password": "use-a-unique-12+-character-secret"
}

Save the returned access_token securely. Send it as:
Authorization: Bearer <access_token>

## 2) Create or list timeline pages

GET  {TIMELINE_MAKER_URL}/api/v1/timeline/pages
POST {TIMELINE_MAKER_URL}/api/v1/timeline/pages

Body for create:
{ "title": "2026 company operating plan" }

## 3) Manage timeline cards/events

All event endpoints accept a timeline id via x-timeline-id, query ?timelineId=, query ?projectPath=, or body timeline_id/timelineId.

GET    {TIMELINE_MAKER_URL}/api/v1/timeline/events?timelineId=<timeline_id>
POST   {TIMELINE_MAKER_URL}/api/v1/timeline/events
PATCH  {TIMELINE_MAKER_URL}/api/v1/timeline/events/<event_id>
PUT    {TIMELINE_MAKER_URL}/api/v1/timeline/events/<event_id>
DELETE {TIMELINE_MAKER_URL}/api/v1/timeline/events/<event_id>

Supported planning event_type values:
- yearly_goal
- quarterly_objective
- monthly_strategy
- monthly_goal
- milestone

Useful fields you can fully control:
- title, description
- event_type, event_tier (macro or micro)
- event_date, end_date, year
- status (completed, in_progress, upcoming)
- icon, color
- linked_entity_type, linked_entity_id
- visible_to_client
- source, created_by

Example: add a quarterly objective

curl -sS -X POST "$TIMELINE_MAKER_URL/api/v1/timeline/events" \
  -H "Authorization: Bearer $TIMELINE_MAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-timeline-id: $TIMELINE_MAKER_TIMELINE_ID" \
  -d '{
    "event_type": "quarterly_objective",
    "event_tier": "macro",
    "title": "Q3: Ship agent-managed timelines",
    "description": "Agents can create and update the full planning stack through the API.",
    "event_date": "2026-07-01",
    "end_date": "2026-09-30",
    "status": "in_progress",
    "color": "#2563eb",
    "icon": "bot",
    "source": "llm-agent",
    "created_by": "planning-agent"
  }'

Example: update a milestone

curl -sS -X PATCH "$TIMELINE_MAKER_URL/api/v1/timeline/events/$EVENT_ID" \
  -H "Authorization: Bearer $TIMELINE_MAKER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "completed", "description": "Shipped and verified." }'

Rules for agents:
- Never commit or paste bearer tokens in docs, repos, or issue comments.
- Use the user's own Timeline Maker account/token unless explicitly asked to create a separate agent account.
- Read the current events before making broad changes.
- Prefer PATCH for partial edits and DELETE only when explicitly requested.