🌞 Connect to GoalsWon by API, MCP or CLI

Access your GoalsWon data programmatically — build integrations, connect AI assistants, reduce the hassle of manual data entry, or manage your goals from the terminal - we’re here to support, your coach is on board and the sky is the limit!

What You Can Do

Connect AI assistants (Claude, Gemini, etc.) to your GoalsWon data via MCP
Integrate with automations — hook in with Zapier, Make, n8n, IFTTT, etc.
Pull your data — goals, daily results, monthly and yearly targets, inbox, wins, and chat history
Create and update goals — add goals, mark them done, manage monthly and yearly targets
Send messages and images to your coach
View your progress — completion rates, streaks, and trends over any date range
Search your chat history with your coach
Build custom integrations — spreadsheets, dashboards, automations, whatever you need

Three tools are available:

Tool	Best For
REST API	Custom integrations, apps, scripts
MCP Server	AI assistants that support MCP (Claude, Gemini, Cursor, etc.)
CLI	Quick access from your terminal

All three use the same API key for authentication.

Getting Started

1. Get Your API Key

Generate an API key from your GoalsWon account:

Open GoalsWon (web or mobile)
Go to Settings > API Access
Click Generate API Key
Copy your key — it’s only shown once

Your API key is personal and gives full access to your account. Keep it secret.

2. Try It Out

# Check the API is reachable
curl https://api.goalswon.com/api/v1/health

# Fetch your profile
curl -H "X-GoalsWon-Key: YOUR_API_KEY" \
  https://api.goalswon.com/api/v1/me

# List today's goals
curl -H "X-GoalsWon-Key: YOUR_API_KEY" \
  "https://api.goalswon.com/api/v1/goals?date=2026-03-06"

Authentication

Include your API key in every request using the X-GoalsWon-Key header:

X-GoalsWon-Key: YOUR_API_KEY

Managing Your Keys

You can create multiple keys (e.g. one for Claude, one for a script) and revoke them individually.

POST   /api/v1/me/api-keys          — Create a new key
GET    /api/v1/me/api-keys          — List your keys
DELETE /api/v1/me/api-keys/:keyId   — Revoke a key

Access Levels

Your API access is controlled by three independent permissions, which you can toggle from Settings > API Access in the GoalsWon app:

Permission	What it allows	Default
Read	Fetch your profile, goals, targets, days, months, inbox, wins, recurring goals, progress, and chat history	Off
Chat	Send messages and images to your coach	Off
Write	Create, update, and delete goals, targets, inbox items, and recurring goals, and manage day/month submissions	Off

These are stored on your user document as apiReadAccess, apiChatAccess, and apiWriteAccess. The API middleware checks them on every request — if a permission is off, the corresponding endpoints return 403 Forbidden.

Each permission is independent. For example, you can enable Read and Chat but leave Write off if you only want to view your data and message your coach without risking accidental changes.

Enabling Write access requires typing a confirmation word as a safety measure, since write operations can modify or delete your data.

Rate Limits

To keep things fair, requests are rate-limited per account:

Window	Limit
Per minute	25 requests
Per day	1,000 requests

Response headers tell you how many requests you have left:

X-RateLimit-Remaining-Minute
X-RateLimit-Remaining-Day

If you exceed a limit, you’ll get a 429 response with a Retry-After header.

Data Safety

All deletes made via the API (including MCP and CLI) are archived before removal. Deleted documents are copied to archive/{userId}/{collection}/{docId} with a timestamp before being removed. This means accidental mass-deletes can be recovered.

Archive retention: 30 days (auto-purged after that)
Only API deletes are archived — deletes from the app are not affected
Restore is manual for now — contact support if you need data recovered

REST API Reference

Base URL: https://api.goalswon.com/api/v1

Response Format

// Single item
{ "data": { ... } }

// List with pagination
{
  "data": [ ... ],
  "meta": {
    "hasMore": true,
    "nextCursor": "abc123"
  }
}

// Error
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Goal not found"
  }
}

Pagination

List endpoints return up to 50 items by default. Use these query parameters to page through results:

?limit=50 — Items per page (max 200)
?cursor=abc123 — Continue from where the last page left off (use the nextCursor value from meta)

Your Profile

Method	Path	Description
`GET`	`/me`	Your profile and stats
`GET`	`/me/coach`	Your coach’s public profile

/me/coach returns the same coach details the app shows: name, description, coachingApproach, location, timezone, favouriteQuote, funFact, image, latestMilestone, nextTarget, and statusImage.

Returns your account info, coach name, and counters:

