API Reference

Complete endpoint reference for the Growhold REST API and MCP server.

Authentication

All API requests require an API key. Create and manage keys from the API & Devs page in your workspace settings.

API keys

API keys start with gh_ and are scoped with permissions for specific domains: knowledge, runs, schedules, agents, and specialists. Keys are hashed before storage. Copy your secret immediately after creation.

Request format

All API calls use a single POST endpoint with action-based routing. Send your key as a Bearer token and the action as a JSON field.

Base URL

https://app.growhold.com/functions/v1/api

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "agents.list"}'

Knowledge

Add, list, remove, and apply knowledge entries to agents and specialists.

knowledge.list

List knowledge entries, optionally filtered by agent or specialist.

Name	Type	Required	Description
`agent_id`	string	No	Filter by agent
`specialist_id`	string	No	Filter by specialist

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "knowledge.list"}'

Response

{
  "knowledge": [
    {
      "id": "uuid",
      "name": "Product FAQ",
      "type": "text",
      "chunk_count": 12,
      "created_at": "2026-03-01T10:00:00Z"
    }
  ]
}

knowledge.add

Add a knowledge entry. Provide either text content or a file URL. Content is automatically chunked and embedded.

Name	Type	Required	Description
`name`	string	Yes	Display name
`content`	string	No	Text content (use this or file_url)
`file_url`	string	No	URL to a file to ingest
`agent_id`	string	No	Attach to agent
`specialist_id`	string	No	Attach to specialist

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "knowledge.add",
    "name": "Product FAQ",
    "content": "Q: What is Growhold?\nA: An AI agent platform."
  }'

Response

{
  "knowledge": {
    "id": "new-uuid",
    "name": "Product FAQ",
    "type": "text",
    "chunk_count": 3
  }
}

knowledge.remove

Remove a knowledge entry and all its embeddings.

Name	Type	Required	Description
`knowledge_id`	string	Yes	Entry to remove

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "knowledge.remove", "knowledge_id": "uuid"}'

Response

{ "deleted": true }

knowledge.apply

Apply an existing knowledge entry to an agent or specialist.

Name	Type	Required	Description
`knowledge_id`	string	Yes	Knowledge entry
`agent_id`	string	No	Target agent
`specialist_id`	string	No	Target specialist

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "knowledge.apply", "knowledge_id": "uuid", "agent_id": "agent-uuid"}'

Response

{ "applied": true }

Agent Runs

Start, monitor, pause, and stop agent runs. Retrieve output cards with content, images, and charts.

runs.list

List agent runs, newest first.

Name	Type	Required	Description
`agent_id`	string	No	Filter by agent
`limit`	number	No	Max results (default 50)

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "runs.list"}'

Response

{
  "runs": [
    {
      "id": "run-uuid",
      "name": "Market Analysis Q1",
      "auto_status": "completed",
      "created_at": "2026-03-31T10:00:00Z",
      "agent": { "id": "agent-uuid", "name": "Market Analyzer" }
    }
  ]
}

runs.get

Get full details of a run including cards, assistant progress, and status.

Name	Type	Required	Description
`run_id`	string	Yes	The run ID

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "runs.get", "run_id": "run-uuid"}'

Response

{
  "run": {
    "id": "run-uuid",
    "name": "Market Analysis Q1",
    "auto_status": "completed",
    "card": [
      {
        "id": "card-uuid",
        "order_id": 1,
        "markdown_content": "## Analysis\n..."
      }
    ],
    "run_assistant": [
      { "id": "ra-uuid", "summary": "Completed" }
    ]
  }
}

runs.start

Start a new async agent run. Returns immediately with the run ID. Poll runs.get for status.

Name	Type	Required	Description
`agent_id`	string	Yes	Agent to run
`name`	string	No	Custom run name
`goal`	string	No	Goal for the run
`input_values`	object	No	Input field values

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "runs.start",
    "agent_id": "agent-uuid",
    "name": "Weekly Report",
    "goal": "Generate the weekly market report"
  }'

Response

