PostHog API — experiments

naftiko: 1.0.0-alpha2
info:
  label: PostHog API — experiments
  description: 'PostHog API — experiments. 44 operations. Lead operation: experiments. Self-contained Naftiko capability covering
    one Posthog business surface.'
  tags:
  - Posthog
  - experiments
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    POSTHOG_API_KEY: POSTHOG_API_KEY
capability:
  consumes:
  - type: http
    namespace: posthog-experiments
    baseUri: ''
    description: PostHog API — experiments business capability. Self-contained, no shared references.
    resources:
    - name: api-projects-project_id-experiments
      path: /api/projects/{project_id}/experiments/
      operations:
      - name: experimentslist
        method: GET
        description: List experiments for the current project. Supports filtering by status and archival state.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: archived
          in: query
          type: boolean
          description: Filter by archived state. Defaults to non-archived experiments only.
        - name: created_by_id
          in: query
          type: integer
          description: Filter to experiments created by the given user ID.
        - name: feature_flag_id
          in: query
          type: integer
          description: Filter to experiments linked to the given feature flag ID.
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: order
          in: query
          type: string
          description: Field to order by. Prefix with '-' for descending. Allowlisted fields include name, created_at, updated_at,
            start_date, end_date, duration, and status.
        - name: search
          in: query
          type: string
          description: Free-text search applied to the experiment name (case-insensitive).
        - name: status
          in: query
          type: string
          description: 'Filter by experiment status. "running" and "paused" are mutually exclusive: "running" returns launched
            experiments with an active feature flag, "paused" returns'
      - name: experimentslist
        method: GET
        description: List experiments for the current project. Supports filtering by status and archival state.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: archived
          in: query
          type: boolean
          description: Filter by archived state. Defaults to non-archived experiments only.
        - name: created_by_id
          in: query
          type: integer
          description: Filter to experiments created by the given user ID.
        - name: feature_flag_id
          in: query
          type: integer
          description: Filter to experiments linked to the given feature flag ID.
        - name: limit
          in: query
          type: integer
          description: Number of results to return per page.
        - name: offset
          in: query
          type: integer
          description: The initial index from which to return the results.
        - name: order
          in: query
          type: string
          description: Field to order by. Prefix with '-' for descending. Allowlisted fields include name, created_at, updated_at,
            start_date, end_date, duration, and status.
        - name: search
          in: query
          type: string
          description: Free-text search applied to the experiment name (case-insensitive).
        - name: status
          in: query
          type: string
          description: 'Filter by experiment status. "running" and "paused" are mutually exclusive: "running" returns launched
            experiments with an active feature flag, "paused" returns'
      - name: experimentscreate
        method: POST
        description: Create a new experiment in draft status with optional metrics.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentscreate
        method: POST
        description: Create a new experiment in draft status with optional metrics.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-eligible_feature_flags
      path: /api/projects/{project_id}/experiments/eligible_feature_flags/
      operations:
      - name: experimentseligiblefeatureflagsretrieve
        method: GET
        description: Returns a paginated list of feature flags eligible for use in experiments.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: experimentseligiblefeatureflagsretrieve
        method: GET
        description: Returns a paginated list of feature flags eligible for use in experiments.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-projects-project_id-experiments-requires_flag_implementation
      path: /api/projects/{project_id}/experiments/requires_flag_implementation/
      operations:
      - name: experimentsrequiresflagimplementationretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: experimentsrequiresflagimplementationretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-projects-project_id-experiments-stats
      path: /api/projects/{project_id}/experiments/stats/
      operations:
      - name: experimentsstatsretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
      - name: experimentsstatsretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: api-projects-project_id-experiments-id
      path: /api/projects/{project_id}/experiments/{id}/
      operations:
      - name: experimentsretrieve
        method: GET
        description: Retrieve a single experiment by ID, including its current status, metrics, feature flag, and results
          metadata.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsretrieve
        method: GET
        description: Retrieve a single experiment by ID, including its current status, metrics, feature flag, and results
          metadata.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsupdate
        method: PUT
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentsupdate
        method: PUT
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentspartialupdate
        method: PATCH
        description: Update an experiment. Use this to modify experiment properties such as name, description, metrics, variants,
          and configuration. Metrics can be added, changed and removed at any time.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: experimentspartialupdate
        method: PATCH
        description: Update an experiment. Use this to modify experiment properties such as name, description, metrics, variants,
          and configuration. Metrics can be added, changed and removed at any time.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: experimentsdestroy
        method: DELETE
        description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsdestroy
        method: DELETE
        description: Hard delete of this model is not allowed. Use a patch API call to set "deleted" to true
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-archive
      path: /api/projects/{project_id}/experiments/{id}/archive/
      operations:
      - name: experimentsarchivecreate
        method: POST
        description: Archive an ended experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsarchivecreate
        method: POST
        description: Archive an ended experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-copy_to_project
      path: /api/projects/{project_id}/experiments/{id}/copy_to_project/
      operations:
      - name: experimentscopytoprojectcreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentscopytoprojectcreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-id-create_exposure_cohort_for_experiment
      path: /api/projects/{project_id}/experiments/{id}/create_exposure_cohort_for_experiment/
      operations:
      - name: experimentscreateexposurecohortforexperimentcreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentscreateexposurecohortforexperimentcreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-id-duplicate
      path: /api/projects/{project_id}/experiments/{id}/duplicate/
      operations:
      - name: experimentsduplicatecreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentsduplicatecreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-id-end
      path: /api/projects/{project_id}/experiments/{id}/end/
      operations:
      - name: experimentsendcreate
        method: POST
        description: End a running experiment without shipping a variant.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: experimentsendcreate
        method: POST
        description: End a running experiment without shipping a variant.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: api-projects-project_id-experiments-id-launch
      path: /api/projects/{project_id}/experiments/{id}/launch/
      operations:
      - name: experimentslaunchcreate
        method: POST
        description: Launch a draft experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentslaunchcreate
        method: POST
        description: Launch a draft experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-pause
      path: /api/projects/{project_id}/experiments/{id}/pause/
      operations:
      - name: experimentspausecreate
        method: POST
        description: Pause a running experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentspausecreate
        method: POST
        description: Pause a running experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-recalculate_timeseries
      path: /api/projects/{project_id}/experiments/{id}/recalculate_timeseries/
      operations:
      - name: experimentsrecalculatetimeseriescreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentsrecalculatetimeseriescreate
        method: POST
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-id-reset
      path: /api/projects/{project_id}/experiments/{id}/reset/
      operations:
      - name: experimentsresetcreate
        method: POST
        description: Reset an experiment back to draft state.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsresetcreate
        method: POST
        description: Reset an experiment back to draft state.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-resume
      path: /api/projects/{project_id}/experiments/{id}/resume/
      operations:
      - name: experimentsresumecreate
        method: POST
        description: Resume a paused experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsresumecreate
        method: POST
        description: Resume a paused experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    - name: api-projects-project_id-experiments-id-ship_variant
      path: /api/projects/{project_id}/experiments/{id}/ship_variant/
      operations:
      - name: experimentsshipvariantcreate
        method: POST
        description: Ship a variant to 100% of users and (optionally) end the experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: experimentsshipvariantcreate
        method: POST
        description: Ship a variant to 100% of users and (optionally) end the experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: api-projects-project_id-experiments-id-timeseries_results
      path: /api/projects/{project_id}/experiments/{id}/timeseries_results/
      operations:
      - name: experimentstimeseriesresultsretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fingerprint
          in: query
          type: string
          description: Fingerprint of the metric configuration. Available alongside metric_uuid on each metric in the experiment's
            metrics array.
          required: true
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: metric_uuid
          in: query
          type: string
          description: UUID of the metric to fetch timeseries for. Available on each metric in the experiment's metrics array.
          required: true
      - name: experimentstimeseriesresultsretrieve
        method: GET
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: fingerprint
          in: query
          type: string
          description: Fingerprint of the metric configuration. Available alongside metric_uuid on each metric in the experiment's
            metrics array.
          required: true
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
        - name: metric_uuid
          in: query
          type: string
          description: UUID of the metric to fetch timeseries for. Available on each metric in the experiment's metrics array.
          required: true
    - name: api-projects-project_id-experiments-id-unarchive
      path: /api/projects/{project_id}/experiments/{id}/unarchive/
      operations:
      - name: experimentsunarchivecreate
        method: POST
        description: Unarchive an archived experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
      - name: experimentsunarchivecreate
        method: POST
        description: Unarchive an archived experiment.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: A unique integer value identifying this experiment.
          required: true
    authentication:
      type: bearer
      token: '{{env.POSTHOG_API_KEY}}'
  exposes:
  - type: rest
    namespace: posthog-experiments-rest
    port: 8080
    description: REST adapter for PostHog API — experiments. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/api/projects/{project-id}/experiments
      name: api-projects-project-id-experiments
      description: REST surface for api-projects-project_id-experiments.
      operations:
      - method: GET
        name: experimentslist
        description: List experiments for the current project. Supports filtering by status and archival state.
        call: posthog-experiments.experimentslist
        with:
          archived: rest.archived
          created_by_id: rest.created_by_id
          feature_flag_id: rest.feature_flag_id
          limit: rest.limit
          offset: rest.offset
          order: rest.order
          search: rest.search
          status: rest.status
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: experimentslist
        description: List experiments for the current project. Supports filtering by status and archival state.
        call: posthog-experiments.experimentslist
        with:
          archived: rest.archived
          created_by_id: rest.created_by_id
          feature_flag_id: rest.feature_flag_id
          limit: rest.limit
          offset: rest.offset
          order: rest.order
          search: rest.search
          status: rest.status
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: experimentscreate
        description: Create a new experiment in draft status with optional metrics.
        call: posthog-experiments.experimentscreate
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: experimentscreate
        description: Create a new experiment in draft status with optional metrics.
        call: posthog-experiments.experimentscreate
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/experiments/eligible-feature-flags
      name: api-projects-project-id-experiments-eligible-feature-flags
      description: REST surface for api-projects-project_id-experiments-eligible_feature_flags.
      operations:
      - method: GET
        name: experimentseligiblefeatureflagsretrieve
        description: Returns a paginated list of feature flags eligible for use in experiments.
        call: posthog-experiments.experimentseligiblefeatureflagsretrieve
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: experimentseligiblefeatureflagsretrieve
        description: Returns a paginated list of feature flags eligible for use in experiments.
        call: posthog-experiments.experimentseligiblefeatureflagsretrieve
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/experiments/requires-flag-implementation
      name: api-projects-project-id-experiments-requires-flag-implementation
      description: REST surface for api-projects-project_id-experiments-requires_flag_implementation.
      operations:
      - method: GET
        name: experimentsrequiresflagimplementationretrieve
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        call: posthog-experiments.experimentsrequiresflagimplementationretrieve
        outputParameters:
        - type: object
          mapping: $.
      - method: GET
        name: experimentsrequiresflagimplementationretrieve
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        call: posthog-experiments.experimentsrequiresflagimplementationretrieve
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/api/projects/{project-id}/experiments/stats
      name: api-projects-project-id-experiments-stats
      description: REST surface for api-projects-project_id-experiments-stats.
      operations:
      - method: GET
        name: experimentsstatsretrieve
        description: Mixin for ViewSets to handle ApprovalRequired exceptions from decorated serializers.
        call: posthog-experiments.experimentsstatsretrieve
        outputParameters:
        - type: object
          mappin

# --- truncated at 32 KB (64 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/posthog/refs/heads/main/capabilities/posthog-experiments.yaml