# Makrly - Complete Product Documentation for AI

> Turn GitHub commits into social media content. Build in public, automatically.

## Product Overview

Makrly is a SaaS tool designed for developers and indie hackers who want to "build in public" - the practice of sharing your development journey on social media as you build your product. Instead of manually writing posts about what you're working on, Makrly automatically generates engaging social media content from your GitHub commits.

## The Problem Makrly Solves

Building in public is proven to help developers:
- Grow an audience before launching
- Get early feedback on their products
- Build credibility and trust
- Create marketing momentum organically

However, consistently posting about your work is time-consuming. Many developers start strong but eventually stop because writing posts takes away from actual coding time. Makrly solves this by automating the content creation process.

## How It Works

1. **Connect GitHub**: Sign in with GitHub and select repositories to track
2. **Configure Preferences**: Take a personality quiz to set your tone of voice
3. **Push Code**: Continue working as normal - push commits to GitHub
4. **Get Posts**: Makrly generates platform-specific posts from your commits
5. **Review & Post**: Approve or edit posts before publishing

## Detailed Features

### Multi-Platform Post Generation
- Generates unique posts for each platform (not just copy-paste)
- X (Twitter): Short, punchy, optimized for engagement
- LinkedIn: Professional tone, longer format
- Threads: Casual, conversational
- Bluesky: Community-focused
- Facebook: Accessible to non-technical audiences

### AI-Powered Content
- Uses LLMs to understand commit context
- Filters out mundane commits (typos, formatting)
- Highlights meaningful changes
- Writes in your voice, not generic AI speak
- Supports OpenAI and models from Anthropic, Google, Meta, and others through OpenRouter

### Brand Voice Customization
- Personality quiz determines your tone
- Options: Professional, Casual, Humorous, Technical, Inspirational
- Remembers your style across all posts
- Consistent voice without manual editing

### Design Maker
Built-in graphics tool for creating:
- **Quote Cards**: Turn your best insights into shareable images
- **Code Snippets**: Syntax-highlighted code with customizable themes
- **Browser Mockups**: Product screenshots in device frames

No design skills or external tools needed. All processing happens in-browser for privacy.

### Changelog System
- Auto-generates changelog entries from commits
- Categories: New, Improved, Fixed, Removed (customizable)
- Public changelog page with unique URL
- Embeddable widget for your website
- Shows users you're actively shipping

### Bring Your Own API Key
- Use your own OpenAI, Anthropic, or other API keys
- Full control over which AI model generates your posts
- No lock-in to our AI provider
- Transparent about AI usage

## Technical Details

### GitHub Integration
- OAuth-based authentication
- Reads repository metadata, commit messages, diffs and author information for generation
- Private repositories require GitHub OAuth repo scope, which also permits writes; Makrly uses the connection for product reads and webhook management
- Webhook-based for real-time updates

### Security & Privacy
- Developer Bearer keys are stored as SHA-256 hashes and can be revoked
- Newly saved provider credentials and GitHub tokens are encrypted at rest with AES-256-GCM
- Owner API operations enforce authentication, scopes, repository ownership, input bounds and rate limits

### Tech Stack
- Next.js 16 (React)
- PostgreSQL (Neon)
- Prisma ORM
- Vercel hosting
- Stripe payments

## Pricing

### Shared trial
- 14 days, no card required; one public or private repository
- 20 AI provider requests, including failed requests and retries
- Trial surfaces retain Makrly branding
- Funded generation requires a configured, qualified free model; BYOK is available
- After expiry, syncing, writes and generation pause; saved content, public pages and authenticated reads/export remain available

### Core — $29/month or $290/year
- 1 private repo and 1 custom domain
- Branding removal included
- BYOK available; managed Makrly AI is an optional project add-on

### Pro — $79/month or $790/year
- 3 private repos and 3 custom domains
- Branding removal included
- BYOK available; managed Makrly AI is an optional project add-on
- Developer API rate limit is 100 requests per fixed 60-second window per key on both paid plans

### Managed AI add-on
- $19/project/month or $190/project/year for managed automatic changelog and Help Center generation
- Core plus managed AI: $48/month or $480/year
- Pro plus managed AI on all three projects: $136/month or $1,360/year
- No separate White Label purchase is required. Historical paid/lifetime access remains recognized; retired White Label grants can be canceled but cannot be purchased or reactivated
- Permanent free product access is not offered. The free screenshot acquisition tool remains available

