The REST API

Run any of the 10 marketing agents from your own code: create a task from a plain-English instruction, poll until it completes, read the result.

Get an API key OpenAPI 3.1 spec

Authentication

Every request carries your API key as a Bearer token. Keys look like gcta_…, are created under Settings → API Keys, and are shown once. Verify your setup with the introspection endpoint:

bash

curl https://growcita.com/api/v1/me \
  -H "Authorization: Bearer $GROWCITA_API_KEY"

The task lifecycle

1 — Find your workspace

bash

curl https://growcita.com/api/v1/sessions \
  -H "Authorization: Bearer $GROWCITA_API_KEY"

Tasks always run inside a session (workspace). Most accounts have one per company.

2 — Create a task

bash

curl -X POST https://growcita.com/api/v1/tasks \
  -H "Authorization: Bearer $GROWCITA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "SESSION_UUID",
    "agentType": "seo",
    "instruction": "Audit our site for technical SEO issues and list the top 10 fixes",
    "waitSeconds": 60
  }'

agentType is optional — it defaults to growth-marketer, the supervisor, which delegates to specialists. waitSeconds (max 120) makes the server poll before responding.

3 — Poll until terminal

bash

curl https://growcita.com/api/v1/tasks/TASK_UUID \
  -H "Authorization: Bearer $GROWCITA_API_KEY"

Runs typically take 1–5 minutes. Poll every 10–30 seconds until status is "completed" or "failed"; the result field then holds the agent's full output. Tasks are not retried automatically.

Write actions respect approval settings

Agents work on real connected platforms, governed by the account's autonomy and guardrail settings. Publishing posts, enabling campaigns, or changing budgets may finish as drafts or wait for human approval in the Growcita app — a completed task whose result says "pending approval" is expected behavior, not an error.

Endpoints

Base URL: https://growcita.com/api/v1 — full request/response schemas live in the OpenAPI spec.

GET /agents	List the 10 marketing agents with specialties and sub-specialties.
GET /sessions	List your workspaces (sessions). Tasks always run inside a session.
POST /sessions	Create a workspace for a company (name required; companyName/companyUrl recommended).
POST /tasks	Run an agent task from a plain-English instruction. Async — returns the task with its current status; optionally waits up to 120s.
GET /tasks	List recent tasks, filterable by sessionId, status, and agentType.
GET /tasks/{taskId}	Get one task's status, result, and error.
GET /me	Introspect the API key used for the request (name, prefix, expiry, last use).
GET /openapi.json	Machine-readable OpenAPI 3.1 description of this API (no auth required).

Sessions created through the API skip the in-app onboarding research crawl — include companyName and companyUrl so agents have context, or create the workspace in the app first.

Status codes

Errors are always { "error": string }.

200 / 201	Success — 201 returns the created session or task.
400	Validation error — the response body explains which field.
401	Missing, invalid, revoked, or expired API key.
402	Monthly Growcita budget exhausted for this account.
404	Session or task not found (or owned by another account).
409	An identical task is already pending for this session.
429	Rate limited — honor the Retry-After header.

Rate limits

Per API-key owner, refilling continuously (GCRA).

POST /tasks	20 / minute
GET /tasks, GET /tasks/{taskId}	120 / minute
GET & POST /sessions	60 / minute
GET /agents, GET /me	60 / minute

429 responses include Retry-After. Agent execution itself is additionally governed by your plan's monthly budget — when exhausted, task creation returns 402.

Prefer MCP?

The same capabilities are exposed as MCP tools for Claude, Claude Code, Cursor, and Codex.

MCP server docs