Skip to main content

REST API

The TodoMate REST API lets you manage your todos, goals, and vision from any HTTP client. This guide walks you through getting a token and making your first request using curl.

Prerequisites​

  • A todo.ac account (sign in with GitHub)
  • A Pro subscription — required to generate an API key

Step 1 — Install the GitHub CLI​

The easiest way to get a GitHub access token is with the GitHub CLI.

# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux — see https://github.com/cli/cli/blob/trunk/docs/install_linux.md

Step 2 — Get a GitHub access token​

gh auth login
gh auth token

Copy the printed token — you'll use it in Step 4.

Step 3 — Get your API key​

Your API key authenticates your client with the API.

  1. Open todo.ac
  2. Go to Account → API Keys
  3. Tap Generate key, give it a name, and copy the value — it's shown once only

Step 4 — Get a TodoMate JWT​

Exchange your GitHub token for a short-lived JWT:

JWT=$(curl -s -X POST https://api.todo.ac/v1/auth/token \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -d '{"github_token": "YOUR_GITHUB_TOKEN"}' \
  | jq -r '.access_token')

echo $JWT

Note: jq is used here to parse the JSON response. Install it with brew install jq or your package manager.

Step 5 — List your todos​

curl https://api.todo.ac/v1/todos \
  -H "Authorization: Bearer $JWT" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY"

You should get back a JSON array of your todos.

Next steps​

Browse the full API Reference to explore all available endpoints — todos, goals, vision, and more.