---
title: "Connect one PostHog Cloud project"
method: POST
path: "/v1/projects/{project_id}/posthog-connection"
tags: ["PostHog Connection"]
---

# Connect one PostHog Cloud project

`POST /v1/projects/{project_id}/posthog-connection`

## Request

- Base URL: `https://api.agentry.sh`
- URL: `https://api.agentry.sh/v1/projects/{project_id}/posthog-connection`
- Auth: HTTP bearer

Owner-only. connect starts a short-lived PKCE browser handoff for the explicit PostHog Cloud region. PostHog's project-scoped consent selects the one environment bound to this connection. The read-only OAuth token remains encrypted in the hosted control plane.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `intent` 'connect', required
  - `region` 'us' | 'eu', required
  - `posthog_project_id` integer: Optional assertion for a caller that already knows the intended PostHog environment id. OAuth consent must still bind exactly this one provider-scoped environment.

## Response `200`

OK

- object
  - `connection` object, required
    - `status` 'detached' | 'active' | 'reauth_required', required
    - `region` 'us' | 'eu', nullable, required
    - `posthog_host` string, nullable, required
    - `posthog_project_id` integer, nullable, required
    - `organization_id` string, nullable, required
    - `scopes` string[], required
    - `connected_at` integer, nullable, required
    - `last_verified_at` integer, nullable, required
    - `capabilities` object, nullable, required
    - `next_action` string, nullable, required
  - `authorization_url` string
  - `poll_interval_seconds` integer
  - `expires_at` integer

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/agentry/apis/agentry-api.md) · [All operations](https://skmtc.dev/agentry/apis/agentry-api/llms.txt) · [OpenAPI document](https://skmtc.dev/agentry/apis/agentry-api/revisions/abdecddf009f?raw)