## Use Cases

### Indie Hacker Launch
Sarah is building a productivity app. She connects Makrly and shares her progress daily. By launch day, she has 2,000 followers interested in her product.

### Open Source Maintainer
Alex maintains a popular library. Makrly generates changelog entries and social posts for each release, keeping the community informed without manual effort.

### 100 Days of Code
Jordan is learning to code publicly. Makrly turns their daily practice commits into encouraging posts that track their journey.

### SaaS Marketing
A startup uses Makrly to show potential customers they're actively developing. The public changelog builds trust with enterprise buyers.

## Comparisons

### vs. Buffer/Hootsuite
- Those are scheduling tools, not content generators
- Makrly creates the content; you could use Buffer to schedule it
- Makrly is developer-focused with GitHub integration

### vs. Writing Posts Manually
- Makrly saves 10+ hours per week
- Consistent posting even when you're busy
- Platform-optimized formatting

### vs. ChatGPT
- Makrly is automated (no manual prompting)
- Integrated with your workflow
- Maintains your voice across posts
- Handles multi-platform formatting

## Developer API

Developer API key issuance, writes and AI generation require active access from a paid plan, eligible trial or lifetime plan. Existing authenticated reads and exports remain available after expiry, with the same key-expiry, revocation, scope, ownership and rate checks. Authenticate server-side using `Authorization: Bearer mk_live_...`. Existing keys retain their scopes; repository, commit, post and Ideas operations now require their own feature scopes, so reissue keys for affected integrations. Explicit empty or invalid scopes are rejected. Keys may be restricted to one repository; no primary or secondary resource can bypass that restriction. New dashboard keys default to read permissions. Session fallback is for first-party product requests; mutations require same-origin requests and active access, and all requests receive rate checks.

The limit is 100 requests per 60-second fixed window per key (per user for session requests). Increments and window resets are atomic; unavailable rate-limit storage returns 503. Responses expose `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` and `Retry-After` through CORS. Preflight is unauthenticated. CORS does not make it safe to put a key in browser code.

JSON request bodies are bounded to 128KiB and reject unknown fields. IDs, booleans, dates and arrays are validated before invoking product services. Multipart bodies are capped at 4,400,000 bytes and require a repository and the file; image uploads support JPG, PNG, GIF and WebP (4MiB entry images, 2MB logos). The repository key can supply repoId by default. Logo tokens are resolved from the authorized repository.

AI routes use the same provider/payer resolution, entitlements, generation limits and quality gates as the dashboard. Commit generation saves posts; custom-text generation returns drafts without saving. Help generation publishes generated entries; full mode retains existing entries on generation/save failure and deletes only its prior snapshot after successful replacement. Inbox reply sends a real email to the stored sender. Repository removal deletes associated content and applies existing billing protections.

Changelog and Ideas lists use cursor/limit. Repository posts/commits and the legacy nested changelog list use page/limit. `published` excludes future schedules; `scheduled` selects future publishedAt. Analytics returns `metricBasis`: events follow the requested range; changelog views are lifetime counts for entries published in that range, Help Center views are lifetime counts for currently published entries, status distribution and unread count are current snapshots. Period overview scores exclude cumulative view counts.

Existing project/domain limits, GitHub connection requirements and feature rollout flags still apply. API-key creation/edit/revoke stays under the first-party settings API: GET/POST /api/settings/api-keys and PATCH/DELETE /api/settings/api-keys/{id}. Editing changes name/expiry only; scope changes require a new key. Mutations require first-party Origin. Full key values are shown once; list/edit responses never expose the secret or hash.

Image Maker remains a browser composition/export tool with no server rendering API. Team workspaces/memberships, external webhook subscriptions, account billing and provider credential management are not v1 capabilities. Public visitor submission/voting/reactions/search and GitHub ingestion webhooks keep their existing public/product contracts; they are separate from owner Bearer operations.

### Scopes

