{"openapi":"3.1.0","info":{"title":"Growcita Public API","version":"1.0.0","description":"Run Growcita's 10 AI marketing agents and read their results. Tasks execute asynchronously against the user's real connected marketing platforms — create a task, then poll it until completed. Write actions inside agent runs respect the user's autonomy and approval settings, so a task may finish with drafts or a pending human approval instead of a live change. Get an API key at https://growcita.com/settings/api-keys; full docs at https://growcita.com/developers/api."},"servers":[{"url":"https://growcita.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/agents":{"get":{"operationId":"listAgents","summary":"List the 10 marketing agents with specialties and sub-specialties.","responses":{"200":{"description":"Agent catalog","content":{"application/json":{"schema":{"type":"object","required":["agents"],"properties":{"agents":{"type":"array","items":{"$ref":"#/components/schemas/Agent"}}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited — honor the Retry-After header","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sessions":{"get":{"operationId":"listSessions","summary":"List your workspaces (sessions). Tasks always run inside a session.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"The caller's workspaces","content":{"application/json":{"schema":{"type":"object","required":["sessions","pagination"],"properties":{"sessions":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSession","summary":"Create a workspace for a company (name required; companyName/companyUrl recommended).","description":"Creates a workspace without triggering the in-app onboarding research crawl. Prefer reusing an existing session — it already carries learned company context and platform connections.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":120},"companyName":{"type":"string","maxLength":200},"companyUrl":{"type":"string","format":"uri","maxLength":500},"industry":{"type":"string","maxLength":100},"targetAudience":{"type":"string","maxLength":300}}}}}},"responses":{"201":{"description":"Created workspace","content":{"application/json":{"schema":{"type":"object","required":["session"],"properties":{"session":{"$ref":"#/components/schemas/Session"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks":{"post":{"operationId":"createTask","summary":"Run an agent task from a plain-English instruction. Async — returns the task with its current status; optionally waits up to 120s.","description":"Enqueues a background agent run. Returns 201 with the task in its current state — typically still pending or running; poll GET /tasks/{taskId} (suggested every 10–30s) until status is completed or failed. Typical runs take 1–5 minutes. Set waitSeconds (max 120) to have the server poll before responding. Tasks are not retried automatically.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sessionId","instruction"],"properties":{"sessionId":{"type":"string","format":"uuid"},"agentType":{"type":"string","enum":["growth-marketer","organic-social","paid-media","seo","email-marketing","creative","web-developer","cro","influencer-marketing","demand-gen"],"default":"growth-marketer","description":"Target agent. growth-marketer (default) is the supervisor and delegates to specialists."},"instruction":{"type":"string","minLength":4,"maxLength":4000,"description":"Plain-English brief for the agent."},"title":{"type":"string","maxLength":200},"priority":{"type":"string","enum":["low","normal","high"],"default":"normal"},"waitSeconds":{"type":"integer","minimum":0,"maximum":120,"default":0}}}}}},"responses":{"201":{"description":"Task created (status may still be pending/running — keep polling)","content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Monthly Growcita budget exhausted for this account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An identical task is already pending","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"listTasks","summary":"List recent tasks, filterable by sessionId, status, and agentType.","parameters":[{"name":"sessionId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","running","completed","failed"]}},{"name":"agentType","in":"query","schema":{"type":"string","enum":["growth-marketer","organic-social","paid-media","seo","email-marketing","creative","web-developer","cro","influencer-marketing","demand-gen"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Tasks, newest first","content":{"application/json":{"schema":{"type":"object","required":["tasks","pagination"],"properties":{"tasks":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Filtered session not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tasks/{taskId}":{"get":{"operationId":"getTask","summary":"Get one task's status, result, and error.","parameters":[{"name":"taskId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The task","content":{"application/json":{"schema":{"type":"object","required":["task"],"properties":{"task":{"$ref":"#/components/schemas/Task"}}}}}},"400":{"description":"Invalid task id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Task not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me":{"get":{"operationId":"introspectKey","summary":"Introspect the API key used for the request (name, prefix, expiry, last use).","responses":{"200":{"description":"Metadata of the key used for this request","content":{"application/json":{"schema":{"type":"object","required":["key"],"properties":{"key":{"$ref":"#/components/schemas/ApiKeyInfo"}}}}}},"401":{"description":"Missing, invalid, revoked, or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings → API Keys (format gcta_…). Send as `Authorization: Bearer gcta_…`."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Pagination":{"type":"object","required":["page","limit","total","totalPages"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"Agent":{"type":"object","required":["type","name","description","isSupervisor","subspecialties"],"properties":{"type":{"type":"string","enum":["growth-marketer","organic-social","paid-media","seo","email-marketing","creative","web-developer","cro","influencer-marketing","demand-gen"]},"name":{"type":"string"},"description":{"type":"string"},"isSupervisor":{"type":"boolean","description":"True only for growth-marketer, which can delegate to all specialists."},"subspecialties":{"type":"array","items":{"type":"object","required":["id","name","description"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"}}}}}},"Session":{"type":"object","required":["id","name","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"companyName":{"type":["string","null"]},"companyUrl":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"Task":{"type":"object","required":["id","sessionId","agentType","taskType","status"],"properties":{"id":{"type":"string","format":"uuid"},"sessionId":{"type":"string","format":"uuid"},"agentType":{"type":"string"},"taskType":{"type":"string"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"instruction":{"type":["string","null"],"description":"The brief the task was created with."},"result":{"type":["string","null"],"description":"Agent output; null until status is completed."},"error":{"type":["string","null"]},"createdAt":{"type":["string","null"],"format":"date-time"},"startedAt":{"type":["string","null"],"format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"}}},"ApiKeyInfo":{"type":"object","required":["id","name","keyPrefix","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"lastUsedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":["string","null"],"format":"date-time"}}}}}}