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

# Create a Feed search and start its first run

> Create a Feed search and start its first run

**CLI:**

```bash theme={null}
puffle feed create --title <title> --intent <intent> --source-plan <source-plan>
puffle feed create --title <title> --intent <intent> --source-plan <source-plan> --description <description> --origin <origin> --creation-prompt <creation-prompt> --details <details>
```

## Overview

Create a Feed search and start its first run

This page documents `post /api/feed`. Use the request and response sections on this page for accepted parameters, payload fields, response fields, and authentication behavior.

## AI agent notes

* Confirm the operation matches the user's intent before calling it.
* For write operations, confirm the user intends to change state.
* Surface validation, permission, and not-found errors instead of retrying unchanged.


## OpenAPI

````yaml post /api/feed
openapi: 3.0.3
info:
  title: Puffle API
  version: 1.0.0
  description: >-
    HTTP API for the Puffle GTM platform - Feed and Lead Finder search
    preparation, campaign-backed Outbound execution, Puffle Agent runs, sender
    management, and Unibox reply workflows. Designed for operation by both
    humans and autonomous AI agents. Agents should start at the [Agent
    Playbook](/guides/agent-playbook) which prescribes a workspace-context check
    (`GET /api/context`) and core user journeys with exact call ordering.
  contact:
    name: Puffle Support
    url: https://puffle.ai
servers:
  - url: https://app.puffle.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Campaigns
    description: >-
      Campaign-backed Outbound execution. These endpoints manage draft,
      launching, active, paused, and completed Outbound runs with sequence
      nodes, contacts, and sender accounts.
  - name: Accounts
    description: Signed-in user account, settings, and workspace context endpoints.
  - name: Billing
    description: Billing customer portal and account billing endpoints.
  - name: Senders
    description: >-
      Connected sender accounts, email inboxes, sending domains, DNS
      verification, warmup, and sender capacity.
  - name: Socials
    description: >-
      Read connected LinkedIn and X accounts, review current and archived posts,
      and reconcile publication status. Creating, editing, scheduling,
      publishing, OAuth connection, analytics, and mentions remain
      dashboard-managed workflows and are not part of the public Bearer-token
      API.
