Copier des endpoints entre projets

Cette compétence duplique un endpoint PostHog — une requête HogQL ou insight enregistrée exposée comme une route API appelable — soit vers un autre projet de la même organisation, soit sous un nouveau nom dans le même projet.

La seule chose à savoir d'abord

Il n'existe pas d'opération de copie d'endpoint côté serveur. Les feature flags ont feature-flags-copy-flags-create et les expériences ont experiment-copy-to-project ; les endpoints n'en ont aucune. Copier un endpoint signifie :

Lire la configuration source complète avec endpoint-get.
La recréer avec endpoint-create (dans le projet cible, ou sous un nouveau nom dans le même projet).

endpoint-get et endpoint-create opèrent uniquement sur le projet MCP actif — aucun ne prend d'id de projet. Donc une copie cross-projet exige que le projet actif soit basculé entre la lecture (source) et l'écriture (cible). Lisez d'abord la source, capturez la configuration, puis basculez vers la cible et créez. Si vous ne pouvez pas basculer entre les projets dans cette session, dites-le à l'utilisateur plutôt que de créer la copie dans le mauvais projet.

Quand utiliser cette compétence

« Copie cet endpoint vers un autre projet », « duplique cet endpoint », « clone l'endpoint »
« Promeut l'endpoint du staging vers la production » (projets-en-tant-qu'environnements)
« Fais une copie pour que je puisse itérer sans toucher à la version en direct » (duplication same-project sous un nouveau nom)
Dupliquer la requête, les variables et la configuration de fraîcheur des données d'un endpoint dans un workspace différent

Ce que cette compétence ne couvre pas

Copie cross-organisation. Les endpoints (et leurs requêtes) ne peuvent être recréés que dans les projets pour lesquels vous avez accès en édition ; il n'existe pas de chemin org-à-org.
Édition des versions d'un endpoint existant — voir managing-endpoint-versions.
Conception d'un nouvel endpoint à partir de zéro — voir creating-an-endpoint (cette compétence suppose que l'endpoint source existe déjà et est correctement configuré).
Copie en masse de tous les endpoints d'un projet. Copiez-en un à la fois ; bouclez endpoints-get-all → copie par endpoint si l'utilisateur veut vraiment tous les copier, et dites-lui que vous le faites.

Flux de travail

1. Résoudre l'endpoint source

Vous avez besoin du nom de l'endpoint et du projet source.

Si l'utilisateur a donné un nom, utilisez-le. S'il a donné une description floue, appelez endpoints-get-all dans le projet source et cherchez par nom/description.
Si l'utilisateur n'a pas dit dans quel projet l'endpoint se trouve, demandez — ne supposez pas que le projet MCP actif est la source. Copier à partir de la mauvaise source est le piège le plus courant.
Confirmez que le projet actif est la source (appelez project-get sans id pour voir le projet actif) avant de lire.

2. Lire la configuration source complète

Appelez endpoint-get avec le nom source. Capturez tout ce dont vous aurez besoin pour le recréer :

name
query (la définition complète de requête HogQL/insight — incluant toute variable déclarée / code_names)
description
data_freshness_seconds
is_materialized (état source — voir l'étape 5 pour savoir pourquoi vous ne la copiez généralement pas telle quelle)
tags

Présentez un court résumé à l'utilisateur avant de copier : ce que la requête retourne, ses variables, son réglage de fraîcheur, et si la source est matérialisée.

3. Résoudre la cible et vérifier une collision de nom

Cross-projet : confirmez que le projet cible appartient à la même organisation et que l'utilisateur y a accès en édition. La copie sera créée dans le projet actif au moment de l'appel endpoint-create, donc prévoyez de basculer le projet actif vers la cible entre l'étape 2 et l'étape 6.

Duplication same-project : le nouvel endpoint a besoin d'un nom différent — les noms sont uniques dans un projet et le chemin URL (/api/projects/{team_id}/endpoints/{name}/run) en dépend. Mettez-vous d'accord avec l'utilisateur sur un nouveau nom.

De toute façon, exécutez endpoints-get-all dans le projet cible et vérifiez si le nom prévu existe déjà. S'il existe, arrêtez-vous et demandez : créer sur un nom existant n'est pas une action sûre et silencieuse. Trouvez le bon nom d'avance — il est gravé dans l'URL de l'appelant et ne peut être renommé qu'avec difficulté plus tard.

4. Décider le nom dans la cible

Cross-projet, même objectif : conservez le même nom pour que le code de l'appelant soit portable sans modifications.
Same-project ou « copie pour itérer » : choisissez un nouveau nom clairement dérivé (ex. weekly_active_users_v2, weekly_active_users_staging). Snake_case, sûr pour les URL, commence par une lettre, max 128 caractères.

5. Choisir la matérialisation pour la copie (par défaut : OFF)

Défaut à is_materialized: false sur la copie, même quand la source est matérialisée. La raison est similaire au défaut sûr dans copying-flags-across-projects (désactivé au démarrage) : la matérialisation coûte en recalcul/stockage sur un calendrier, et un endpoint fraîchement copié n'a pas de trafic prouvé dans la cible encore. Publiez-le sans matérialisation, confirmez qu'il est réellement appelé, puis activez la matérialisation plus tard une fois l'usage justifié.

Substituez à is_materialized: true uniquement si l'utilisateur veut explicitement que la copie soit matérialisée dès le début (ex. une promotion de production similaire d'un endpoint à fort trafic). Notez les mises en garde de creating-an-endpoint : les requêtes avec ventilations de cohortes ou mode de comparaison, et les types d'insights autres que Trends/Lifecycle/Retention (ex. Funnels), ne sont pas matérialisables — endpoint-create les crée simplement sans matérialisation de toute façon.

