Tell your AI agent to set this up

# Set up GroZro for your operator

You are configuring GroZro (https://grozro.com) — an AI social-growth
operator for X. It drafts platform-native content in the operator's voice;
every post stays behind human approval. Your job: connect to the API and run
the content loop on the human's behalf.

## 1. Get an API key (human step)

Ask your human to create a key at app.grozro.com → Settings → Developer access
(direct link: https://app.grozro.com/settings). Keys look like `ak_…`,
are shown once, and carry the scopes api:read, api:write, mcp:use. Scopes are
method-based: reads (GET) need `api:read`; mutations — drafting, approving,
posting — need `api:write` (403 `API key missing scope: api:write`
otherwise); `mcp:use` unlocks the MCP endpoint.

## 2. Verify the key

```bash
curl -H "Authorization: Bearer ak_…" https://api.grozro.com/api/v1/growth/connection
```

A 200 with JSON means you are in. 401 → wrong or revoked key.

Read the response before acting on it:

- `connected: false` — no X account linked yet. Drafting, approving,
  scheduling, and learnings all still work; only `post-now` and engagement
  execution fail with 400 `x_not_connected`. Ask the human to connect X in
  the app settings; `mark-posted` records content they posted by hand.
- `tier` is the server's X read tier. `payg` means reads (signals,
  mentions, target watching) spend a metered budget — a 429
  `x_read_budget_exhausted` means today's read budget is gone and read-side
  features resume tomorrow; drafting and posting are unaffected.

## 3. Pick your surface

**REST** (works everywhere): base URL `https://api.grozro.com`, Bearer auth with the key.
Machine spec: `https://api.grozro.com/api/v1/openapi.json` (no auth). Capability manifest —
endpoints, scopes, error codes: `https://api.grozro.com/api/v1/capabilities` (no auth).

**MCP** (best for AI clients): streamable-HTTP server with growth tools
(growth_overview, growth_get_brief, growth_create_batch, growth_list_batches, growth_create_article, growth_list_articles, growth_list_queue, growth_approve_item, growth_reject_item, growth_mark_item_posted, growth_schedule_item, growth_unschedule_item, growth_post_item, growth_connection_status, growth_list_accounts, growth_set_default_account, growth_update_profile, growth_update_channel, growth_create_audit, growth_list_learnings, growth_add_learning, growth_retire_learning, growth_list_engagements, growth_create_engagement, growth_approve_engagement, growth_reject_engagement, growth_execute_engagement, growth_list_targets, growth_add_target, growth_update_target, growth_list_signals, growth_dismiss_signal, growth_engage_signal, growth_list_products, growth_add_product, growth_update_product, growth_list_hooks, growth_list_reports, growth_create_report, growth_list_experiments, growth_create_experiment, growth_conclude_experiment, growth_list_rules, growth_create_rule, growth_update_rule, growth_list_rule_runs, growth_pause_automation, growth_resume_automation).

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

**CLI** (for terminals): `npm install -g grozro`, then
`grozro login --api-key ak_…` (non-interactive; humans can run plain
`grozro login` for browser approval). Config lands in `~/.grozro/config.json`.

## 4. Run the core loop

1. **Verify the key** — `GET /api/v1/growth/connection`
   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.
2. **See the workspace** — `GET /api/v1/growth/overview`
   Profile, channels, drafted queue, and learnings in one call.
3. **Draft a batch** — `POST /api/v1/growth/batches`
   Body {"count": 6, "focus": "launch week"}. Generation is async.
4. **Draft an article** — `POST /api/v1/growth/articles`
   Body {"topic": "…", "length": "medium"}. Long-form X article.
5. **Watch the batch settle** — `GET /api/v1/growth/batches/{id}`
   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.
6. **Review the queue** — `GET /api/v1/growth/items?status=drafted`
   Drafted items land here once their batch settles ready.
7. **Approve or reject** — `POST /api/v1/growth/items/{id}/approve`
   Optional {"edited_body": "…"}; /reject takes {"reason": "…"}.
8. **Post or schedule** — `POST /api/v1/growth/items/{id}/post-now`
   Or /schedule with {"post_at": ISO-8601} — the worker posts when due.

## Guardrails

- NEVER post or approve content without the human's explicit go-ahead —
  the drafted → approved transition is the human checkpoint.
- Generation is async and CAN fail: a batch/article settles `ready` or
  `failed` (typically 1–3 minutes). On `failed`, the record's `error`
  starts with `generation_failed:` and includes a retry hint — retry once,
  then follow the hint (lower count, shorter focus, or add evidence to the
  profile) instead of looping.
- Retrying a mutation? Send an `Idempotency-Key` header (unique string per
  logical request) — the same key replays the stored response instead of
  re-executing, so a retried post can never double-post.
- Generation endpoints are subject to plan quotas; a 403 with
  `plan_quota_exceeded:…` means the workspace hit its monthly limit —
  surface it, don't retry.
- A 403 with `plan_invalid:…` means the workspace billing state blocks
  costly actions (reads still work) — tell the human to fix billing,
  don't retry.
- Full docs for everything else: https://docs.grozro.com/llms-full.txt