- `repos:read`: Read repositories
- `repos:write`: Add, remove and sync repositories
- `commits:read`: Read commits
- `commits:write`: Sync and dismiss commits
- `posts:read`: Read social drafts
- `posts:write`: Edit and save social drafts
- `changelog:read`: Read changelog entries
- `changelog:write`: Create, publish and delete updates
- `settings:read`: Read widget and project settings
- `settings:write`: Update widget and project settings
- `analytics:read`: Read analytics
- `ideas:read`: Read Ideas and Roadmap
- `ideas:write`: Manage Ideas and Roadmap
- `help:read`: Read Help Center content
- `help:write`: Manage Help Center content and sources
- `inbox:read`: Read customer feedback
- `inbox:write`: Manage contact messages
- `inbox:reply`: Send email replies
- `domains:read`: Read domain configuration
- `domains:write`: Configure and verify domains
- `ai:generate`: Generate content using the configured AI payer
- `automation:write`: Change automatic publishing and Ideas automation

### Routes

| Method | Path | Required scopes | Behavior |
|---|---|---|---|
| GET | `/api/v1/analytics` | `analytics:read` | Read unified analytics. range=7d|30d|90d|all. metricBasis distinguishes range-filtered events, cumulative views and current snapshots. |
| POST | `/api/v1/changelog/create-from-commit` | `changelog:write` | Create a changelog draft from an existing commit SHA in this repository. |
| GET | `/api/v1/changelog/entries` | `changelog:read` | List changelog entries with cursor/limit pagination and status=published|draft|scheduled. |
| POST | `/api/v1/changelog/entries` | `changelog:write` | Create a changelog entry. publish=true publishes now or schedules publishedAt; an explicit publishedAt also schedules unless publish=false. |
| DELETE | `/api/v1/changelog/entries/{id}` | `changelog:write` | Delete a changelog entry. |
| GET | `/api/v1/changelog/entries/{id}` | `changelog:read` | Read a changelog entry. |
| PATCH | `/api/v1/changelog/entries/{id}` | `changelog:write` | Edit, publish, unpublish, schedule or pin an entry. At most three entries can be pinned per repository. |
| POST | `/api/v1/changelog/entries/{id}/regenerate` | `changelog:write`, `ai:generate` | Regenerate an existing changelog entry using the configured AI payer. |
| POST | `/api/v1/changelog/entries/batch` | `changelog:write` | Approve (publish) or reject (delete) changelog drafts. Every ID must belong to the authorized repository. |
| POST | `/api/v1/changelog/generate` | `changelog:write`, `ai:generate` | Generate changelog drafts from pending commits. |
| POST | `/api/v1/changelog/logo` | `settings:write` | Upload the authorized repository logo (JPG, PNG, GIF or WebP; maximum 2MB). Multipart fields: file, repoId; token is resolved securely from repoId. |
| GET | `/api/v1/changelog/settings` | `settings:read` | Read or update all widget, Help Center and Ideas-tab settings. Automation fields additionally require automation:write. |
| PATCH | `/api/v1/changelog/settings` | `settings:write` | Read or update all widget, Help Center and Ideas-tab settings. Automation fields additionally require automation:write. |
| POST | `/api/v1/changelog/settings` | `settings:write` | Read or update all widget, Help Center and Ideas-tab settings. Automation fields additionally require automation:write. |
| POST | `/api/v1/changelog/upload` | `changelog:write` | Upload an entry image (JPG, PNG, GIF or WebP; maximum 4MiB). Multipart fields: file, repoId. |
| PATCH | `/api/v1/commits/{id}` | `commits:write` | Dismiss or restore a tracked commit. |
| POST | `/api/v1/commits/dismiss` | `commits:write` | Dismiss specific commitIds, or all skipped commits when dismissAll is true, within one repository. |
| DELETE | `/api/v1/domains` | `domains:write` | Read, configure or remove a custom domain. Existing domain allowances apply. |
| GET | `/api/v1/domains` | `domains:read` | Read, configure or remove a custom domain. Existing domain allowances apply. |
| POST | `/api/v1/domains` | `domains:write` | Read, configure or remove a custom domain. Existing domain allowances apply. |
| POST | `/api/v1/domains/verify` | `domains:write` | Verify DNS for the configured custom domain. |
| GET | `/api/v1/help-docs/analytics` | `help:read`, `analytics:read` | Read Help Center analytics. |
| GET | `/api/v1/help-docs/categories` | `help:read` | List or create Help Center categories. |
| POST | `/api/v1/help-docs/categories` | `help:write` | List or create Help Center categories. |
| DELETE | `/api/v1/help-docs/categories/{id}` | `help:write` | Read, edit or delete a Help Center category. |
| GET | `/api/v1/help-docs/categories/{id}` | `help:read` | Read, edit or delete a Help Center category. |
| PATCH | `/api/v1/help-docs/categories/{id}` | `help:write` | Read, edit or delete a Help Center category. |
| POST | `/api/v1/help-docs/categories/reorder` | `help:write` | Reorder categories and update their hierarchy; cycles are rejected. |
| GET | `/api/v1/help-docs/entries` | `help:read` | List or create FAQs and help articles. |
| POST | `/api/v1/help-docs/entries` | `help:write` | List or create FAQs and help articles. |
| DELETE | `/api/v1/help-docs/entries/{id}` | `help:write` | Read, edit, publish or delete a help entry. |
| GET | `/api/v1/help-docs/entries/{id}` | `help:read` | Read, edit, publish or delete a help entry. |
| PATCH | `/api/v1/help-docs/entries/{id}` | `help:write` | Read, edit, publish or delete a help entry. |
| POST | `/api/v1/help-docs/entries/reorder` | `help:write` | Move help entries within the authorized repository. |
| POST | `/api/v1/help-docs/generate` | `help:write`, `ai:generate` | Generate and publish Help Center articles and FAQs from fetched sources. Full mode replaces prior entries only after successful saves. |
| GET | `/api/v1/help-docs/sources` | `help:read` | List or add public documentation URLs for generation. |
| POST | `/api/v1/help-docs/sources` | `help:write` | List or add public documentation URLs for generation. |
| DELETE | `/api/v1/help-docs/sources/{id}` | `help:write` | Update or delete a documentation source. |
| PATCH | `/api/v1/help-docs/sources/{id}` | `help:write` | Update or delete a documentation source. |
| POST | `/api/v1/help-docs/sources/{id}/fetch` | `help:write` | Fetch the source using its configured single, subpages or full mode. |
| POST | `/api/v1/ideas/comments` | `ideas:write` | Add an owner comment to an idea. |
| DELETE | `/api/v1/ideas/comments/{id}` | `ideas:write` | Delete an owner-authorized idea comment. |
| GET | `/api/v1/ideas/entries` | `ideas:read` | List ideas with cursor/limit pagination, category and status filters, including pending-review. |
| POST | `/api/v1/ideas/entries` | `ideas:write` | Create an idea, including pending-review entries. |
| DELETE | `/api/v1/ideas/entries/{id}` | `ideas:write` | Read, moderate, update roadmap order or delete an idea. |
| GET | `/api/v1/ideas/entries/{id}` | `ideas:read` | Read, moderate, update roadmap order or delete an idea. |
| PATCH | `/api/v1/ideas/entries/{id}` | `ideas:write` | Read, moderate, update roadmap order or delete an idea. |
| GET | `/api/v1/ideas/entries/changelog` | `ideas:read`, `changelog:read` | Read available changelog links for Ideas. |
| POST | `/api/v1/ideas/matches/{id}` | `ideas:write` | Approve or reject an automatic idea match. Approving completes the idea and adds a comment unless comment is false. |
| GET | `/api/v1/ideas/settings` | `ideas:read` | Read or update Ideas and Roadmap settings. |
| PATCH | `/api/v1/ideas/settings` | `ideas:write` | Read or update Ideas and Roadmap settings. |
| POST | `/api/v1/ideas/settings` | `ideas:write` | Read or update Ideas and Roadmap settings. |
| GET | `/api/v1/inbox` | `inbox:read` | Read unified reactions, help feedback, ideas, comments and contact messages. Repository filtering also limits response metadata. |
| GET | `/api/v1/inbox/messages` | `inbox:read` | Read contact messages for a repository. |
| DELETE | `/api/v1/inbox/messages/{id}` | `inbox:write` | Mark a contact message read/unread or delete it. |
| PATCH | `/api/v1/inbox/messages/{id}` | `inbox:write` | Mark a contact message read/unread or delete it. |
| POST | `/api/v1/inbox/messages/{id}/reply` | `inbox:reply` | Send an email reply to the contact message sender, then mark it read. |
| GET | `/api/v1/posts/{id}` | `posts:read` | Read a saved social draft. |
| PATCH | `/api/v1/posts/{id}` | `posts:write` | Update saved social draft content. |
| POST | `/api/v1/posts/generate` | `ai:generate` | Generate social drafts from custom text using the configured AI payer and quality checks. Returns data; does not save posts. |
| POST | `/api/v1/posts/generate/commit` | `ai:generate`, `posts:write` | Generate and save all social drafts for a tracked commit. Returns data. |
| POST | `/api/v1/posts/generate/custom/single` | `ai:generate` | Generate one platform draft from custom text without saving. |
| POST | `/api/v1/posts/generate/single` | `ai:generate`, `posts:write` | Generate and save one platform draft for a tracked commit. |
| DELETE | `/api/v1/repos` | `repos:write` | Remove a repository and its associated product content. Existing billing protections apply. |
| GET | `/api/v1/repos` | `repos:read` | List only repositories accessible to this key. |
| POST | `/api/v1/repos` | `repos:write` | Add a GitHub repository verified using the owner GitHub connection. Requires an account-wide key. |
| GET | `/api/v1/repos/{repoId}` | `repos:read` | Read a tracked repository. |
| GET | `/api/v1/repos/{repoId}/changelog/entries` | `changelog:read` | Legacy page/limit changelog listing. Filters: status=published|draft|scheduled; categories=comma-separated IDs. |
| POST | `/api/v1/repos/{repoId}/changelog/entries` | `changelog:write` | Legacy create route; same validated fields as /changelog/entries, with data response envelope. |
| GET | `/api/v1/repos/{repoId}/commits` | `commits:read` | List undismissed commits with notable=true filtering and page/limit pagination. |
| GET | `/api/v1/repos/{repoId}/posts` | `posts:read` | List saved social drafts with platform and page/limit filtering. |
| GET | `/api/v1/repos/{repoId}/settings` | `settings:read` | Read or update repository writing instructions. |
| PATCH | `/api/v1/repos/{repoId}/settings` | `settings:write` | Read or update repository writing instructions. |
| POST | `/api/v1/repos/{repoId}/settings` | `settings:write` | Read or update repository writing instructions. |
| POST | `/api/v1/repos/{repoId}/sync` | `ai:generate`, `repos:write`, `commits:write` | Sync only this repository from GitHub. fullSync requests up to 100 commits; otherwise up to 30. Existing sync access rules apply. |