paths:
  /api/feed:
    post:
      tags:
        - Feed
      summary: Create a Feed search and start its first run
      description: Create a Feed search and start its first run
      operationId: feed.create
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 1
                  maxLength: 180
                description:
                  type: string
                  maxLength: 500
                intent:
                  type: string
                  minLength: 1
                origin:
                  default: prompt
                  type: string
                  enum:
                    - prompt
                    - planner
                creationPrompt:
                  type: string
                  minLength: 1
                sourcePlan:
                  type: object
                  properties:
                    sourceId:
                      type: string
                      enum:
                        - linkedin_posts
                        - linkedin_people
                        - news
                        - reddit
                        - hacker_news
                        - x_twitter
                        - hiring_cafe
                        - github
                    query:
                      minItems: 1
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 240
                    reason:
                      type: string
                      minLength: 1
                      maxLength: 240
                    resultTarget:
                      oneOf:
                        - type: object
                          properties:
                            mode:
                              type: string
                              enum:
                                - count
                            count:
                              type: integer
                              exclusiveMinimum: true
                              maximum: 9007199254740991
                              minimum: 0
                          required:
                            - mode
                            - count
                          additionalProperties: false
                        - type: object
                          properties:
                            mode:
                              type: string
                              enum:
                                - all
                          required:
                            - mode
                          additionalProperties: false
                    recurrence:
                      type: string
                      enum:
                        - finite
                        - monitoring
                    geography:
                      type: object
                      properties:
                        mode:
                          type: string
                          enum:
                            - explicit
                        countryCodes:
                          minItems: 1
                          type: array
                          items:
                            type: string
                            description: String value with endpoint-specific validation.
                        cityNames:
                          type: array
                          items:
                            type: string
                            minLength: 1
                      required:
                        - mode
                        - countryCodes
                      additionalProperties: false
                    companySize:
                      type: object
                      properties:
                        min:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        max:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                      additionalProperties: false
                    personCriteria:
                      minItems: 1
                      maxItems: 12
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            maxLength: 60
                            description: String value with endpoint-specific validation.
                          kind:
                            type: string
                            enum:
                              - current_title
                          values:
                            minItems: 1
                            maxItems: 12
                            type: array
                            items:
                              type: string
                              minLength: 1
                              maxLength: 120
                        required:
                          - id
                          - kind
                          - values
                        additionalProperties: false
                    unresolvedPreferences:
                      maxItems: 3
                      type: array
                      items:
                        type: string
                        minLength: 1
                        maxLength: 240
                    companyCriteria:
                      description: >-
                        Every separate entry is AND-combined and must pass. Put
                        OR alternatives in one criterion value instead of
                        separate entries.
                      maxItems: 12
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            maxLength: 60
                            description: String value with endpoint-specific validation.
                          kind:
                            type: string
                            enum:
                              - business_model
                              - customer_type
                              - offering
                              - industry
                              - exclusion
                              - other
                          operator:
                            type: string
                            enum:
                              - is
                              - is_not
                          value:
                            type: string
                            minLength: 1
                            maxLength: 120
                        required:
                          - id
                          - kind
                          - operator
                          - value
                        additionalProperties: false
                    rankedCompanyCohort:
                      oneOf:
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - default
                            limit:
                              type: integer
                              exclusiveMinimum: true
                              maximum: 9007199254740991
                              minimum: 0
                          required:
                            - kind
                          additionalProperties: false
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - named
                                - attached
                            sourceId:
                              type: string
                              minLength: 1
                              maxLength: 120
                            limit:
                              type: integer
                              exclusiveMinimum: true
                              maximum: 9007199254740991
                              minimum: 0
                          required:
                            - kind
                            - sourceId
                          additionalProperties: false
                        - type: object
                          properties:
                            kind:
                              type: string
                              enum:
                                - metric
                            metric:
                              type: string
                              enum:
                                - revenue
                                - market_cap
                            limit:
                              type: integer
                              exclusiveMinimum: true
                              maximum: 9007199254740991
                              minimum: 0
                          required:
                            - kind
                            - metric
                          additionalProperties: false
                  required:
                    - sourceId
                    - query
                    - reason
                  additionalProperties: false
                details:
                  type: object
                  properties:
                    channel:
                      type: string
                    signal:
                      type: string
                    expectedLead:
                      type: string
                    whyThisShouldWork:
                      type: string
                    plannerAssumedPreferences:
                      type: array
                      items:
                        type: string
                  additionalProperties: {}
              required:
                - title
                - intent
                - origin
                - sourcePlan
              additionalProperties: false
      responses:
        '200':
          description: Search created.
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    properties:
                      search:
                        type: object
                        properties:
                          searchId:
                            type: string
                            format: uuid
                          title:
                            type: string
                          description:
                            type: string
                          kind:
                            type: string
                            enum:
                              - recurring
                              - static
                          surface:
                            type: string
                            enum:
                              - lead-finder
                              - feed
                          scheduleEnabled:
                            type: boolean
                          definitionHash:
                            type: string
                            minLength: 64
                            maxLength: 64
                            nullable: true
                          intent:
                            type: string
                          sellerContext:
                            type: string
                          sourcePlans:
                            type: array
                            items:
                              type: object
                              properties:
                                sourceId:
                                  type: string
                                  enum:
                                    - linkedin_posts
                                    - linkedin_people
                                    - news
                                    - reddit
                                    - hacker_news
                                    - x_twitter
                                    - hiring_cafe
                                    - github
                                query:
                                  minItems: 1
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                    maxLength: 240
                                reason:
                                  type: string
                                  minLength: 1
                                  maxLength: 240
                                resultTarget:
                                  oneOf:
                                    - type: object
                                      properties:
                                        mode:
                                          type: string
                                          enum:
                                            - count
                                        count:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - mode
                                        - count
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        mode:
                                          type: string
                                          enum:
                                            - all
                                      required:
                                        - mode
                                      additionalProperties: false
                                recurrence:
                                  type: string
                                  enum:
                                    - finite
                                    - monitoring
                                geography:
                                  type: object
                                  properties:
                                    mode:
                                      type: string
                                      enum:
                                        - explicit
                                    countryCodes:
                                      minItems: 1
                                      type: array
                                      items:
                                        type: string
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                    cityNames:
                                      type: array
                                      items:
                                        type: string
                                        minLength: 1
                                  required:
                                    - mode
                                    - countryCodes
                                  additionalProperties: false
                                companySize:
                                  type: object
                                  properties:
                                    min:
                                      type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                    max:
                                      type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                  additionalProperties: false
                                personCriteria:
                                  minItems: 1
                                  maxItems: 12
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        maxLength: 60
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                      kind:
                                        type: string
                                        enum:
                                          - current_title
                                      values:
                                        minItems: 1
                                        maxItems: 12
                                        type: array
                                        items:
                                          type: string
                                          minLength: 1
                                          maxLength: 120
                                    required:
                                      - id
                                      - kind
                                      - values
                                    additionalProperties: false
                                unresolvedPreferences:
                                  maxItems: 3
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                    maxLength: 240
                                companyCriteria:
                                  description: >-
                                    Every separate entry is AND-combined and
                                    must pass. Put OR alternatives in one
                                    criterion value instead of separate entries.
                                  maxItems: 12
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        maxLength: 60
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                      kind:
                                        type: string
                                        enum:
                                          - business_model
                                          - customer_type
                                          - offering
                                          - industry
                                          - exclusion
                                          - other
                                      operator:
                                        type: string
                                        enum:
                                          - is
                                          - is_not
                                      value:
                                        type: string
                                        minLength: 1
                                        maxLength: 120
                                    required:
                                      - id
                                      - kind
                                      - operator
                                      - value
                                    additionalProperties: false
                                rankedCompanyCohort:
                                  oneOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - default
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - named
                                            - attached
                                        sourceId:
                                          type: string
                                          minLength: 1
                                          maxLength: 120
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                        - sourceId
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - metric
                                        metric:
                                          type: string
                                          enum:
                                            - revenue
                                            - market_cap
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                        - metric
                                      additionalProperties: false
                              required:
                                - sourceId
                                - query
                                - reason
                              additionalProperties: false
                          details:
                            type: object
                            properties:
                              channel:
                                type: string
                              signal:
                                type: string
                              expectedLead:
                                type: string
                              whyThisShouldWork:
                                type: string
                              plannerAssumedPreferences:
                                type: array
                                items:
                                  type: string
                            additionalProperties: false
                          lastRunId:
                            type: string
                            format: uuid
                            nullable: true
                          outboundCampaignId:
                            type: string
                            format: uuid
                            nullable: true
                          leadCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          resultCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          contactedCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          nextRunAt:
                            type: string
                            nullable: true
                          createdAt:
                            type: string
                          updatedAt:
                            type: string
                        required:
                          - searchId
                          - title
                          - description
                          - kind
                          - surface
                          - scheduleEnabled
                          - definitionHash
                          - intent
                          - sellerContext
                          - sourcePlans
                          - details
                          - lastRunId
                          - outboundCampaignId
                          - leadCount
                          - resultCount
                          - contactedCount
                          - nextRunAt
                          - createdAt
                          - updatedAt
                        additionalProperties: false
                      run:
                        type: object
                        properties:
                          runId:
                            type: string
                            minLength: 1
                          triggerRunId:
                            type: string
                            minLength: 1
                            nullable: true
                          status:
                            type: string
                            enum:
                              - queued
                              - running
                              - completed
                              - partial
                              - failed
                              - cancelled
                          continuationRetryAfter:
                            type: string
                            format: date-time
                            nullable: true
                          counts:
                            type: object
                            additionalProperties:
                              type: number
                        required:
                          - runId
                          - triggerRunId
                          - status
                          - continuationRetryAfter
                          - counts
                        additionalProperties: false
                      dispatch:
                        type: string
                        enum:
                          - recorded
                          - accepted_unrecorded
                          - existing
                      searchDisposition:
                        type: string
                        enum:
                          - created
                          - reused
                      runDisposition:
                        type: string
                        enum:
                          - queued
                          - existing
                    required:
                      - search
                      - run
                      - dispatch
                      - searchDisposition
                      - runDisposition
                    additionalProperties: false
                  - type: object
                    properties:
                      search:
                        type: object
                        properties:
                          searchId:
                            type: string
                            format: uuid
                          title:
                            type: string
                          description:
                            type: string
                          kind:
                            type: string
                            enum:
                              - recurring
                              - static
                          surface:
                            type: string
                            enum:
                              - lead-finder
                              - feed
                          scheduleEnabled:
                            type: boolean
                          definitionHash:
                            type: string
                            minLength: 64
                            maxLength: 64
                            nullable: true
                          intent:
                            type: string
                          sellerContext:
                            type: string
                          sourcePlans:
                            type: array
                            items:
                              type: object
                              properties:
                                sourceId:
                                  type: string
                                  enum:
                                    - linkedin_posts
                                    - linkedin_people
                                    - news
                                    - reddit
                                    - hacker_news
                                    - x_twitter
                                    - hiring_cafe
                                    - github
                                query:
                                  minItems: 1
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                    maxLength: 240
                                reason:
                                  type: string
                                  minLength: 1
                                  maxLength: 240
                                resultTarget:
                                  oneOf:
                                    - type: object
                                      properties:
                                        mode:
                                          type: string
                                          enum:
                                            - count
                                        count:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - mode
                                        - count
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        mode:
                                          type: string
                                          enum:
                                            - all
                                      required:
                                        - mode
                                      additionalProperties: false
                                recurrence:
                                  type: string
                                  enum:
                                    - finite
                                    - monitoring
                                geography:
                                  type: object
                                  properties:
                                    mode:
                                      type: string
                                      enum:
                                        - explicit
                                    countryCodes:
                                      minItems: 1
                                      type: array
                                      items:
                                        type: string
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                    cityNames:
                                      type: array
                                      items:
                                        type: string
                                        minLength: 1
                                  required:
                                    - mode
                                    - countryCodes
                                  additionalProperties: false
                                companySize:
                                  type: object
                                  properties:
                                    min:
                                      type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                    max:
                                      type: integer
                                      minimum: 0
                                      maximum: 9007199254740991
                                  additionalProperties: false
                                personCriteria:
                                  minItems: 1
                                  maxItems: 12
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        maxLength: 60
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                      kind:
                                        type: string
                                        enum:
                                          - current_title
                                      values:
                                        minItems: 1
                                        maxItems: 12
                                        type: array
                                        items:
                                          type: string
                                          minLength: 1
                                          maxLength: 120
                                    required:
                                      - id
                                      - kind
                                      - values
                                    additionalProperties: false
                                unresolvedPreferences:
                                  maxItems: 3
                                  type: array
                                  items:
                                    type: string
                                    minLength: 1
                                    maxLength: 240
                                companyCriteria:
                                  description: >-
                                    Every separate entry is AND-combined and
                                    must pass. Put OR alternatives in one
                                    criterion value instead of separate entries.
                                  maxItems: 12
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: string
                                        maxLength: 60
                                        description: >-
                                          String value with endpoint-specific
                                          validation.
                                      kind:
                                        type: string
                                        enum:
                                          - business_model
                                          - customer_type
                                          - offering
                                          - industry
                                          - exclusion
                                          - other
                                      operator:
                                        type: string
                                        enum:
                                          - is
                                          - is_not
                                      value:
                                        type: string
                                        minLength: 1
                                        maxLength: 120
                                    required:
                                      - id
                                      - kind
                                      - operator
                                      - value
                                    additionalProperties: false
                                rankedCompanyCohort:
                                  oneOf:
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - default
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - named
                                            - attached
                                        sourceId:
                                          type: string
                                          minLength: 1
                                          maxLength: 120
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                        - sourceId
                                      additionalProperties: false
                                    - type: object
                                      properties:
                                        kind:
                                          type: string
                                          enum:
                                            - metric
                                        metric:
                                          type: string
                                          enum:
                                            - revenue
                                            - market_cap
                                        limit:
                                          type: integer
                                          exclusiveMinimum: true
                                          maximum: 9007199254740991
                                          minimum: 0
                                      required:
                                        - kind
                                        - metric
                                      additionalProperties: false
                              required:
                                - sourceId
                                - query
                                - reason
                              additionalProperties: false
                          details:
                            type: object
                            properties:
                              channel:
                                type: string
                              signal:
                                type: string
                              expectedLead:
                                type: string
                              whyThisShouldWork:
                                type: string
                              plannerAssumedPreferences:
                                type: array
                                items:
                                  type: string
                            additionalProperties: false
                          lastRunId:
                            type: string
                            format: uuid
                            nullable: true
                          outboundCampaignId:
                            type: string
                            format: uuid
                            nullable: true
                          leadCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          resultCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          contactedCount:
                            type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          nextRunAt:
                            type: string
                            nullable: true
                          createdAt:
                            type: string
                          updatedAt:
                            type: string
                        required:
                          - searchId
                          - title
                          - description
                          - kind
                          - surface
                          - scheduleEnabled
                          - definitionHash
                          - intent
                          - sellerContext
                          - sourcePlans
                          - details
                          - lastRunId
                          - outboundCampaignId
                          - leadCount
                          - resultCount
                          - contactedCount
                          - nextRunAt
                          - createdAt
                          - updatedAt
                        additionalProperties: false
                      run:
                        nullable: true
                      searchDisposition:
                        type: string
                        enum:
                          - created
                          - reused
                      runDisposition:
                        type: string
                        enum:
                          - blocked
                      dispatch:
                        type: string
                        enum:
                          - blocked
                      blocker:
                        type: object
                        properties:
                          sourceId:
                            type: string
                          code:
                            type: string
                          message:
                            type: string
                          retryable:
                            type: boolean
                          alert:
                            type: boolean
                          action:
                            type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - navigate
                              label:
                                type: string
                              href:
                                type: string
                            required:
                              - type
                              - label
                              - href
                            additionalProperties: false
                        required:
                          - sourceId
                          - code
                          - message
                          - retryable
                          - alert
                        additionalProperties: false
                    required:
                      - search
                      - run
                      - searchDisposition
                      - runDisposition
                      - dispatch
                      - blocker
                    additionalProperties: false
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  sourceId:
                    type: string
                  code:
                    type: string
                  alternatives:
                    type: array
                    items:
                      type: string
                  retryable:
                    type: boolean
                  alert:
                    type: boolean
                  action:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - navigate
                      label:
                        type: string
                      href:
                        type: string
                    required:
                      - type
                      - label
                      - href
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  sourceId:
                    type: string
                  code:
                    type: string
                  alternatives:
                    type: array
                    items:
                      type: string
                  retryable:
                    type: boolean
                  alert:
                    type: boolean
                  action:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - navigate
                      label:
                        type: string
                      href:
                        type: string
                    required:
                      - type
                      - label
                      - href
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                  sourceId:
                    type: string
                  code:
                    type: string
                  alternatives:
                    type: array
                    items:
                      type: string
                  retryable:
                    type: boolean
                  alert:
                    type: boolean
                  action:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - navigate
                      label:
                        type: string
                      href:
                        type: string
                    required:
                      - type
                      - label
                      - href
                    additionalProperties: false
                required:
                  - error
                additionalProperties: false
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: pk_live_...

````