{"id":15373849,"url":"https://github.com/boly38/umami-api-client","last_synced_at":"2026-04-27T00:31:44.893Z","repository":{"id":41524902,"uuid":"510032486","full_name":"boly38/umami-api-client","owner":"boly38","description":"Umami API nodeJS client","archived":false,"fork":false,"pushed_at":"2026-01-19T20:09:14.000Z","size":177,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-19T22:43:41.560Z","etag":null,"topics":["api","api-rest","client","hacktoberfest","nodejs","umami"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/boly38.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-07-03T13:34:36.000Z","updated_at":"2026-01-19T20:09:17.000Z","dependencies_parsed_at":"2024-12-06T21:24:07.251Z","dependency_job_id":"0d6d7ba5-7271-402b-8bfc-b58eb7c47feb","html_url":"https://github.com/boly38/umami-api-client","commit_stats":{"total_commits":20,"total_committers":3,"mean_commits":6.666666666666667,"dds":0.25,"last_synced_commit":"ca7f2123b532d69ff860acf4bd96b1f258bd7e4c"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/boly38/umami-api-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boly38%2Fumami-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boly38%2Fumami-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boly38%2Fumami-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boly38%2Fumami-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boly38","download_url":"https://codeload.github.com/boly38/umami-api-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boly38%2Fumami-api-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32318417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"ssl_error","status_checked_at":"2026-04-26T23:26:25.802Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-rest","client","hacktoberfest","nodejs","umami"],"created_at":"2024-10-01T13:56:32.186Z","updated_at":"2026-04-27T00:31:44.874Z","avatar_url":"https://github.com/boly38.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# umami-api-client\n\n[![NPM](https://nodei.co/npm/umami-api-client.png?compact=true)](https://npmjs.org/package/umami-api-client)\n\nUmami [ReST API](https://umami.is/docs/api) client for Node.js.\n\n## ⚠️ Version Notice\n\n**Current version: v3.0.3** - Targets **Umami v3.x API**\n\n| umami-api-client | Umami Server   | Status        |\n|------------------|----------------|---------------|\n| **v3.0.3**       | **Umami v3.x** | ✅ **Current** |\n| v2.17.3          | Umami v2.x     | ❌ EOL         |\n\n📚 **[Migration Guide v2 → v3](./MIGRATION_V3.md)** - Breaking changes \u0026 upgrade instructions\n\n---\n\n## Features\n\n- ✅ **Dual mode**: Umami Cloud (API key) \u0026 Hosted (login/password)\n- ✅ **Read-only API**: Retrieve websites, stats, pageviews, events, metrics, sessions, links, pixels\n- ✅ **Periods**: `1h`, `24h`, `7d`, `1w`, `30d`, `1m`\n- ✅ **v3 compatible**: Works with Umami v3.0.x API\n- ✅ **Links API**: Track short URLs and redirects (read-only) - **v3.0.3+**\n- ✅ **Pixels API**: Track email opens and external sites (read-only) - **v3.0.3+**\n- ❌ **Segments \u0026 Cohorts**: Not implemented (use Umami UI)\n\n### Current Limitations\n- ❌ No website creation/modification/deletion\n- ❌ No user/team management\n- ❌ No event tracking (send events to Umami)\n- ❌ No write operations on Links/Pixels (read-only)\n- ❌ **Segments \u0026 Cohorts APIs**: Not implemented (use Umami UI for now)\n\n## Installation\n\n```bash\nnpm install umami-api-client@^3.0.3\n# or\npnpm add umami-api-client@^3.0.3\n```\n\n**Upgrading from v2.x?** Read the **[Migration Guide](./MIGRATION_V3.md)**\n\n---\n\n## Quick Start\n\n### Umami Cloud (API Key)\nUmami Cloud: https://cloud.umami.is/ ([Get your API key](https://cloud.umami.is/api-keys))\n````javascript\nimport UmamiClient from 'umami-api-client';\n\nconst doIt = async () =\u003e {\n    try {\n        const client = new UmamiClient();\n        // default is // new UmamiClient({cloudApiKey:process.env.UMAMI_CLOUD_API_KEY});\n        const identity = await client.me();\n        console.log(`🔑 Api key details:\\n${JSON.stringify(identity?.user,null,2)}`);\n\n        const sitesData = await client.websites();\n        const filteredSitesData = sitesData.map(({ id, name, createdAt, domain }) =\u003e ({ id, name, createdAt, domain }));\n        console.log(\"🗂️ List of Tracked Websites:\");\n        console.table(filteredSitesData);\n\n        const websiteStats = await client.websiteStats(sitesData[0].id);\n        console.log(`📊 Website Stats for: ${sitesData[0].name}`);\n        console.table(websiteStats);\n    } catch(error) {\n        console.error(error);\n    }\n};\n\ndoIt().then(r =\u003e {});\n````\n\n### Umami Hosted (Self-hosted)\n\nSelf-hosted Umami instance with login/password authentication.\n````javascript\nimport UmamiClient from 'umami-api-client';\n\nconst doIt = async () =\u003e {\n    try {\n        const client = new UmamiClient();\n        // default is // new UmamiClient({server:process.env.UMAMI_SERVER});\n        await client.login();\n        // default is // client.login(process.env.UMAMI_USER, process.env.UMAMI_PASSWORD)\n        const sitesData = await client.websites();\n        const filteredSitesData = sitesData.map(({ id, name, createdAt, domain }) =\u003e ({ id, name, createdAt, domain }));\n        console.log(\"🗂️ List of Tracked Websites:\");\n        console.table(filteredSitesData);\n\n        const websiteStats = await client.websiteStats(sitesData[0].id);\n        console.log(`📊 Website Stats for: ${sitesData[0].name}`);\n        console.table(websiteStats);\n    } catch(error) {\n        console.error(error);\n    }\n};\n\ndoIt().then(r =\u003e {});\n````\n\n### Explicit Configuration (no env vars)\n\n```javascript\n// Cloud mode\nconst client = new UmamiClient({ cloudApiKey: 'your-api-key' });\n\n// Hosted mode\nconst client = new UmamiClient({ server: 'https://umami.example.com' });\nawait client.login('admin', 'password');\n```\n\n---\n\n## API Methods\n\n### Authentication\n- `me()` - Get user info (Cloud mode)\n- `login(username, password)` - Login (Hosted mode)\n- `logout()` - Logout (Hosted mode)\n\n### Websites\n- `websites()` - List all websites\n- `selectSiteByDomain(sites, domain)` - Select site by domain\n\n### Statistics\n- `websiteStats(websiteId, period, options)` - Get website stats\n- `websitePageViews(websiteId, period, options)` - Get pageviews timeline\n- `websiteMetrics(websiteId, period, options)` - Get metrics (urls, referrers, browsers, etc.)\n- `websiteEvents(websiteId, period, options)` - Get events (paginated)\n- `websiteSessions(websiteId, period, options)` - Get sessions (paginated)\n\n### Links (Umami v3.x) ✅\n- `links(options)` - List all links (short URLs)\n- `getLink(linkId)` - Get link details\n- `linkStats(linkId, period, options)` - Get link statistics (alias for `websiteStats`)\n\n### Pixels (Umami v3.x) ✅\n- `pixels(options)` - List all pixels (tracking pixels)\n- `getPixel(pixelId)` - Get pixel details\n- `pixelStats(pixelId, period, options)` - Get pixel statistics (alias for `websiteStats`)\n\n### Segments \u0026 Cohorts (Umami v3.x) ❌\n\u003e **⚠️ Not Implemented**: Segments and Cohorts APIs are not available in this client.  \n\u003e Use the Umami web UI to manage segments and cohorts.\n\n\u003e **📝 Note**: In Umami v3, links and pixels use the websites stats endpoint. `linkStats()` and `pixelStats()` are aliases for `websiteStats()` where the ID serves as `websiteId`.\n\n### Periods\nAccepted values: `1h`, `24h`, `7d`, `1w`, `30d`, `1m`\n\n### Usage Examples\n\n#### Links API\n```javascript\nimport UmamiClient from 'umami-api-client';\n\nconst client = new UmamiClient();\nawait client.login(); // or use cloud API key\n\n// Get all links\nconst linksData = await client.links({ page: 1, pageSize: 10 });\nconsole.log(`Total links: ${linksData.data.length}`);\n\n// Get specific link\nconst linkId = linksData.data[0].id;\nconst linkDetails = await client.getLink(linkId);\nconsole.log(`Link URL: ${linkDetails.url}`);\n\n// Get link statistics (uses /api/websites/:linkId/stats)\nconst stats = await client.linkStats(linkId, '7d', { unit: 'day' });\nconsole.log('Link stats:', stats);\n\n// Alternative: use websiteStats() directly (same result)\nconst sameStats = await client.websiteStats(linkId, '7d', { unit: 'day' });\n```\n\n#### Pixels API\n```javascript\nimport UmamiClient from 'umami-api-client';\n\nconst client = new UmamiClient();\nawait client.login(); // or use cloud API key\n\n// Get all pixels\nconst pixelsData = await client.pixels({ page: 1, pageSize: 10 });\nconsole.log(`Total pixels: ${pixelsData.data.length}`);\n\n// Get specific pixel\nconst pixelId = pixelsData.data[0].id;\nconst pixelDetails = await client.getPixel(pixelId);\nconsole.log(`Pixel: ${pixelDetails.name} (${pixelDetails.slug})`);\n\n// Get pixel statistics (uses /api/websites/:pixelId/stats)\nconst stats = await client.pixelStats(pixelId, '7d', { unit: 'day' });\nconsole.log('Pixel stats:', stats);\n```\n\nSee [tests/manual/](./tests/manual/) for more examples.\n\n---\n\n\n## Documentation\n\n- 📚 **[Migration Guide v2 → v3](./MIGRATION_V3.md)** - Breaking changes \u0026 upgrade path\n- 👨‍💻 **[Contributing Guide](./CONTRIBUTING.md)** - Setup, tests, release process\n- 🧪 **[Tests Documentation](./tests/TestsReadme.md)** - Running tests\n- 📝 **[Umami API Docs](https://umami.is/docs/api)** - Official API reference\n\n---\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md)\n\n### Services or activated bots\n\n\n| ![CI/CD](https://github.com/boly38/umami-api-client/workflows/umami_api_client_ci/badge.svg) | [![Automated Release Notes by gren](https://img.shields.io/badge/%F0%9F%A4%96-release%20notes-00B2EE.svg)](https://github-tools.github.io/github-release-notes/) | [\u003cimg src=\"https://cdn.icon-icons.com/icons2/2148/PNG/512/houndci_icon_132320.png\" width=\"40\"\u003e](https://houndci.com/) | [\u003cimg src=\"https://codetheweb.blog/assets/img/posts/github-pages-free-hosting/cover.png\" width=\"100\"\u003e](https://boly38.github.io/umami-api-client/) |\n| ---- | ---- | ---- | ---- |\n\n- Github actions : continuous tests + coverage using [c8](https://www.npmjs.com/package/c8) reported on github pages [website](https://boly38.github.io/umami-api-client/)\n- Github security checks activated\n- [Houndci](https://houndci.com/) : JavaScript  automated review (configured by `.hound.yml`)\n- [gren](https://github.com/github-tools/github-release-notes) : [Release notes](https://github.com/boly38/umami-api-client/releases) automation\n- Github pages [website](https://boly38.github.io/umami-api-client/) hosts some metrics for the main branch of this project: [code coverage](https://boly38.github.io/umami-api-client/)\n\n---\n\n## License\n\nMIT - See [LICENSE](./LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboly38%2Fumami-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboly38%2Fumami-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboly38%2Fumami-api-client/lists"}