Integrations

GET    /v1/cofounder/integrations
PUT    /v1/cofounder/integrations/:provider
DELETE /v1/cofounder/integrations/:provider
GET    /v1/cofounder/oauth/:provider/start
GET    /v1/cofounder/oauth/:provider/callback     ← public (state-authenticated)

Each integration row holds credentials + config for one delivery channel. Two ways to populate it:

OAuth (Slack, Linear, GitHub, Notion) — one click, captures workspace info automatically. See OAuth flow.
PUT (all providers) — supply credentials directly. Used by the manual key paths and by Webhook/ASC-write which don’t have an OAuth flow.

Providers

Provider	Required credentials	Config
`slack`	`webhookUrl` OR `botToken`+`channelId`	`defaultChannel`
`linear`	`apiKey`	`teamId`, `projectId`
`github`	`token`	`owner`, `repo`
`webhook`	`url`	`secret`
`notion`	`token`	`databaseId`
`asc_write`	(none — uses existing ASC connection)	(none)

GET — list

curl https://api.appeeky.com/v1/cofounder/integrations -H "X-API-Key: $KEY"

Returns metadata only — credentials are never exposed:

{
  "data": {
    "integrations": [
      {
        "id": "uuid",
        "provider": "slack",
        "enabled": true,
        "config": { "defaultChannel": "#app-cofounder" },
        "last_used_at": "2026-05-02T08:00:13Z",
        "last_error": null,
        "created_at": "...",
        "updated_at": "...",
        // OAuth-managed integrations include extra metadata:
        "auth_method": "oauth",                    // "oauth" | "manual"
        "oauth_account_label": "Acme Workspace",   // shown in dashboards
        "oauth_external_id": "T012ABC",            // workspace/team/repo id
        "oauth_scope": "chat:write,channels:read,...",
        "oauth_expires_at": null                   // null = long-lived
      }
    ]
  }
}

PUT — upsert

curl -X PUT https://api.appeeky.com/v1/cofounder/integrations/slack \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "credentials": { "webhookUrl": "https://hooks.slack.com/services/..." },
    "integrationConfig": { "defaultChannel": "#app-cofounder" },
    "enabled": true
  }'

Body:

Field	Required	Description
`credentials`	Yes (per provider schema)	Object with credentials
`integrationConfig`	No	Provider-specific config
`enabled`	No, default `true`	Disable without deleting

Every PUT triggers a connectivity test against the provider before saving. If the test fails, the request returns 422 INTEGRATION_TEST_FAILED and nothing is persisted.

DELETE

curl -X DELETE https://api.appeeky.com/v1/cofounder/integrations/slack \
  -H "X-API-Key: $KEY"

Removes the row entirely. To temporarily disable, use PUT with enabled: false instead.

Enabling integrations on the agent

Setting credentials is necessary but not sufficient. The integration is only used by the agent if it’s listed in preferences.enabledIntegrations:

PUT /v1/cofounder/preferences
{ "enabledIntegrations": ["slack", "linear", "notion"] }

This two-step (credentials + enable) lets you pre-provision integrations without immediately turning them on.

Errors

400 INVALID_PROVIDER — unknown provider
400 MISSING_CREDENTIAL — required credential field absent
422 INTEGRATION_TEST_FAILED — credentials are wrong or endpoint is unreachable

OAuth flow (Slack, Linear, GitHub, Notion)

GET /v1/cofounder/oauth/:provider/start?return_to=<url>
   → 200 { authorizeUrl, state, expiresAt }   ← user opens authorizeUrl

GET /v1/cofounder/oauth/:provider/callback?code=...&state=...
   → 302 redirect to return_to with one of:
        ?cofounder_oauth=success&provider=…&account=…
        ?cofounder_oauth=denied&provider=…&error=…
        ?cofounder_oauth=error&provider=…&error=…

The return_to URL is validated against an allowlist of host prefixes (open-redirect guard). Defaults: https://app.appeeky.com, https://api.appeeky.com, http://localhost. Configure via COFOUNDER_OAUTH_RETURN_TO_ALLOWLIST. After a successful callback the row in cofounder_integrations is upserted with:

auth_method = 'oauth'
oauth_account_label, oauth_external_id, oauth_scope populated from the provider
encrypted_credentials.accessToken (and provider-specific aliases like botToken for Slack)

Re-running the OAuth flow for the same provider overwrites the row — useful when switching workspaces. See OAuth (recommended) for the full flow + frontend code example.

Per-provider details

See the integration-specific docs:

Get Started

Concepts

Knowledge Base

Capabilities

API Reference

Integrations

Providers

GET — list

PUT — upsert

DELETE

Enabling integrations on the agent

Errors

OAuth flow (Slack, Linear, GitHub, Notion)

Per-provider details

​Providers

​GET — list

​PUT — upsert

​DELETE

​Enabling integrations on the agent

​Errors

​OAuth flow (Slack, Linear, GitHub, Notion)

​Per-provider details

Providers

GET — list

PUT — upsert

DELETE

Enabling integrations on the agent

Errors

OAuth flow (Slack, Linear, GitHub, Notion)

Per-provider details