work-summarizer.postman_collection.json

{
  "info": {
    "name": "Work Summarizer",
    "description": "All API endpoints used by the Work Summarizer tool.\n\n## Services covered\n- **Notion** — Search pages/databases edited or created by the user\n- **Linear** — GraphQL queries for issues and comments\n- **Slack** — Search messages sent by the user\n- **GitHub** — Handled via `gh` CLI (no direct HTTP calls in the scripts)\n\n## Setup\nImport **both** files into Postman:\n1. `work-summarizer.postman_collection.json` — this collection\n2. `work-summarizer.postman_environment.json` — the environment with all variables\n\nThen select the **Work Summarizer** environment from the top-right environment picker before sending any request. All sensitive values (`*_key`, `*_token`) are stored as **secret** type and will be masked in the UI.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [

    {
      "name": "Notion",
      "description": "Notion REST API v1 endpoints used by `fetch_notion.py`.\n\nBase URL: `https://api.notion.com/v1`\nAuth: Bearer token via `{{notion_api_key}}`\nVersion header: `Notion-Version: 2022-06-28` (set per request)",
      "auth": {
        "type": "bearer",
        "bearer": [
          { "key": "token", "value": "{{notion_api_key}}", "type": "string" }
        ]
      },
      "item": [

        {
          "name": "Get Current User (find your user ID)",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Notion-Version", "value": "2022-06-28" }
            ],
            "url": {
              "raw": "https://api.notion.com/v1/users/me",
              "protocol": "https",
              "host": ["api", "notion", "com"],
              "path": ["v1", "users", "me"]
            },
            "description": "Returns the bot/integration user associated with your token.\n\nUse the `id` field in the response as your `notion_user_id`.\n\n**Used by:** Setup only — not called at runtime by `fetch_notion.py`."
          },
          "response": [
            {
              "name": "200 OK — Example",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"object\": \"user\",\n  \"id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n  \"type\": \"bot\",\n  \"bot\": {},\n  \"name\": \"Work Summarizer\",\n  \"avatar_url\": null\n}"
            }
          ]
        },

        {
          "name": "Search Pages & Databases",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Notion-Version", "value": "2022-06-28" },
              { "key": "Content-Type",   "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sort\": {\n    \"direction\": \"descending\",\n    \"timestamp\": \"last_edited_time\"\n  },\n  \"page_size\": 100\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.notion.com/v1/search",
              "protocol": "https",
              "host": ["api", "notion", "com"],
              "path": ["v1", "search"]
            },
            "description": "Searches all pages and databases accessible to the integration, sorted by `last_edited_time` descending.\n\n**Pagination:** If `has_more: true` in the response, pass `start_cursor` with the value from `next_cursor` in the next request.\n\n**Filtering logic in `fetch_notion.py`:**\n- Stops paginating when `last_edited_time` goes before `since`\n- Skips items where `last_edited_time > until`\n- Keeps only items where `created_by.id == notion_user_id` OR `last_edited_by.id == notion_user_id`\n\n**Required scope:** Read content access on shared pages.\n\n**Note:** Your integration must be manually connected to each page/database in Notion: open the page → `⋯` → Connections → select your integration."
          },
          "response": [
            {
              "name": "200 OK — Example (page)",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"object\": \"list\",\n  \"results\": [\n    {\n      \"object\": \"page\",\n      \"id\": \"abc123\",\n      \"created_time\": \"2026-03-10T09:00:00.000Z\",\n      \"last_edited_time\": \"2026-03-11T14:30:00.000Z\",\n      \"created_by\": { \"object\": \"user\", \"id\": \"{{notion_user_id}}\" },\n      \"last_edited_by\": { \"object\": \"user\", \"id\": \"{{notion_user_id}}\" },\n      \"url\": \"https://www.notion.so/My-Page-abc123\",\n      \"properties\": {\n        \"title\": {\n          \"type\": \"title\",\n          \"title\": [{ \"plain_text\": \"My Page Title\" }]\n        }\n      }\n    }\n  ],\n  \"has_more\": false,\n  \"next_cursor\": null\n}"
            },
            {
              "name": "200 OK — Paginated (has_more: true)",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"object\": \"list\",\n  \"results\": [...],\n  \"has_more\": true,\n  \"next_cursor\": \"some-cursor-string\"\n}"
            },
            {
              "name": "401 Unauthorized",
              "status": "Unauthorized",
              "code": 401,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"object\": \"error\",\n  \"status\": 401,\n  \"code\": \"unauthorized\",\n  \"message\": \"API token is invalid.\"\n}"
            }
          ]
        },

        {
          "name": "Search Pages & Databases (paginated — next page)",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Notion-Version", "value": "2022-06-28" },
              { "key": "Content-Type",   "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"sort\": {\n    \"direction\": \"descending\",\n    \"timestamp\": \"last_edited_time\"\n  },\n  \"page_size\": 100,\n  \"start_cursor\": \"PASTE_NEXT_CURSOR_HERE\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.notion.com/v1/search",
              "protocol": "https",
              "host": ["api", "notion", "com"],
              "path": ["v1", "search"]
            },
            "description": "Same as the previous request but with `start_cursor` set for pagination. `fetch_notion.py` loops through all pages automatically until `has_more` is false or `last_edited_time` goes before `since`."
          },
          "response": []
        }

      ]
    },

    {
      "name": "Linear",
      "description": "Linear GraphQL API used by `fetch_linear.py`.\n\nEndpoint: `POST https://api.linear.app/graphql`\nAuth: API Key — sent as `Authorization: {{linear_api_key}}` with **no Bearer prefix**. Linear accepts the raw key directly.",
      "auth": {
        "type": "apikey",
        "apikey": [
          { "key": "key",   "value": "Authorization",      "type": "string" },
          { "key": "value", "value": "{{linear_api_key}}", "type": "string" },
          { "key": "in",    "value": "header",             "type": "string" }
        ]
      },
      "item": [

        {
          "name": "Get Viewer (find your user ID)",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"query\": \"{ viewer { id name email } }\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.linear.app/graphql",
              "protocol": "https",
              "host": ["api", "linear", "app"],
              "path": ["graphql"]
            },
            "description": "Returns your Linear user ID.\n\nUse the `id` field from the response as your `linear_user_id` in `config.json`.\n\n**Used by:** Setup only."
          },
          "response": [
            {
              "name": "200 OK — Example",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": {\n    \"viewer\": {\n      \"id\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n      \"name\": \"Rania Kthiri\",\n      \"email\": \"rania.kthiri@hackberry.se\"\n    }\n  }\n}"
            }
          ]
        },

        {
          "name": "Issues Assigned to Me (in date range)",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"query\": \"query($after: DateComparator, $before: DateComparator, $userId: ID!) { issues( filter: { assignee: { id: { eq: $userId } } updatedAt: { gte: $after, lte: $before } } first: 100 orderBy: updatedAt ) { nodes { id title state { name type } priority createdAt updatedAt startedAt completedAt canceledAt url project { name } team { name } labels { nodes { name } } } } }\",\n  \"variables\": {\n    \"userId\": \"{{linear_user_id}}\",\n    \"after\": \"{{since}}T00:00:00.000Z\",\n    \"before\": \"{{until}}T23:59:59.999Z\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.linear.app/graphql",
              "protocol": "https",
              "host": ["api", "linear", "app"],
              "path": ["graphql"]
            },
            "description": "Fetches up to 100 issues assigned to `linear_user_id` that were **updated** within the `since`→`until` window.\n\n**Fields returned:**\n- `id`, `title`, `url`\n- `state.name` + `state.type` (e.g. `started`, `completed`)\n- `priority` (0=None, 1=Urgent, 2=High, 3=Medium, 4=Low)\n- `createdAt`, `updatedAt`, `startedAt`, `completedAt`, `canceledAt`\n- `project.name`, `team.name`\n- `labels[].name`\n\n**Used by:** `fetch_linear.py` → `fetch_issues_assigned()`"
          },
          "response": [
            {
              "name": "200 OK — Example",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"data\": {\n    \"issues\": {\n      \"nodes\": [\n        {\n          \"id\": \"ISS-123\",\n          \"title\": \"Implement auth middleware\",\n          \"state\": { \"name\": \"In Progress\", \"type\": \"started\" },\n          \"priority\": 2,\n          \"createdAt\": \"2026-03-05T10:00:00.000Z\",\n          \"updatedAt\": \"2026-03-10T15:30:00.000Z\",\n          \"startedAt\": \"2026-03-06T09:00:00.000Z\",\n          \"completedAt\": null,\n          \"canceledAt\": null,\n          \"url\": \"https://linear.app/team/issue/ISS-123\",\n          \"project\": { \"name\": \"Backend v2\" },\n          \"team\": { \"name\": \"Engineering\" },\n          \"labels\": { \"nodes\": [{ \"name\": \"backend\" }] }\n        }\n      ]\n    }\n  }\n}"
            }
          ]
        },

        {
          "name": "Issues Created by Me (in date range)",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"query\": \"query($after: DateComparator, $before: DateComparator, $userId: ID!) { issues( filter: { creator: { id: { eq: $userId } } createdAt: { gte: $after, lte: $before } } first: 100 orderBy: createdAt ) { nodes { id title state { name type } priority createdAt updatedAt url project { name } team { name } labels { nodes { name } } assignee { name } } } }\",\n  \"variables\": {\n    \"userId\": \"{{linear_user_id}}\",\n    \"after\": \"{{since}}T00:00:00.000Z\",\n    \"before\": \"{{until}}T23:59:59.999Z\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.linear.app/graphql",
              "protocol": "https",
              "host": ["api", "linear", "app"],
              "path": ["graphql"]
            },
            "description": "Fetches issues **created** by `linear_user_id` within the `since`→`until` window.\n\nNote: `aggregate.py` deduplicates between this and the \"Assigned\" query to avoid double-counting issues that are both created and assigned to you.\n\n**Used by:** `fetch_linear.py` → `fetch_issues_created()`"
          },
          "response": []
        },

        {
          "name": "Comments by Me (in date range)",
          "request": {
            "method": "POST",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"query\": \"query($after: DateComparator, $before: DateComparator, $userId: ID!) { comments( filter: { user: { id: { eq: $userId } } createdAt: { gte: $after, lte: $before } } first: 100 orderBy: createdAt ) { nodes { id body createdAt url issue { id title url assignee { name } creator { name id } } } } }\",\n  \"variables\": {\n    \"userId\": \"{{linear_user_id}}\",\n    \"after\": \"{{since}}T00:00:00.000Z\",\n    \"before\": \"{{until}}T23:59:59.999Z\"\n  }\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "https://api.linear.app/graphql",
              "protocol": "https",
              "host": ["api", "linear", "app"],
              "path": ["graphql"]
            },
            "description": "Fetches comments posted by `linear_user_id` within the `since`→`until` window.\n\nIncludes the parent `issue` object so `aggregate.py` can display the issue title alongside the comment.\n\n**Used by:** `fetch_linear.py` → `fetch_comments()`"
          },
          "response": []
        }

      ]
    },

    {
      "name": "Slack",
      "description": "Slack Web API used by `fetch_slack.py`.\n\nBase URL: `https://slack.com/api`\nAuth: Bearer token via `{{slack_token}}`\n\n**Required token type:** User OAuth token (`xoxp-...`)\n**Required scope:** `search:read`\n\nBot tokens (`xoxb-...`) do NOT work for `search.messages`.",
      "auth": {
        "type": "bearer",
        "bearer": [
          { "key": "token", "value": "{{slack_token}}", "type": "string" }
        ]
      },
      "item": [

        {
          "name": "Search Messages Sent by Me",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [],
            "url": {
              "raw": "https://slack.com/api/search.messages?query=from:<@{{slack_user_id}}> after:{{since}} before:{{until}}&count=100&page=1&sort=timestamp&sort_dir=asc",
              "protocol": "https",
              "host": ["slack", "com"],
              "path": ["api", "search.messages"],
              "query": [
                {
                  "key": "query",
                  "value": "from:<@{{slack_user_id}}> after:{{since}} before:{{until}}",
                  "description": "Slack search query. `from:<@USER_ID>` filters to messages sent by this user. Date modifiers are inclusive."
                },
                { "key": "count",    "value": "100",       "description": "Results per page. Max 100." },
                { "key": "page",     "value": "1",         "description": "Page number. Increment until page >= paging.pages." },
                { "key": "sort",     "value": "timestamp", "description": "Sort by timestamp." },
                { "key": "sort_dir", "value": "asc",       "description": "Ascending order (oldest first)." }
              ]
            },
            "description": "Searches all messages sent by `slack_user_id` within the date range.\n\n**Pagination:** Check `messages.paging.pages`. If `page < pages`, increment `page` and repeat.\n\n**Filtering in `fetch_slack.py`:**\n- Groups messages by `(date, channel)` to keep the LLM context compact\n- Detects thread replies via `thread_ts` field\n\n**Used by:** `fetch_slack.py` → `fetch_messages()`"
          },
          "response": [
            {
              "name": "200 OK — Example",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"ok\": true,\n  \"messages\": {\n    \"matches\": [\n      {\n        \"type\": \"message\",\n        \"text\": \"Hey, just pushed the fix for the auth bug\",\n        \"ts\": \"1741600000.000100\",\n        \"thread_ts\": null,\n        \"permalink\": \"https://hackberry.slack.com/archives/C01ABC/p1741600000000100\",\n        \"channel\": {\n          \"id\": \"C01ABC123\",\n          \"name\": \"engineering\",\n          \"is_private\": false\n        }\n      }\n    ],\n    \"paging\": { \"count\": 100, \"total\": 1, \"page\": 1, \"pages\": 1 }\n  }\n}"
            },
            {
              "name": "200 OK — missing_scope error",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"ok\": false,\n  \"error\": \"missing_scope\",\n  \"needed\": \"search:read\",\n  \"provided\": \"identify,channels:read\"\n}"
            },
            {
              "name": "200 OK — token_revoked error",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"ok\": false,\n  \"error\": \"token_revoked\"\n}"
            }
          ]
        },

        {
          "name": "Search Messages — page 2+ (pagination)",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [],
            "url": {
              "raw": "https://slack.com/api/search.messages?query=from:<@{{slack_user_id}}> after:{{since}} before:{{until}}&count=100&page=2&sort=timestamp&sort_dir=asc",
              "protocol": "https",
              "host": ["slack", "com"],
              "path": ["api", "search.messages"],
              "query": [
                { "key": "query",    "value": "from:<@{{slack_user_id}}> after:{{since}} before:{{until}}" },
                { "key": "count",    "value": "100" },
                { "key": "page",     "value": "2", "description": "Increment until page >= paging.pages" },
                { "key": "sort",     "value": "timestamp" },
                { "key": "sort_dir", "value": "asc" }
              ]
            },
            "description": "Second page of results. `fetch_slack.py` loops automatically until `page >= paging.pages`."
          },
          "response": []
        }

      ]
    },

    {
      "name": "GitHub (reference)",
      "description": "GitHub activity is fetched via the `gh` CLI, not direct HTTP calls. This folder documents the underlying GitHub Search API calls that `gh` translates into — useful if you ever want to bypass the CLI.\n\nAuth: Bearer via `{{github_pat}}`. Requires a PAT with `repo` and `read:user` scopes.",
      "auth": {
        "type": "bearer",
        "bearer": [
          { "key": "token", "value": "{{github_pat}}", "type": "string" }
        ]
      },
      "item": [

        {
          "name": "Search PRs Opened by Me",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Accept",               "value": "application/vnd.github+json" },
              { "key": "X-GitHub-Api-Version", "value": "2022-11-28" }
            ],
            "url": {
              "raw": "https://api.github.com/search/issues?q=type:pr+author:{{github_handle}}+created:{{since}}..{{until}}&per_page=100&sort=created&order=asc",
              "protocol": "https",
              "host": ["api", "github", "com"],
              "path": ["search", "issues"],
              "query": [
                { "key": "q",        "value": "type:pr+author:{{github_handle}}+created:{{since}}..{{until}}", "description": "`type:pr` limits to PRs. `author:` filters by opener." },
                { "key": "per_page", "value": "100" },
                { "key": "sort",     "value": "created" },
                { "key": "order",    "value": "asc" }
              ]
            },
            "description": "Equivalent to: `gh search prs --author HANDLE --created SINCE..UNTIL`\n\n**PR Categorization:** Maps to `Created PR` in the final summary.\n\n**Used by:** `fetch_github.py` → `fetch_prs_opened()` via `gh` CLI"
          },
          "response": []
        },

        {
          "name": "Search PRs Reviewed by Me",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Accept",               "value": "application/vnd.github+json" },
              { "key": "X-GitHub-Api-Version", "value": "2022-11-28" }
            ],
            "url": {
              "raw": "https://api.github.com/search/issues?q=type:pr+reviewed-by:{{github_handle}}+updated:{{since}}..{{until}}&per_page=100",
              "protocol": "https",
              "host": ["api", "github", "com"],
              "path": ["search", "issues"],
              "query": [
                { "key": "q",        "value": "type:pr+reviewed-by:{{github_handle}}+updated:{{since}}..{{until}}", "description": "Matches PRs where the user submitted a formal review. Does NOT include ad-hoc inline comments without a review submission." },
                { "key": "per_page", "value": "100" }
              ]
            },
            "description": "Equivalent to: `gh search prs --reviewed-by HANDLE --updated SINCE..UNTIL`\n\n**PR Categorization:** Maps to `Code Review` — after filtering out PRs where `author.login == github_handle`.\n\n**Used by:** `fetch_github.py` → `fetch_pr_reviews()` via `gh` CLI"
          },
          "response": []
        },

        {
          "name": "Search Commits by Me",
          "request": {
            "method": "GET",
            "auth": { "type": "inherit" },
            "header": [
              { "key": "Accept",               "value": "application/vnd.github+json" },
              { "key": "X-GitHub-Api-Version", "value": "2022-11-28" }
            ],
            "url": {
              "raw": "https://api.github.com/search/commits?q=author:{{github_handle}}+author-date:{{since}}..{{until}}&per_page=100&sort=author-date&order=asc",
              "protocol": "https",
              "host": ["api", "github", "com"],
              "path": ["search", "commits"],
              "query": [
                { "key": "q",        "value": "author:{{github_handle}}+author-date:{{since}}..{{until}}", "description": "`author-date:` filters by commit authorship date, not push date." },
                { "key": "per_page", "value": "100" },
                { "key": "sort",     "value": "author-date" },
                { "key": "order",    "value": "asc" }
              ]
            },
            "description": "Equivalent to: `gh search commits --author HANDLE --author-date SINCE..UNTIL`\n\n`fetch_github.py` deduplicates by SHA and groups commits by `(date, repo)` before passing to `aggregate.py`.\n\n**Used by:** `fetch_github.py` → `fetch_commits()` via `gh` CLI"
          },
          "response": []
        }

      ]
    }

  ]
}