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

# Start a test with your own openings

> Requires the `experiments:write` scope.

Test one page (page) or a unit: site, a page type or a page group. Darwin adds the opening the page shows now as the current one, so your openings are compared with what visitors see today. One test per page or unit at a time. Starts at once unless launch is false.



## OpenAPI

````yaml /api-reference/openapi.json post /experiments
openapi: 3.1.0
info:
  title: Darwin API
  version: '2026-10-12'
  description: >-
    Read and act on your Darwin workspace: conversations, contacts, meetings,
    outcome forms and their requests, personal links and their greetings,
    analytics, knowledge, the agent, its chat buttons and its opening tests,
    with signed webhooks for what happens.


    Authenticate with a secret key from Integrations → API: `Authorization:
    Bearer dk_live_…`. Keys carry scopes; personal data needs `contacts:read`.

    Rate limits are per key per minute, the same on every plan: 600; heavy calls
    (exports, crawls, model work) have a smaller budget (30). Plans from before
    credits keep theirs. An Agency's client workspaces have the Agency's. Every
    response carries RateLimit-* headers.

    The chat API is on every plan: 2,500 conversations a month per workspace.

    Lists are cursor-paginated (`limit`, `starting_after`, `next_cursor`).
    Writes accept `Idempotency-Key`. Errors are RFC 9457 problem documents with
    a stable `code` and a `request_id`.
  contact:
    name: Darwin
    url: https://docs.meetdarwin.ai/api-reference/introduction
servers:
  - url: https://api.meetdarwin.ai/v1
security:
  - bearer: []
tags:
  - name: Workspace
  - name: Conversations
  - name: Contacts
  - name: Meetings
  - name: Outcomes
  - name: Personal links
  - name: Analytics
  - name: Events
  - name: Webhooks
  - name: Knowledge
  - name: Agent
  - name: Experiments
  - name: Privacy
  - name: Chat
