> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Co-founder API

> REST endpoints and MCP tools for running briefings, asking questions and reviewing actions from your own tools.

Everything in the Co-founder dashboard is available over the API, so you can trigger briefings, ask questions and approve actions from your own scripts, bots or agents.

> [!NOTE]
>
> Authenticate with your API key in the `X-API-Key` header. See [Authentication](https://docs.appeeky.com/docs/authentication.md). Co-founder endpoints use **0 API credits**. Briefings themselves need the **Startup plan** or higher.

All endpoints live under `https://api.appeeky.com/v1` and return `{ "data": ... }`.

***

## Setup and briefings

| Method | Endpoint | Description |
| - | - | - |
| POST | `/cofounder/onboard` | Set up an app with defaults: `{ appId, country?, platform? }` |
| GET | `/cofounder/preferences` | Your current settings |
| PUT | `/cofounder/preferences` | Update settings (any subset of fields, see below) |
| POST | `/cofounder/runs` | Start a briefing: `{ appId, country?, analysisDepth? }` |
| GET | `/cofounder/runs` | Recent runs and their status |
| POST | `/cofounder/runs/portfolio` | Start a portfolio sweep across your live apps |
| GET | `/cofounder/reports` | Briefings, newest first (`?appId=&limit=&offset=`, limit max 100) |
| GET | `/cofounder/reports/:reportId` | One full briefing |

### Start a briefing

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/cofounder/runs \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "6479581124", "country": "us" }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "triggered": true, "triggerRunId": "run_abc123" } }
```

The briefing runs in the background and takes a few minutes. Poll `GET /cofounder/runs?limit=1`, then read it with `GET /cofounder/reports?limit=1`. The `briefingMarkdown` field of a report holds the briefing text.

| Error | When |
| - | - |
| `402 SUBSCRIPTION_REQUIRED` | Your plan doesn't include the Co-founder |
| `422 NOT_CONFIGURED` | Call `/cofounder/onboard` or `PUT /cofounder/preferences` first |
| `429 RUN_COOLDOWN` | This app already had a run in the last 24 hours |

### Preference fields

| Field | Values |
| - | - |
| `enabled` | `true` / `false` (master switch) |
| `timezone` | IANA name, e.g. `Europe/Berlin` |
| `scheduleCrons` | 5-field cron expressions in your timezone, e.g. `["0 8 * * 1-5"]` |
| `agentMode` | `read`, `write` |
| `autopilotLevel` | `0`–`4` |
| `autoApproveTypes` | Action types that skip approval, e.g. `["asc_review_reply"]` |
| `personaPreset` | `default`, `cfo`, `growth`, `pm`, `aso_specialist` |
| `personaPrompt` | Your own instructions on top of the preset |
| `personalityProfile` | `balanced`, `blunt_advisor`, `friendly_mentor`, `indie_hacker`, `pg_analytical`, `yc_partner` |
| `briefingLanguage` | `auto`, `en`, `tr`, `es`, `de`, `fr`, `pt`, `ja` |
| `briefingLength` | `short`, `standard`, `detailed` |
| `briefingExcludeTopics` | `["revenue"]` to leave revenue out |
| `analysisDepth` | `quick`, `standard`, `deep` |
| `proactiveMode` | `off`, `mixed`, `event_only` |
| `alertsEnabled`, `alertsMinSeverity`, `alertsMaxPerDay`, `alertsQuietStart`, `alertsQuietEnd` | Alert settings. Quiet hours are 0–23, set together, or `null` for none. |
| `publicDiaryEnabled` | `true` / `false` |

***

## Ask

| Method | Endpoint | Description |
| - | - | - |
| POST | `/cofounder/ask` | Ask a question: `{ appId, question, reportId?, scope? }` |
| GET | `/cofounder/ask` | Past questions and answers (`?appId=&limit=`) |

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.appeeky.com/v1/cofounder/ask \
  -H "X-API-Key: $APPEEKY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "appId": "6479581124", "question": "Why did conversion drop this week?" }'
```

The response has `answer` (Markdown) and `proposedActions`: changes the answer queued for your approval. Set `scope` to `portfolio` to ask across all your apps.

***

## Actions

| Method | Endpoint | Description |
| - | - | - |
| GET | `/cofounder/actions` | Actions (`?appId=&status=&reportId=&limit=`, limit max 100) |
| GET | `/cofounder/actions/stats` | Counts by status |
| PATCH | `/cofounder/actions/:actionId/review` | `{ "decision": "approved" }` or `"rejected"` |
| POST | `/cofounder/actions/bulk-review` | `{ actionIds, decision }`, up to 50 at once |
| POST | `/cofounder/actions/:actionId/restore` | Move a rejected action back to pending |

`status` is one of `proposed`, `approved`, `applied`, `rejected`, `superseded`. Approving runs the change right away through the connected integration.

***

## Always-on

| Method | Endpoint | Description |
| - | - | - |
| GET | `/cofounder/routines` | Your routines, templates and limits |
| POST | `/cofounder/routines` | `{ templateKey }` or `{ title, instruction, cron \| runAt, appId?, notify? }` |
| PATCH | `/cofounder/routines/:id` | Edit, or `{ "status": "paused" }` / `"active"` |
| DELETE | `/cofounder/routines/:id` | Delete a routine |
| POST | `/cofounder/routines/:id/run` | Run once now |
| GET | `/cofounder/routines/:id/runs` | Run history |
| GET | `/cofounder/alerts` | Recent alerts |
| GET | `/cofounder/signals` | Open signals (`?appId=&status=`) |
| PATCH | `/cofounder/signals/:signalId/dismiss` | Dismiss a signal |