{
  "run_id": "new-run-uuid",
  "name": "Weekly Report",
  "status": "running"
}

runs.stop

Stop a running agent permanently.

Name	Type	Required	Description
`run_id`	string	Yes	Run to stop

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "runs.stop", "run_id": "run-uuid"}'

Response

{ "run_id": "run-uuid", "status": "stopped" }

runs.pause

Pause a running agent. Use runs.resume to continue.

Name	Type	Required	Description
`run_id`	string	Yes	Run to pause

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "runs.pause", "run_id": "run-uuid"}'

Response

{ "run_id": "run-uuid", "status": "paused" }

runs.resume

Resume a paused agent run.

Name	Type	Required	Description
`run_id`	string	Yes	Run to resume

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "runs.resume", "run_id": "run-uuid"}'

Response

{ "run_id": "run-uuid", "status": "running" }

Cards

Retrieve output cards with markdown content, structured JSON, images, and charts. File URLs are signed and valid for 1 hour.

cards.list

List output cards for a run.

Name	Type	Required	Description
`run_id`	string	Yes	The run ID

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "cards.list", "run_id": "run-uuid"}'

Response

{
  "cards": [
    {
      "id": "card-uuid",
      "order_id": 1,
      "markdown_content": "## Report\n...",
      "image_url": "https://...",
      "is_starred": true
    }
  ]
}

cards.get

Get a single card with full content and attached files (images, charts). File URLs are signed.

Name	Type	Required	Description
`card_id`	string	Yes	The card ID

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "cards.get", "card_id": "card-uuid"}'

Response

{
  "card": {
    "id": "card-uuid",
    "markdown_content": "## Report\n...",
    "content_json": { ... },
    "image_url": "https://..."
  },
  "files": [
    {
      "id": "file-uuid",
      "file_name": "chart.png",
      "signed_url": "https://..."
    }
  ]
}

Schedules

Create and manage scheduled agent runs using cron expressions.

schedules.list

List all schedules in the workspace.

Name	Type	Required	Description
`agent_id`	string	No	Filter by agent

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedules.list"}'

Response

{
  "schedules": [
    {
      "id": "schedule-uuid",
      "name": "Weekly Report",
      "cron": "0 9 * * 1",
      "is_active": true,
      "next_run_at": "2026-03-31T09:00:00Z"
    }
  ]
}

schedules.create

Create a new schedule.

Name	Type	Required	Description
`agent_id`	string	Yes	Agent to schedule
`name`	string	Yes	Schedule name
`cron`	string	Yes	Cron expression (e.g. "0 9 * * 1")
`goal`	string	No	Goal for each run
`input_values`	object	No	Input values per run

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "schedules.create",
    "agent_id": "agent-uuid",
    "name": "Daily Summary",
    "cron": "0 8 * * *"
  }'

Response

{
  "schedule": {
    "id": "new-uuid",
    "name": "Daily Summary",
    "cron": "0 8 * * *",
    "is_active": true
  }
}

schedules.update

Update schedule settings. Only provided fields are changed.

Name	Type	Required	Description
`schedule_id`	string	Yes	Schedule ID
`name`	string	No	New name
`cron`	string	No	New cron expression
`goal`	string	No	New goal

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedules.update", "schedule_id": "uuid", "cron": "0 10 * * 1-5"}'

Response

{ "schedule": { "id": "uuid", "cron": "0 10 * * 1-5", "is_active": true } }

schedules.delete

Delete a schedule permanently.

Name	Type	Required	Description
`schedule_id`	string	Yes	Schedule to delete

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedules.delete", "schedule_id": "uuid"}'

Response

{ "deleted": true }

schedules.pause

Pause a schedule. Runs stop triggering until resumed.

Name	Type	Required	Description
`schedule_id`	string	Yes	Schedule to pause

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedules.pause", "schedule_id": "uuid"}'

Response

{ "schedule_id": "uuid", "is_active": false }

schedules.resume

Resume a paused schedule.