{
  "data": {
    "id": "abc123",
    "email": "you@example.com",
    "name": "Alex",
    "avatar": "https://...",
    "timezone": "America/New_York",
    "isCoach": false,
    "coachName": "Joel",
    "counters": {
      "goalsTotal": 142,
      "recurrentGoalsTotal": 5,
      "milestonesTotal": 3,
      "yearlyTargetsTotal": 4,
      "yearlyTargetsCompleted": 1
    }
  }
}

Goals

Method	Path	Description
`GET`	`/goals`	List your goals
`GET`	`/goals/:id`	Get a single goal
`POST`	`/goals`	Create a goal
`PUT`	`/goals/:id`	Update a goal
`POST`	`/goals/:id/complete`	Mark a goal done, partial, or pending
`DELETE`	`/goals/:id`	Delete a goal
`GET`	`/goals/recurring`	List your recurring goal templates
`GET`	`/goals/recurring/:id`	Get a single recurring goal
`POST`	`/goals/recurring`	Create a recurring goal
`PUT`	`/goals/recurring/:id`	Update a recurring goal
`DELETE`	`/goals/recurring/:id`	Delete a recurring goal

Filters for listing: ?date=YYYY-MM-DD, ?status=done|partial|pending

Recurring goals appear in the daily goal list with isRecurring: true. Use /goals/recurring to manage the templates and their schedules.

Create a goal:

{
  "name": "Morning meditation",
  "date": "2026-03-10",
  "description": "10 minutes mindfulness",
  "tag": "green"
}

Field	Required	Description
`name`	Yes	Goal name
`date`	No	Date (YYYY-MM-DD). Defaults to today based on your account timezone.
`description`	No	Description text
`tag`	No	Colour name (see below)

All fields can also be updated via PUT, plus isDone and isPartiallyDone (booleans).

Tags are colours matching the colour picker in the app:

red, orange, green, blue, purple, pink, yellow, teal, cyan, lavender

Leave tag empty or omit it for no colour. Tags work the same across goals, recurring goals, monthly targets, and inbox items.

Recurring goals: When listing goals for a date, recurring goals that haven’t been interacted with yet are returned with an ID prefixed recurring_ (e.g., recurring_abc123). You can complete or update these directly — the API will automatically instantiate them as real goals on first interaction.

Mark a goal:

{ "status": "done" }

Status can be done, partial, or pending.

Submitted days are read-only. Once a day has been submitted (reviewed by your coach), its goals cannot be created, updated, marked, or deleted via the API. You’ll receive a 409 response with code DAY_SUBMITTED. You can still read goals on submitted days.

Create a recurring goal:

{
  "name": "Morning run",
  "recurrencePattern": "weekly",
  "days": [1, 3, 5],
  "startDate": "2026-03-10",
  "rollOver": true,
  "tag": "green"
}

Field	Required	Description
`name`	Yes	Goal name
`recurrencePattern`	Yes	`daily`, `weekly`, `monthly`, or `yearly`
`days`	Weekly	Array of weekday numbers: 1=Monday through 7=Sunday
`startDate`	No	Start date (YYYY-MM-DD). Defaults to today. For monthly/yearly, the day-of-month is used.
`endDate`	No	End date (YYYY-MM-DD), or omit/null for never
`rollOver`	No	`true` to roll over incomplete goals to the next day. Defaults to `false`
`description`	No	Description text
`tag`	No	Colour name (e.g., `red`, `blue`, `yellow`)

For monthly, the goal repeats on the same day-of-month as the start date (e.g. start on March 6th → repeats every 6th). For yearly, it repeats on the same month and day.

Days

View your daily submissions and how you did each day.

Method	Path	Description
`GET`	`/days`	List your day submissions
`GET`	`/days/:YYYYMMDD`	Full day detail with all goals
`POST`	`/days/:YYYYMMDD/submit`	Submit a day
`POST`	`/days/:YYYYMMDD/unsubmit`	Unsubmit a day

Filters: ?from=YYYY-MM-DD, ?to=YYYY-MM-DD, ?submitted=true|false

Defaults to the last 30 days if no from date is specified. Use ?from= with an earlier date to fetch further back.

Day detail includes a summary:

{
  "data": {
    "id": "20260210",
    "date": "2026-02-10T00:00:00Z",
    "isSubmitted": true,
    "clientComment": "Tough day but got through it",
    "coachComment": "Great effort, keep it up!",
    "mood": 4,
    "goals": [ ... ],
    "summary": {
      "total": 15,
      "done": 9,
      "partial": 0,
      "pending": 6,
      "completionRate": 60
    }
  }
}

clientComment — your message when submitting the day (null if none)
coachComment — your coach’s reply (null if none)
mood — your mood rating when submitting (1–5, null if not set)

Monthly Targets