Portez data_freshness_seconds sans modification à moins que l'utilisateur ne veuille une fraîcheur différente dans la cible (n'oubliez pas qu'elle double aussi comme cadence d'actualisation de matérialisation).

6. Créer la copie

Avec le projet cible actif, appelez endpoint-create avec :

name — de l'étape 4
query — la requête source capturée à l'étape 2, verbatim (cela porte les variables/code_names)
description — de la source (optionnellement notez qu'c'est une copie)
data_freshness_seconds — de la source à moins que l'utilisateur ne l'ait changé
is_materialized — de l'étape 5 (défaut false)
tags — de la source si l'utilisateur les veut ; supprimez les tags qui n'ont pas de sens dans le projet cible

7. Vérifier

Appelez endpoint-run sur le nouvel endpoint avec une charge variables représentative et confirmez que la forme de réponse correspond à la source. Pour une promotion cross-projet, vérifiez que les événements/propriétés sous-jacents que la requête référence existent réellement dans le projet cible — une requête valide en staging peut retourner vide ou erreur dans un projet avec une taxonomie différente. Si la copie est HogQL et les appelants s'appuient sur la pagination offset, notez que offset sur endpoint-run n'est supporté que pour les endpoints HogQL (pas pour les endpoints insight).

8. Rapporter

Dites à l'utilisateur : le nom et le projet du nouvel endpoint, son état de matérialisation, son réglage de fraîcheur, et le résultat de la vérification. Si vous avez basculé le projet actif pour faire la copie, dites quel projet est actif maintenant pour qu'il ne soit pas surpris au prochain appel.

Notes importantes

La requête est une copie, pas un lien. Comme la création d'un endpoint à partir d'un insight, l'endpoint cible possède sa propre copie de la requête. Les modifications ultérieures de l'endpoint source ne se propagent pas à la copie.
Les variables viennent à l'intérieur de query. Les déclarations de variables code_name HogQL et les variables de ventilation d'insight vivent à l'intérieur de la définition de requête, donc copier query verbatim les préserve. Double-vérifiez les variables de la copie dans la vérification.
Pas d'annulation. endpoint-create crée un nouvel endpoint (ou échoue si le nom est pris). Confirmez toujours le nom et le projet cible avec l'utilisateur avant de créer, surtout quand la cible est la production.
Accès. L'utilisateur a besoin d'un accès en édition sur l'équipe du projet cible ; sans cela endpoint-create sera rejeté.

Outils disponibles

endpoint-get — lire la configuration complète de l'endpoint source (requête, variables, fraîcheur, matérialisation, tags). Supporte ?version=N.
endpoint-create — créer la copie dans le projet actif. Champs : name, query, description, data_freshness_seconds, is_materialized, tags.
endpoints-get-all — lister les endpoints dans le projet actif ; utilisez pour résoudre un nom source flou et pour vérifier une collision de nom dans la cible.
endpoint-run — exécuter le nouvel endpoint pour vérifier la forme de réponse de la copie.
project-get — appelez sans id pour confirmer quel projet est actuellement actif avant de lire la source ou de créer la copie.

copying-endpoints-across-projects