Name	Type	Required	Description
`schedule_id`	string	Yes	Schedule to resume

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "schedules.resume", "schedule_id": "uuid"}'

Response

{ "schedule_id": "uuid", "is_active": true }

Cron expression reference

# Format: minute hour day-of-month month day-of-week
#
# "0 9 * * *"     Every day at 9:00 AM UTC
# "0 9 * * 1"     Every Monday at 9:00 AM UTC
# "0 9 * * 1-5"   Weekdays at 9:00 AM UTC
# "0 */6 * * *"   Every 6 hours
# "30 14 1 * *"   1st of each month at 2:30 PM UTC

Agents & Specialists

List and inspect agents and specialists in your workspace.

agents.list

List all agents with their assistants.

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "agents.list"}'

Response

{
  "agents": [
    {
      "id": "agent-uuid",
      "name": "Market Analyzer",
      "deliverable": "Market Report",
      "assistant": [
        { "id": "asst-uuid", "name": "Research Analyst" }
      ]
    }
  ]
}

agents.get

Get agent details.

Name	Type	Required	Description
`agent_id`	string	Yes	Agent ID

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "agents.get", "agent_id": "agent-uuid"}'

Response

{ "agent": { "id": "agent-uuid", "name": "Market Analyzer", ... } }

specialists.list

List all specialists.

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "specialists.list"}'

Response

{
  "specialists": [
    { "id": "uuid", "name": "SEO Expert", "is_default": false }
  ]
}

specialists.get

Get specialist details.

Name	Type	Required	Description
`specialist_id`	string	Yes	Specialist ID

Example

curl -X POST https://app.growhold.com/functions/v1/api \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"action": "specialists.get", "specialist_id": "uuid"}'

Response

{ "specialist": { "id": "uuid", "name": "SEO Expert", ... } }

MCP Server

Connect Growhold to Claude Desktop, Cursor, or any MCP-compatible AI client using the Model Context Protocol.

Setup

Add the MCP server to your Claude Desktop configuration. On macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "growhold": {
      "url": "https://app.growhold.com/functions/v1/mcp",
      "headers": {
        "Authorization": "Bearer gh_your_api_key"
      }
    }
  }
}

Available tools

The MCP server exposes all API actions as tools. Tool availability depends on your API key permissions.

Tool	Permission	Description
`knowledge_list`	knowledge	List knowledge entries
`knowledge_add`	knowledge	Add text or file as knowledge
`knowledge_remove`	knowledge	Remove a knowledge entry
`knowledge_apply`	knowledge	Apply knowledge to agent/specialist
`runs_list`	runs	List agent runs
`runs_get`	runs	Get run details with cards
`runs_start`	runs	Start an async agent run
`runs_stop`	runs	Stop a running agent
`runs_pause`	runs	Pause a running agent
`runs_resume`	runs	Resume a paused agent
`cards_list`	runs	List output cards for a run
`cards_get`	runs	Get card with signed file URLs
`schedules_list`	schedules	List schedules
`schedules_create`	schedules	Create a schedule
`schedules_update`	schedules	Update a schedule
`schedules_delete`	schedules	Delete a schedule
`schedules_pause`	schedules	Pause a schedule
`schedules_resume`	schedules	Resume a schedule
`agents_list`	agents	List agents
`agents_get`	agents	Get agent details
`specialists_list`	specialists	List specialists
`specialists_get`	specialists	Get specialist details

Raw JSON-RPC

For custom MCP clients, send JSON-RPC 2.0 requests directly:

List tools

curl -X POST https://app.growhold.com/functions/v1/mcp \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

Call a tool

curl -X POST https://app.growhold.com/functions/v1/mcp \
  -H "Authorization: Bearer gh_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "agents_list",
      "arguments": {}
    }
  }'

Error Handling

API errors return a JSON object with an error field and an appropriate HTTP status code.

{ "error": "Invalid or expired API key" }

Status	Meaning
400	Bad request, missing or invalid parameters
401	Missing or invalid API key
403	Insufficient permissions for this action
404	Resource not found
500	Internal server error