Method	Path	Description
`GET`	`/targets`	List your monthly targets
`GET`	`/targets/:id`	Get a single target
`POST`	`/targets`	Create a target
`PUT`	`/targets/:id`	Update a target
`DELETE`	`/targets/:id`	Delete a target

Filter: ?month=YYYYMM, ?status=done|partial|pending

Create a target:

{
  "name": "Read 3 books",
  "month": "202603",
  "tag": "blue",
  "description": "Fiction or non-fiction",
  "rollOver": true,
  "yearlyTargetId": "abc123"
}

Field	Required	Description
`name`	Yes	Target name
`month`	Yes	Month in YYYYMM format
`description`	No	Description text
`tag`	No	Colour name (e.g., `red`, `blue`, `yellow`)
`rollOver`	No	`true` to roll over incomplete targets to the next month
`yearlyTargetId`	No	ID of a yearly target to link to (from `/yearly-targets`). Set to `null` to unlink.

All fields except name and month can also be updated via PUT.

Submitted months are read-only. Once a month has been submitted, its targets cannot be created, updated, or deleted via the API. You’ll receive a 409 response with code MONTH_SUBMITTED. You can still read targets in submitted months.

Yearly Targets

Method	Path	Description
`GET`	`/yearly-targets`	List your yearly targets
`GET`	`/yearly-targets/:id`	Get a yearly target with linked monthly targets
`POST`	`/yearly-targets`	Create a yearly target
`PUT`	`/yearly-targets/:id`	Update a yearly target
`DELETE`	`/yearly-targets/:id`	Delete a yearly target

Create a yearly target:

{
  "name": "Run a marathon",
  "emoji": "🏃"
}

Both name and emoji are required. The emoji appears alongside linked monthly targets in the app.

Update via PUT — you can change name, emoji, isDone (boolean), and reflection (text). Setting isDone: true marks the yearly target as complete. Use reflection to add your thoughts when completing it — this appears in your chat history.

Delete removes the yearly target. Monthly targets that were linked to it will retain the yearlyTargetName and yearlyTargetEmoji they were created with, but the link becomes inactive.

The response for GET /yearly-targets/:id includes a linkedTargets array showing all monthly targets linked to it (via yearlyTargetId).

Months

Method	Path	Description
`GET`	`/months`	List your month submissions
`GET`	`/months/:YYYYMM`	Month detail with targets and completion summary
`POST`	`/months/:YYYYMM/submit`	Submit a month
`POST`	`/months/:YYYYMM/unsubmit`	Unsubmit a month

Submit/unsubmit works the same as days — optional comment and mood (1–5). You can only submit the current month or past months. Submitting locks the month’s targets.

Chat

Access your coaching chat history and send messages — including images.

Method	Path	Description
`GET`	`/chat/messages`	List messages
`GET`	`/chat/messages/:id`	Get a single message
`POST`	`/chat/messages`	Send a text message
`POST`	`/chat/messages/image`	Send an image message

Filters: ?search=meditation, ?from=YYYY-MM-DD, ?to=YYYY-MM-DD, ?systemMessages=false

System messages (e.g. “Repeating goal added”) are included by default. Set ?systemMessages=false to hide them.

Messages with images include an image URL and isImageMessage: true in the response. The sentBy field shows the sender’s display name (not an internal ID).

Send a text message:

{ "text": "Had a great week!" }

Send an image: Use multipart/form-data with an image field. Optional text field for a caption.

curl -X POST "https://api.goalswon.com/api/v1/chat/messages/image" \
  -H "X-GoalsWon-Key: YOUR_API_KEY" \
  -F "image=@photo.jpg" \
  -F "text=Check out my progress!"

Image limits:

Max file size: 5MB
Supported formats: JPEG, PNG, GIF, WebP
Images are automatically resized (max 1000x1000) and compressed
Upload limit: 30 per hour, 100 per day

Inbox

Your inbox holds undated goals — ideas and tasks you haven’t scheduled yet.

Method	Path	Description
`GET`	`/inbox`	List inbox items
`GET`	`/inbox/:id`	Get a single inbox item
`POST`	`/inbox`	Add an item to your inbox
`PUT`	`/inbox/:id`	Update an inbox item
`POST`	`/inbox/:id/schedule`	Schedule — converts to a goal on a date
`DELETE`	`/inbox/:id`	Delete an inbox item

Filter: ?status=done|pending

Add an inbox item:

{
  "name": "Research holiday destinations",
  "description": "Look at flights and hotels",
  "tag": "cyan"
}

Only name is required. description and tag (colour name) are optional.

Update an inbox item — all fields are optional:

{
  "name": "Updated name",
  "description": "New description",
  "tag": "green",
  "isDone": true,
  "isPartiallyDone": false
}

Schedule an inbox item — assigns a date, converting it into a goal. The inbox item is removed.

POST /inbox/{id}/schedule

{
  "date": "2026-03-10"
}

date is optional — defaults to today (in your timezone). Returns the newly created goal.

Wins

Method	Path	Description
`GET`	`/wins`	List your wins

Returns your wins (previously called milestones), each with id, name, date, and emoji. The milestonesTotal counter in /me keeps its legacy name.

Progress Report

Get a summary of how you’re doing over any date range.

Method	Path	Description
`GET`	`/progress`	Your progress report (default: last 30 days)

Filters: ?from=YYYY-MM-DD, ?to=YYYY-MM-DD

Response includes:

Overview — total days, submitted days, goals done/partial/pending, completion rate, current streak
By tag — breakdown of completion rates per goal category
Daily rates — completion percentage for each day in the range

For Coaches

If your API key belongs to a coach account, three extra endpoints are available:

Method	Path	Description
`GET`	`/clients`	List your clients
`GET`	`/clients/:id`	Single client detail
`GET`	`/clients/:id/summary`	Client summary — goals, recent chat, streaks

These return 403 for non-coach accounts.

MCP Server — Connect Your AI Assistant

The GoalsWon MCP server lets AI assistants read and manage your goals directly. It works with any tool that supports the Model Context Protocol — including Claude, Gemini, Cursor, Windsurf, and others.

Setup

Install the MCP server:
```
npm install -g @goalswon/mcp-server
```
Add it to your AI assistant’s MCP configuration. The details vary by tool — here are some common ones:

Claude Code:
```
claude mcp add goalswon -- goalswon-mcp
```
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on Mac, %APPDATA%\Claude\claude_desktop_config.json on Windows):
```
{
  "mcpServers": {
    "goalswon": {
      "command": "goalswon-mcp",
      "env": {
        "GOALSWON_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```
Other tools: Check your tool’s documentation for how to add an MCP server. You’ll need to point it at the goalswon-mcp command with your API key as the GOALSWON_API_KEY environment variable.
Your AI assistant can now access your GoalsWon data.

What Your AI Assistant Can Do

Capability	Description
List goals	See your goals filtered by date and status
Create goals	Add new goals for any date
Update goal status	Mark goals as done, partial, or pending
View day details	See a full day with all goals and completion summary
Monthly & yearly targets	Create, update, and track monthly and yearly targets
Recurring goals	Set up repeating goals (daily, weekly, etc.)
Inbox	Manage undated goals and schedule them
Search chat	Search your coaching chat history
Send messages	Send a message to your coach
Progress report	Get completion rates, streaks, and trends
And more…	Wins, submit days/months, upload images, etc.

Example

Ask your AI assistant things like:

“How did I do this week?”
“Create a goal ‘Morning run’ for tomorrow”
“Mark my meditation goal as done”
“What’s my current streak?”
“Search my chat for messages about sleep”
“Share my week themes with my coach”
“Post the workout screenshots”

CLI — Terminal Access

Manage your goals from the command line.

Install

npm install -g @goalswon/cli

Authenticate

goalswon auth login YOUR_API_KEY
goalswon auth status    # Verify it worked

Commands

# Your profile
goalswon auth status

# Goals
goalswon goals list --today                    # Today's goals
goalswon goals list --yesterday                # Yesterday's goals
goalswon goals list --tomorrow                 # Tomorrow's goals
goalswon goals list --date 2026-03-06          # Specific date
goalswon goals list --status pending           # Filter by status
goalswon goals create "Exercise" --today
goalswon goals complete <goalId>               # Mark done
goalswon goals complete <goalId> --status partial
goalswon goals delete <goalId>
goalswon goals recurring                       # Your recurring templates

# Days
goalswon days list --from 2026-03-01 --to 2026-03-31
goalswon days show --today                     # Today's detail with goals
goalswon days show --yesterday                 # Yesterday
goalswon days show 20260306                    # Specific date

# Monthly targets
goalswon targets list --month 202603
goalswon targets create "Read 3 books" --month 202603

# Chat
goalswon chat list --limit 10                  # Recent messages
goalswon chat list --search "meditation"       # Search your chat

# Progress
goalswon progress                              # Last 30 days
goalswon progress --from 2026-01-01 --to 2026-03-01

Security

Your API key gives access only to your own data
Keys are stored securely — we never see your raw key after creation
You can revoke any key at any time from Settings or via the API
All requests are encrypted via HTTPS

Need Help?

Email: support@goalswon.com
In-app chat: Message your coach — they can help with API setup too