103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
---
|
|
name: project-tracking
|
|
description: "SaaS project tracking: Airtable (spreadsheets+databases), Linear (issues+projects), and Notion (pages+databases). REST API integration via curl/Python."
|
|
version: 1.0.0
|
|
author: Hermes Agent
|
|
license: MIT
|
|
metadata:
|
|
hermes:
|
|
tags: [airtable, linear, notion, project-management, task-tracking, saas, rest-api]
|
|
related_skills: [google-workspace, teams-meeting-pipeline]
|
|
---
|
|
|
|
# Project Tracking
|
|
|
|
Three SaaS platforms for tracking projects, tasks, and data. Each has a REST API for programmatic access.
|
|
|
|
## Choosing a Platform
|
|
|
|
| Need | Platform | Strength |
|
|
|------|----------|----------|
|
|
| Spreadsheet-like data management | **Airtable** | Relational databases, views, forms |
|
|
| Software issue tracking | **Linear** | Fast, keyboard-driven, GraphQL API |
|
|
| Knowledge base + databases | **Notion** | Pages, wikis, databases, rich content |
|
|
| Forms and data collection | **Airtable** | Built-in forms with submissions |
|
|
| Engineering workflows | **Linear** | Sprints, cycles, project boards |
|
|
|
|
## Section 1: Airtable — Spreadsheets + Databases
|
|
|
|
REST API for Airtable bases, tables, records. CRUD operations, filtering, sorting, upserts.
|
|
|
|
**When to use:** Managing structured data, forms, project trackers, inventory, CRM-style workflows.
|
|
|
|
**Authentication:** Personal access token or OAuth. Pass as `Authorization: Bearer <token>` header.
|
|
|
|
**Quick start:**
|
|
```bash
|
|
# List records
|
|
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE_NAME" \
|
|
-H "Authorization: Bearer $AIRTABLE_TOKEN" | jq
|
|
|
|
# Create record
|
|
curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE_NAME" \
|
|
-H "Authorization: Bearer $AIRTABLE_TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"fields": {"Name": "New Task", "Status": "Todo"}}'
|
|
```
|
|
|
|
**Key features:** upsert (create-or-update via `performUpsert`), formula filtering, webhooks, synced tables.
|
|
|
|
**See:** `references/airtable.md` for full API reference with filtering, upserts, and batch operations.
|
|
|
|
## Section 2: Linear — Issues + Projects
|
|
|
|
GraphQL API for Linear issues, projects, teams, and workflows.
|
|
|
|
**When to use:** Software project management, issue tracking, sprint planning, engineering workflows.
|
|
|
|
**Authentication:** API key passed as `Authorization: <api_key>` header.
|
|
|
|
**Quick start:**
|
|
```bash
|
|
# List issues
|
|
curl -s -X POST "https://api.linear.app/graphql" \
|
|
-H "Authorization: $LINEAR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"query": "{ issues { nodes { id title state { name } assignee { name } } } }"}' | jq
|
|
|
|
# Create issue
|
|
curl -s -X POST "https://api.linear.app/graphql" \
|
|
-H "Authorization: $LINEAR_API_KEY" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"query": "mutation { issueCreate(input: {title: \"Bug fix\", teamId: \"$TEAM_ID\"}) { success issue { id } } }"}'
|
|
```
|
|
|
|
**Key features:** GraphQL API, teams/cycles/projects, labels/states, comments, webhooks, Zapier integration.
|
|
|
|
**See:** `references/linear.md` for full GraphQL schema and workflow patterns.
|
|
|
|
## Section 3: Notion — Pages + Databases
|
|
|
|
Notion API + `ntn` CLI for pages, databases, markdown, and Workers.
|
|
|
|
**When to use:** Knowledge bases, wikis, documentation, meeting notes, databases with rich content.
|
|
|
|
**Authentication:** Integration token via `NOTION_TOKEN` env var or `ntn` CLI config.
|
|
|
|
**Quick start:**
|
|
```bash
|
|
# Using ntn CLI
|
|
ntn search "meeting notes"
|
|
ntn page create --parent <page_id> --title "New Page" --body "Content here"
|
|
|
|
# Using API directly
|
|
curl -s "https://api.notion.com/v1/databases/$DB_ID/query" \
|
|
-H "Authorization: Bearer $NOTION_TOKEN" \
|
|
-H "Notion-Version: 2022-06-28" \
|
|
-d '{}' | jq
|
|
```
|
|
|
|
**Key features:** Rich text blocks, database queries with filters/sorts, page hierarchies, `ntn` CLI for quick operations, Workers for automation.
|
|
|
|
**See:** `references/notion.md` for full API reference, `ntn` CLI guide, and Workers setup.
|