`cron` is a 5-field cron in your timezone (`0 9 * * 1` is Mondays at 09:00). `runAt` is a local date-time for a one-off run (`2026-11-20T09:00`).

### Custom webhook

Send events from your own systems, such as a support backlog spike. Each one becomes a signal that can trigger an [alert](https://docs.appeeky.com/docs/cofounder/always-on.md#alerts).

| Method | Endpoint | Description |
| - | - | - |
| GET | `/cofounder/webhooks/custom` | Your webhook URL and signing secret |
| POST | `/cofounder/webhooks/custom` | Rotate the URL and secret |

Sign the raw JSON body with HMAC-SHA256 and your secret:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
BODY='{"summary":"Support backlog spiked to 40 open tickets","severity":"high"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Appeeky-Signature: sha256=$SIG" \
  -d "$BODY"
```

`summary` is required. Optional: `severity` (`info`, `low`, `medium`, `high`, `critical`; default `medium`), `appId`, `metricPath`, `fingerprint`, `magnitude`.

***

## Why analysis

| Method | Endpoint | Description |
| - | - | - |
| POST | `/cofounder/why` | `{ appId, metricPath, timeRange: { from, to }, userQuestion? }` |
| GET | `/cofounder/why/reports` | Past analyses |
| GET | `/cofounder/why/reports/:id` | One analysis with ranked causes |

`metricPath` is `asc.downloads` or `asc.revenue`.

***

## Goals, commitments and finance

| Method | Endpoint | Description |
| - | - | - |
| GET / POST | `/cofounder/goals` | List or create: `{ scope, appId?, label, metric, targetValue, baselineValue?, deadline }` |
| PATCH / DELETE | `/cofounder/goals/:id` | Update or remove a goal |
| GET / POST | `/cofounder/commitments` | List or add: `{ appId, body, dueAt? }` (`dueAt` as `YYYY-MM-DD`) |
| PATCH / DELETE | `/cofounder/commitments/:id` | Update, complete or remove |
| GET / PATCH | `/cofounder/finance` | Cash on hand, costs, unit economics |
| POST | `/cofounder/costs` | Add a monthly cost |
| PATCH / DELETE | `/cofounder/costs/:id` | Update or remove a cost |
| GET | `/cofounder/decision-log` | Proposed actions, decisions and outcomes (`?appId=&lookbackDays=`) |
| GET | `/cofounder/scorecard` | Applied, rejected and measured results (`?appId=&days=`) |

***

## Knowledge and memory

| Method | Endpoint | Description |
| - | - | - |
| GET / PATCH | `/cofounder/company` | Company profile |
| POST | `/cofounder/company/confirm` | Confirm a drafted profile |
| PATCH | `/cofounder/company/apps/:appId` | Product profile for one app |
| GET | `/cofounder/documents` | List knowledge base documents |
| GET | `/cofounder/documents/search` | Search documents |
| GET | `/cofounder/documents/content` | Read a document |
| PUT | `/cofounder/documents` | Create or replace: `{ path, content, visibility? }` |
| DELETE | `/cofounder/documents` | Delete a document |
| GET | `/cofounder/knowledge-patches` | Edits the Co-founder suggested |
| POST | `/cofounder/knowledge-patches/:id/apply` | Apply a suggestion |
| POST | `/cofounder/knowledge-patches/:id/reject` | Reject a suggestion |
| GET / POST | `/cofounder/memory/facts` | List or add memory facts |
| DELETE | `/cofounder/memory/facts/:id` | Remove a fact |
| POST | `/cofounder/memory/ingest` | Turn a URL or text into candidate facts: `{ kind: "url" \| "text", url?, text?, title?, appId? }` |
| GET | `/cofounder/memory/export` | Export memory (`?format=json` or `markdown`) |
| POST | `/cofounder/memory/import` | Import a JSON export |

***

## Integrations

| Method | Endpoint | Description |
| - | - | - |
| GET | `/cofounder/integrations` | Connected integrations |
| PUT | `/cofounder/integrations/:provider` | Connect with credentials, e.g. a Slack incoming webhook |
| DELETE | `/cofounder/integrations/:provider` | Disconnect |

Slack, Linear, GitHub and Notion are easiest to connect from **App Co-founder → Integrations**, which handles the sign-in for you.

***

## MCP tools

The [Appeeky MCP server](https://docs.appeeky.com/docs/mcp.md) includes Co-founder tools, so an AI assistant can work your action queue and knowledge base. They use 0 API credits.

| Tool | Description |
| - | - |
| `cofounder_actions_stats` | Counts by status, including failed actions |
| `cofounder_actions_list` | Your pending actions (`status=proposed` by default) |
| `cofounder_actions_review` | Approve (runs it now) or reject an action |
| `workspace_search`, `workspace_list`, `workspace_read` | Search, list or read knowledge base documents |
| `workspace_write`, `workspace_delete` | Create, replace or delete a document |

> [!WARNING]
>
> `cofounder_actions_review` with `decision=approved` applies the change immediately. Let your assistant approve only when you've asked it to.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.