# GroZro developer docs (full)

> Your AI growth operator — drafts the content, you stay editor-in-chief.

GroZro is an AI-native social growth operator. It drafts platform-native post batches from your growth profile, learns from your analytics, and keeps every post behind your approval.

## Authentication

Create a tenant API key at app.grozro.com → Settings → Developer access (https://app.grozro.com/settings).
Keys are prefixed `ak_`, shown once, and carry the scopes
api:read, api:write, mcp:use. Pass them as a Bearer token. Scopes are method-based:
GETs need `api:read`; POST/PUT/DELETE need `api:write` (403
`API key missing scope: api:write` otherwise); `mcp:use` unlocks the MCP
endpoint, which hides mutating tools from keys without `api:write`. The
API-key-reachable surface is `/api/v1/growth/*`, `/api/v1/mcp`, and the
public no-auth pair `/api/v1/openapi.json` + `/api/v1/capabilities` (the
capability manifest, also at `/.well-known/grozro.json`); every other route serves
the web app with session JWTs.

## REST API

Base URL: `https://api.grozro.com`.

```bash
curl -H "Authorization: Bearer ak_…" \
  https://api.grozro.com/api/v1/growth/items?status=drafted
```

The core loop:

- `GET /api/v1/growth/connection` — Verify the key. Returns the connected X account; 401 means the key is wrong. connected:false still allows drafting, approving, and scheduling — only post-now and engagement execution need X.
- `GET /api/v1/growth/overview` — See the workspace. Profile, channels, drafted queue, and learnings in one call.
- `POST /api/v1/growth/batches` — Draft a batch. Body {"count": 6, "focus": "launch week"}. Generation is async.
- `POST /api/v1/growth/articles` — Draft an article. Body {"topic": "…", "length": "medium"}. Long-form X article.
- `GET /api/v1/growth/batches/{id}` — Watch the batch settle. Poll every ~20s; drafts typically take 1–3 minutes. Status becomes ready or failed — a failed batch sets error to "generation_failed: …" with a retry hint. Retry once; if it fails again, adjust as the hint says.
- `GET /api/v1/growth/items?status=drafted` — Review the queue. Drafted items land here once their batch settles ready.
- `POST /api/v1/growth/items/{id}/approve` — Approve or reject. Optional {"edited_body": "…"}; /reject takes {"reason": "…"}.
- `POST /api/v1/growth/items/{id}/post-now` — Post or schedule. Or /schedule with {"post_at": ISO-8601} — the worker posts when due.

Plan limits: generation endpoints return 403 with `plan_quota_exceeded:<key>`
or `plan_feature_disabled:<feature>` when the workspace plan does not allow
the call, and `plan_invalid:<reason>` when the billing state blocks costly
actions (reads stay open; fix billing to resume). A 429 `rate_limited:<action>`
means an hourly cap tripped — back off. Full endpoint reference:
`https://api.grozro.com/api/v1/openapi.json`.

Async generation: batches, articles, audits, and reports settle `ready` or
`failed` — poll their GET endpoint every ~20s; drafts typically take 1–3
minutes. On `failed` the record's `error` is a stable code:
`generation_failed: <retry hint>` (model could not produce valid output —
retry once, then follow the hint), `cancelled`, or `enqueue_failed`
(infrastructure; safe to retry). Webhook subscribers get the same terminal
state as `growth.batch.settled`.

Retries: send an `Idempotency-Key` header (any unique string ≤200 chars)
on mutating calls — a retry with the same key replays the stored response
(`Idempotency-Replayed: true`) instead of re-executing, so a retried
post-now can never double-post. A concurrent duplicate gets 409
`idempotency_in_flight`; keys expire after 24h. Only 2xx responses are
stored — failed calls re-execute on retry.

## CLI

Install: `npm install -g grozro` (Node 20+). No global-install rights? A local
install works too: `npm install grozro --prefix .` then run
`./node_modules/.bin/grozro`. `grozro login` does a browser
device-flow login (approve a one-time code in the app); `--api-key` is the
non-interactive path. Config is stored in `~/.grozro/config.json` (0600).
`--api-url` targets another stack. `grozro help` lists what your
installed version supports; `npm update -g grozro` upgrades it.

- `grozro login` — Browser login: approve a code in the app. CI/agents: --api-key ak_…
- `grozro overview` — Workspace snapshot: profile, channels, drafted queue, learnings
- `grozro brief [--items]` — Daily operator brief: ranked "do this next" actions from workspace state (?include=items hydrates each action with its actionable rows)
- `grozro batch [--count 6] [--focus …]` — Draft a batch of ready-to-post content (async — poll the batch)
- `grozro batches list` — List recent batches
- `grozro batches get <id>` — One batch with its drafted items (settles in-flight generation)
- `grozro article <topic…> [--outline …] [--length short|medium|long]` — Draft one long-form X article (async — poll GET /articles)
- `grozro articles [get <id>]` — List long-form articles
- `grozro articles get <id>` — One article
- `grozro queue [--status drafted]` — List content items by status
- `grozro approve <id> [--body …]` — Approve a drafted item (optional edited body; articles may retitle)
- `grozro reject <id> [--reason …]` — Reject a drafted item
- `grozro item posted <id> [--url …]` — Mark an approved item posted (manual publish path)
- `grozro item schedule <id> --at <iso8601>` — Schedule an approved item; the worker posts it when due
- `grozro item unschedule <id>` — Clear an approved item's schedule; it stays approved in the queue
- `grozro post <id>` — Post an approved item to X immediately (articles go out as one long post)
- `grozro whoami` — Connected X account state
- `grozro connection disconnect` — Disconnect the X account
- `grozro accounts [set-default <id>]` — List connected X accounts (multi-account)
- `grozro accounts set-default <id>` — Make an account the default new content posts from
- `grozro profile update [--goal …] [--voice …] [--json {…}]` — Update the growth profile and Writing DNA (voice, stories, proof, patterns…)
- `grozro channels update <id> [--status active|inactive] [--json {…}]` — Update a platform channel (status, format rules, cadence)
- `grozro audit` — Run an analytics audit (from synced metrics by default)
- `grozro audits get <id>` — Audit result with extracted learnings
- `grozro learnings [add|retire]` — List learnings (what worked / flopped / hypotheses)
- `grozro learnings add --kind worked|flopped|hypothesis --note …` — Add a learning
- `grozro learnings retire <id>` — Retire a learning
- `grozro engage list [--status …]` — List engagement suggestions/drafts (replies, quotes)
- `grozro engage create <url|id> --action reply|quote|repost|like` — Draft an engagement against an X post
- `grozro engage approve <id> [--body …]` — Approve a drafted engagement
- `grozro engage reject <id> [--reason …]` — Reject a drafted engagement
- `grozro engage execute <id>` — Execute an approved engagement on X
- `grozro targets list` — List target accounts
- `grozro targets add <handle> [--category …] [--priority 1-3]` — Add a target account to watch
- `grozro targets update <id> [--status active|paused] [--priority 1-3]` — Update or pause a target
- `grozro signals list` — List open signals from watched targets
- `grozro signals dismiss <id>` — Dismiss a signal
- `grozro signals engage <id> --action reply|quote|repost|like` — Engage a signal (drafts a reply/quote)
- `grozro products list` — List products available for self-promotion weaving
- `grozro products add --name … --one-liner … [--url …]` — Add a product
- `grozro products update <id> [--status active|archived] [--json {…}]` — Update or archive a product
- `grozro hooks` — Hook-pattern library with usage stats
- `grozro reports list` — List weekly reports
- `grozro reports create` — Generate a weekly report
- `grozro experiments list` — List experiments
- `grozro experiments create --name … --hypothesis …` — Create an experiment
- `grozro experiments conclude <id> --result …` — Conclude an experiment with a verdict
- `grozro rules list [update|pause-all|resume-all|runs]` — List automation rules
- `grozro rules update <id> [--status active|paused] [--json {…}]` — Update an automation rule
- `grozro rules runs [--rule-id <id>]` — List recent automation rule runs
- `grozro rules pause-all` — Pause all automation (kill switch)
- `grozro rules resume-all` — Resume automation
- `grozro calendar` — List scheduled/approved items (alias for `queue --status approved`)

## MCP

Streamable-HTTP MCP server at `https://api.grozro.com/api/v1/mcp` (scope `mcp:use`).

```bash
claude mcp add grozro --transport http \
  https://api.grozro.com/api/v1/mcp \
  --header "Authorization: Bearer ak_…"
```

Growth tools:

- `growth_overview` — Workspace snapshot: profile, channels, drafted queue, learnings
- `growth_get_brief` — Daily operator brief: ranked "do this next" actions from workspace state (?include=items hydrates each action with its actionable rows)
- `growth_create_batch` — Draft a batch of ready-to-post content (async — poll the batch)
- `growth_list_batches` — List recent batches
- `growth_create_article` — Draft one long-form X article (async — poll GET /articles)
- `growth_list_articles` — List long-form articles
- `growth_list_queue` — List content items by status
- `growth_approve_item` — Approve a drafted item (optional edited body; articles may retitle)
- `growth_reject_item` — Reject a drafted item
- `growth_mark_item_posted` — Mark an approved item posted (manual publish path)
- `growth_schedule_item` — Schedule an approved item; the worker posts it when due
- `growth_unschedule_item` — Clear an approved item's schedule; it stays approved in the queue
- `growth_post_item` — Post an approved item to X immediately (articles go out as one long post)
- `growth_connection_status` — Connected X account state
- `growth_list_accounts` — List connected X accounts (multi-account)
- `growth_set_default_account` — Make an account the default new content posts from
- `growth_update_profile` — Update the growth profile and Writing DNA (voice, stories, proof, patterns…)
- `growth_update_channel` — Update a platform channel (status, format rules, cadence)
- `growth_create_audit` — Run an analytics audit (from synced metrics by default)
- `growth_list_learnings` — List learnings (what worked / flopped / hypotheses)
- `growth_add_learning` — Add a learning
- `growth_retire_learning` — Retire a learning
- `growth_list_engagements` — List engagement suggestions/drafts (replies, quotes)
- `growth_create_engagement` — Draft an engagement against an X post
- `growth_approve_engagement` — Approve a drafted engagement
- `growth_reject_engagement` — Reject a drafted engagement
- `growth_execute_engagement` — Execute an approved engagement on X
- `growth_list_targets` — List target accounts
- `growth_add_target` — Add a target account to watch
- `growth_update_target` — Update or pause a target
- `growth_list_signals` — List open signals from watched targets
- `growth_dismiss_signal` — Dismiss a signal
- `growth_engage_signal` — Engage a signal (drafts a reply/quote)
- `growth_list_products` — List products available for self-promotion weaving
- `growth_add_product` — Add a product
- `growth_update_product` — Update or archive a product
- `growth_list_hooks` — Hook-pattern library with usage stats
- `growth_list_reports` — List weekly reports
- `growth_create_report` — Generate a weekly report
- `growth_list_experiments` — List experiments
- `growth_create_experiment` — Create an experiment
- `growth_conclude_experiment` — Conclude an experiment with a verdict
- `growth_list_rules` — List automation rules
- `growth_create_rule` — Create an automation rule
- `growth_update_rule` — Update an automation rule
- `growth_list_rule_runs` — List recent automation rule runs
- `growth_pause_automation` — Pause all automation (kill switch)
- `growth_resume_automation` — Resume automation

Plus general workspace tools (memory, scheduling, playbooks, artifacts,
documents search) depending on enabled modules.

## Agent onboarding

Copy-paste block for AI agents: https://docs.grozro.com/agents.md
Human version: https://docs.grozro.com/docs/agents