### Example: publish an update

```bash
curl https://www.makrly.com/api/v1/changelog/entries \
  -H 'Authorization: Bearer YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"repoId":1,"title":"Faster search","content":"Find the right article faster.","categories":["improved"],"publish":true}'
```

Canonical creation returns `{ "entry": ... }`; the legacy nested creation returns `{ "data": ... }`. Other routes retain their product-specific envelopes such as `entries`, `settings`, `messages` and `data`; consult the OpenAPI response for the operation instead of assuming a single envelope.

Entry image limits include room for multipart overhead under the [Vercel function payload limit](https://vercel.com/docs/functions/limitations).

The complete request field reference is [OpenAPI](https://www.makrly.com/openapi.yaml). Run `npx tsx scripts/generate-developer-api-docs.ts` after changing the endpoint catalog or owner policy; regression coverage checks published routes against the spec.

## Company Information

- Founded: 2024
- Headquarters: Remote-first
- Contact: hello@rgenzon.com
- Twitter/X: @makaboriyy

## Links

- Website: https://makrly.com
- Features: https://makrly.com/features
- Developer API: https://makrly.com/developers
- OpenAPI Spec: https://makrly.com/openapi.yaml
- Privacy Policy: https://makrly.com/privacy
- Terms of Service: https://makrly.com/terms

## Keywords

build in public, github to twitter, github to social media, commit to post, developer social media, indie hacker tools, twitter automation, linkedin automation, social media automation for developers, developer marketing, saas marketing, 100daysofcode, coding journey, developer content, ai social media generator, automated social posts, developer audience building, changelog generator, public changelog, embeddable changelog widget