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

# Set the initial funnel stage



## OpenAPI

````yaml /api-reference/openapi.json post /v1/funnel-stages/{stage_id}/set-initial
openapi: 3.1.0
info:
  title: Ciarem API
  version: v1
  description: >
    The Ciarem public API. Authenticate every request with an org-bound API key

    (created in Settings → API keys; Scale plan or free trial) sent as a bearer
    token:

    `Authorization: Bearer oak_…`.


    Compatibility: this is an early, fast-moving API. Most changes are

    additive (new endpoints, new optional params, new response fields, new

    enum/string values) — clients must tolerate unknown fields and unknown

    string values. Every contract change is listed in the changelog at

    help.ciarem.ai.
servers:
  - url: https://api.ciarem.ai
security:
  - apiKey: []
tags:
  - name: Account
    description: The organization behind the API key.
  - name: Contacts
    description: People in the CRM — create, read, update, delete.
  - name: CRM
    description: 'The shape of the CRM: custom properties and funnel stages.'
  - name: Conversations
    description: Read the message history of a conversation.
  - name: WhatsApp numbers
    description: The connected numbers a send can go out from.
  - name: WhatsApp templates
    description: Message templates, and what each one needs filled before it can be sent.
  - name: Broadcasts
    description: Send a template, and follow what happened to every recipient.
paths:
  /v1/funnel-stages/{stage_id}/set-initial:
    post:
      tags:
        - CRM
      summary: Set the initial funnel stage
      operationId: set_initial_endpoint_v1_funnel_stages__stage_id__set_initial_post
      parameters:
        - name: stage_id
          in: path
          required: true
          schema:
            type: string
            title: Stage Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicFunnelStageListResponse'
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
        '401':
          description: >-
            No usable credential: `missing_bearer_token` (no `Authorization:
            Bearer`) or `invalid_api_key` (unknown or revoked key).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
        '403':
          description: >-
            The credential is real but not allowed here: `api_key_required` (a
            session token rather than an `oak_` key), `scale_plan_required` (a
            live plan below Scale — upgrade to Scale), `trial_expired` (the free
            trial ended without a card — subscribe to keep the key working), or
            `subscription_required` (the subscription is canceled or suspended).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStageError'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicStageError'
          description: Unprocessable Content
        '429':
          description: >-
            Over the organization's request budget (`rate_limited`).
            `Retry-After` says how many seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicError'
          headers:
            Retry-After:
              description: Seconds until the window resets.
              schema:
                type: integer
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
components:
  schemas:
    PublicFunnelStageListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/PublicFunnelStage'
          type: array
          title: Items
      type: object
      required:
        - items
      title: PublicFunnelStageListResponse
    PublicError:
      description: An error whose `detail` is a stable, machine-readable code.
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: PublicError
      type: object
    PublicStageError:
      properties:
        detail:
          $ref: '#/components/schemas/PublicStageErrorDetail'
      type: object
      required:
        - detail
      title: PublicStageError
    PublicFunnelStage:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        key:
          type: string
          title: Key
        description:
          type: string
          title: Description
        order_idx:
          type: integer
          title: Order Idx
        is_initial:
          type: boolean
          title: Is Initial
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - name
        - key
        - description
        - order_idx
        - is_initial
        - created_at
        - updated_at
      title: PublicFunnelStage
    PublicStageErrorDetail:
      properties:
        code:
          type: string
          title: Code
        missing_ids:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Missing Ids
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
        stages:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Stages
      type: object
      required:
        - code
      title: PublicStageErrorDetail
      description: Machine-readable stage-operation error (the `detail` of a 409/422).
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per window, shared across the org's keys.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: When the window resets, as a Unix timestamp in seconds.
      schema:
        type: integer
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An org API key: `Authorization: Bearer oak_…`.'

````