paths:
  /experiments:
    post:
      tags:
        - Experiments
      summary: Start a test with your own openings
      description: >-
        Requires the `experiments:write` scope.


        Test one page (page) or a unit: site, a page type or a page group.
        Darwin adds the opening the page shows now as the current one, so your
        openings are compared with what visitors see today. One test per page or
        unit at a time. Starts at once unless launch is false.
      operationId: createExperiment
      parameters:
        - name: Idempotency-Key
          in: header
          required: false
          description: >-
            Retry safely: the first response is replayed for 24 hours (not for
            streamed answers).
          schema:
            type: string
            maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExperimentCreate'
      responses:
        '201':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Experiment'
        '400':
          description: Invalid request (`invalid_request`, `unsupported_version`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: >-
            Missing or invalid key (`authentication_required`,
            `invalid_api_key`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '402':
          description: >-
            The workspace must add a card before the API can be used
            (`payment_required`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: >-
            The key lacks the scope (`insufficient_scope`), the feature is off
            (`feature_disabled`), or the workspace's plan doesn't include it
            (`plan_required`, with `required_plan`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: No such object in this workspace (`not_found`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: >-
            Conflicts with the current state (`conflict`,
            `idempotency_key_in_use`), or the change would leave a live agent
            with no calendar or live form (`goal_required`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '422':
          description: Refused by a rule (`unprocessable`, `idempotency_key_reused`).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: >-
            Rate limited (`rate_limited`) or a monthly allowance used
            (`quota_exceeded`); see Retry-After.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  schemas:
    ExperimentCreate:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 120
          description: What your team calls the test.
        hypothesis:
          description: Why the new openings should do better.
          type: string
          maxLength: 500
        page:
          description: >-
            One page to test: a path such as /pricing, or an address on your
            website.
          type: string
          minLength: 1
          maxLength: 500
        unit:
          description: >-
            Instead of page: "site" for every page on the site's opening,
            "type:<home|pricing|comparison|integration|product|guide|proof|developer|company|other>"
            for a page type, or "group:<id>" for a page group.
          type: string
          pattern: >-
            ^(site|type:(home|pricing|comparison|integration|product|guide|proof|developer|company|other)|group:[a-f0-9-]{36})$
        openings:
          minItems: 1
          maxItems: 4
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                maxLength: 80
              hypothesis:
                type: string
                maxLength: 500
              headline:
                type: string
                minLength: 1
                maxLength: 120
                description: What the chat says first, up to 120 characters.
              buttons:
                minItems: 1
                maxItems: 4
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                      minLength: 1
                      maxLength: 120
                    message:
                      description: >-
                        What a click sends as the visitor; the label when left
                        out.
                      type: string
                      maxLength: 400
                  required:
                    - label
                description: >-
                  1 to 4 buttons under the message. Your locked buttons (Agent
                  Studio) are always added.
            required:
              - headline
              - buttons
            additionalProperties: false
          description: >-
            1 to 4 new openings. Each is tested against the opening the page
            shows now, which Darwin adds as the current one.
        launch:
          description: >-
            Default true: start showing the openings at once. false saves the
            test as a draft.
          type: boolean
      required:
        - name
        - openings
      additionalProperties: false
    Experiment:
      type: object
      properties:
        id:
          type: string
          pattern: ^exp_
          example: exp_4c1f0a2b9d3e7a10
        object:
          type: string
          const: experiment
        name:
          type: string
        status:
          type: string
          description: >-
            draft, ready, running, winner_found, applied, stopped, paused,
            failed or invalidated.
        internal_status:
          type: string
        unit:
          type: string
          description: >-
            What the test covers: page:<page>, type:<page type>, group:<id> or
            site.
        pages:
          type: array
          items:
            type: string
        metric:
          type: string
        hypothesis:
          type:
            - string
            - 'null'
        winner:
          type:
            - string
            - 'null'
        verdict:
          type:
            - string
            - 'null'
        created_at:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            - type: 'null'
        started_at:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            - type: 'null'
        ended_at:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            - type: 'null'
        applied_at:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            - type: 'null'
        variants:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              object:
                type: string
                const: variant
              name:
                type: string
              control:
                type: boolean
              headline:
                type: string
              buttons:
                type: array
                items:
                  type: object
                  properties:
                    label:
                      type: string
                    message:
                      type: string
                    locked:
                      type: boolean
                  required:
                    - label
                    - message
                    - locked
              angle:
                type:
                  - string
                  - 'null'
              created_at:
                anyOf:
                  - type: string
                    format: date-time
                    pattern: >-
                      ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  - type: 'null'
              results:
                anyOf:
                  - type: object
                    properties:
                      views:
                        type: number
                      stages:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          type: number
                      rate:
                        type:
                          - number
                          - 'null'
                      rate_low:
                        type:
                          - number
                          - 'null'
                      rate_high:
                        type:
                          - number
                          - 'null'
                      chance_beats_current:
                        type:
                          - number
                          - 'null'
                      lift:
                        type:
                          - number
                          - 'null'
                      computed_at:
                        anyOf:
                          - type: string
                            format: date-time
                            pattern: >-
                              ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                          - type: 'null'
                    required:
                      - views
                      - stages
                      - rate
                      - rate_low
                      - rate_high
                      - chance_beats_current
                      - lift
                      - computed_at
                  - type: 'null'
            required:
              - id
              - object
              - name
              - control
              - headline
              - buttons
              - angle
              - created_at
              - results
        result: {}
        live:
          description: >-
            On GET /experiments/{id}: the results worked out now, as the
            Experiments screen shows them. Reading it saves nothing.
          type: object
          properties:
            computed_at:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
            current:
              type: boolean
              description: >-
                False once the test has finished: the numbers are its last saved
                results.
            reason:
              description: One sentence on where the test stands.
              type:
                - string
                - 'null'
            estimate:
              description: Roughly how long until a clear answer at today's traffic.
              type:
                - string
                - 'null'
            views_per_day:
              type:
                - number
                - 'null'
            winner_needs:
              anyOf:
                - type: object
                  properties:
                    views:
                      type: number
                    current_views:
                      type: number
                    successes:
                      type: number
                    chance_to_beat:
                      type: number
                  required:
                    - views
                    - current_views
                    - successes
                    - chance_to_beat
                - type: 'null'
              description: >-
                What a new opening needs before it can be applied: views on it,
                views on the current one, visitors who reached booking, and its
                chance to beat the current one.
            metric:
              type: string
            openings:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                  control:
                    type: boolean
                  views:
                    type: number
                  conversations:
                    type: number
                  reached_booking:
                    type: number
                  meetings:
                    type: number
                  successes:
                    type: number
                    description: 'What the test scores: visitors who reached booking.'
                  rate:
                    type:
                      - number
                      - 'null'
                  chance_best:
                    type:
                      - number
                      - 'null'
                  chance_beats_current:
                    type:
                      - number
                      - 'null'
                  lift:
                    type:
                      - number
                      - 'null'
                  comparable:
                    type: boolean
                  evidence_note:
                    type:
                      - string
                      - 'null'
                  share:
                    description: Share of visitors it gets now.
                    type:
                      - number
                      - 'null'
                  worse_at:
                    type: array
                    items:
                      type: string
                    description: >-
                      "booked meetings" when it is probably booking fewer than
                      the current opening; it cannot be applied then.
                required:
                  - id
                  - name
                  - control
                  - views
                  - conversations
                  - reached_booking
                  - meetings
                  - successes
                  - rate
                  - chance_best
                  - chance_beats_current
                  - lift
                  - comparable
                  - evidence_note
                  - share
                  - worse_at
          required:
            - computed_at
            - current
            - reason
            - estimate
            - views_per_day
            - winner_needs
            - metric
            - openings
      required:
        - id
        - object
        - name
        - status
        - internal_status
        - unit
        - pages
        - metric
        - hypothesis
        - winner
        - verdict
        - created_at
        - started_at
        - ended_at
        - applied_at
        - variants
    Problem:
      type: object
      properties:
        type:
          type: string
          example: https://docs.meetdarwin.ai/api-reference/errors#insufficient_scope
        title:
          type: string
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        code:
          type: string
          example: insufficient_scope
        detail:
          type: string
        param:
          type: string
        required_plan:
          description: >-
            With `plan_required`: the plan that unlocks what was refused.
            Upgrade under Billing in the Darwin admin.
          type: string
          enum:
            - growth
            - agency
        feature:
          description: >-
            With `plan_required`: the plan feature that was refused, such as
            `fit_rules`.
          example: fit_rules
          type:
            - string
            - 'null'
        upgrade_url:
          description: >-
            With `plan_required`: the Billing page in the Darwin admin where an
            owner upgrades.
          type: string
        request_id:
          type: string
          example: req_8m2k4p0q1x7z9c3v5b6n
      required:
        - type
        - title
        - status
        - code
        - detail
        - request_id
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        A secret key (dk_live_…). Scopes: conversations:read, contacts:read,
        contacts:write, meetings:read, analytics:read, events:read,
        webhooks:write, knowledge:read, knowledge:write, agent:read,
        agent:write, experiments:read, experiments:write, privacy:write,
        chat:write.

````

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