openapi: 3.1.0
info:
  title: Bagel Api
  description: Bagel API docs
  version: 1.0.0
  contact:
    email: support@getbagel.com
    url: https://developers.bagel.ai
  license:
    name: MIT
    url: https://opensource.org/license/mit/
servers:
  - url: https://api.bagel.ai
paths:
  /export/ideas:
    post:
      summary: Export ideas
      description: Export ideas based on date range.
      operationId: ExportIdeas
      tags:
        - Export API
      security:
        - ApiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                createdAtStart:
                  type: string
                  format: date-time
                  description: ISO 8601 date string.
                  example: '2024-12-01T00:00:00.000Z'
                createdAtEnd:
                  type: string
                  format: date-time
                  description: ISO 8601 date string.
                  example: '2024-12-26T00:00:00.000Z'
      responses:
        '200':
          description: A list of ideas
          content:
            application/json:
              schema:
                type: object
                properties:
                  ideas:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiIdea'
        '400':
          description: Invalid request payload.
        '401':
          description: Unauthorized. Auth token is required.
        '500':
          description: Internal server error.
  /export/evidences:
    post:
      summary: Export evidence
      description: Exports evidence based on date range.
      operationId: ExportEvidence
      tags:
        - Export API
      security:
        - ApiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                createdAtStart:
                  type: string
                  format: date-time
                  description: ISO 8601 date string.
                  example: '2024-12-01T00:00:00.000Z'
                createdAtEnd:
                  type: string
                  format: date-time
                  description: ISO 8601 date string.
                  example: '2024-12-26T00:00:00.000Z'
      responses:
        '200':
          description: A list of evidence
          content:
            application/json:
              schema:
                type: object
                properties:
                  evidences:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiEvidence'
              example:
                evidences:
                  - id: '1'
                    title: Request 1
                    origin: salesforce
                    origin_id: SFOpporunityId-123
                    type: request
                    business_name: Customer Health Comments
                    source: request
                    description: Evidence for claim A
                    priority: High
                    domain: Legal
                    product_area: Case Management
                    product_sub_area: Compliance
                    owner:
                      id: 6409c5ccece53d4dbbe93b59
                      name: Test User
                      email: example@gmail.com
                    delivery_item:
                      id: 6543b274ae193deed0ecacbc
                      status: done
                      link: https://bageltechnologies.atlassian.net
                    origin_object:
                      id: 6543b274ae193deed0ecacbc
                      origin: salesforce
                      origin_id: SFOpporunityId-123
                      type: opportunity
                      title: Opportunity Title
                      description: Opportunity Description
                      link: https://example.salesforce.net/item/567
                    gtm_idea:
                      id: 6409c5ccece53d4dbbe93b59
                      status: test
                      title: Idea Title
                    company:
                      name: Burlington Textiles Corp of America
                      external_id: 001Rt000001i4OsTQZ
                      intercom_id: '14563459202934'
                      sf_id: 001Rt000001i4OsTQZ
                      zendesk_id: '152693059'
                      crm_id: 001Rt000001i4OsTQZ
                    submitter:
                      id: 6409c5ccece53d4dbbe93b59
                      name: Submitter Name
                      email: submitter@example.com
                    reject_info:
                      reason: Insufficient data
                      comment: Needs further clarification
                      rejecting_user:
                        id: 6409c5ccece53d4dbbe93b59
                        name: Rejecting User
                        email: rejecting.user@example.com
                      rejected_at: '2023-12-01T00:00:00.000Z'
                    createdAt: '2023-12-01T00:00:00.000Z'
                    updatedAt: '2023-12-02T12:00:00.000Z'
        '400':
          description: Invalid request payload.
        '401':
          description: Unauthorized. Auth token is required.
        '500':
          description: Internal server error.
  /sync/feedback:
    post:
      summary: Send feedback to Bagel
      description: >-
        Receive a batch of original feedback items from an external integration
        and store them as original items in Bagel.  Each item must have an
        originId, linkedAccountId, and createdAt. The accountId is taken from
        the API token. The origin system is automatically set to 'api'.
      operationId: IngestFeedbackItems
      tags:
        - Sync API
      security:
        - ApiToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - feedbackName
                - feedbackCategory
                - originSystem
                - records
              properties:
                feedbackName:
                  type: string
                  description: Name identifier for the feedback type
                  example: gong_feature_request
                feedbackCategory:
                  type: string
                  description: The feedback category
                  enum:
                    - call
                    - ticket
                    - survey
                    - chat
                    - lostReason
                    - note
                    - request
                    - meetingInterview
                    - other
                  example: call
                originSystem:
                  type: string
                  description: The origin system where the feedback items come from
                  example: salesforce
                records:
                  type: array
                  items:
                    type: object
                    required:
                      - originId
                      - linkedAccountId
                      - createdAt
                    properties:
                      originId:
                        type: string
                        description: >-
                          The ID of the original item in the system of origin
                          (e.g., Gong call ID, Survey response ID)
                        example: gong-call-123
                      linkedAccountId:
                        type: string
                        description: >-
                          CRM ID of the relevant customer to this
                          evidence/request
                        example: sf-account-456
                      createdAt:
                        type: string
                        format: date-time
                        description: >-
                          The date the evidence was created/submitted (e.g.,
                          Call date, survey response date)
                        example: '2024-01-15T10:30:00.000Z'
                      submitterEmail:
                        type: string
                        format: email
                        description: >-
                          If applicable, the email of the internal employee who
                          submitted this evidence
                        example: john.doe@company.com
                      title:
                        type: string
                        description: Optional title for the feedback item
                        example: Feature request from customer call
                      description:
                        type: string
                        description: Optional description of the feedback
                        example: >-
                          Customer requested advanced reporting capabilities
                          during the sales call
                      productComponent:
                        type: string
                        description: Optional product component related to this feedback
                        example: reporting-module
                      priority:
                        type: string
                        description: Optional priority level
                        example: high
              example:
                feedbackName: gong_feature_request
                feedbackCategory: call
                originSystem: gong
                records:
                  - originId: gong-call-123
                    linkedAccountId: sf-account-456
                    createdAt: '2024-01-15T10:30:00.000Z'
                    submitterEmail: sales@company.com
                    title: Feature request from Q4 review
                    description: Customer wants better integration with their CRM
                    priority: high
                  - originId: gong-call-124
                    linkedAccountId: sf-account-789
                    createdAt: '2024-01-16T14:00:00.000Z'
                    title: API enhancement request
                    description: Customer needs webhook support
      responses:
        '200':
          description: Feedback items processed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  receivedCount:
                    type: integer
                  filteredCount:
                    type: integer
                  insertedCount:
                    type: integer
                  skippedCount:
                    type: integer
                  errors:
                    type: array
                    items:
                      type: object
              example:
                receivedCount: 2
                filteredCount: 2
                insertedCount: 2
                skippedCount: 0
                errors: []
        '400':
          description: Invalid request or missing mandatory parameters
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
components:
  securitySchemes:
    ApiToken:
      description: >
        Generate your secret API Token in the app settings.

        use the token as the value for the `authorization` header in the
        following format: Authorization: `Bearer {token}`.
      name: authorization
      type: apiKey
      in: header
  schemas:
    ApiIdea:
      type: object
      properties:
        id:
          type: string
          description: Unique Bagel ID of the idea
          example: '12345'
        title:
          type: string
          description: The idea title
          example: New Feature Implementation
        description:
          type: string
          description: The idea description
          example: This idea proposes a new feature for improving user experience.
        priority:
          type: string
          description: >-
            Custom options defined by the user in Bagel. Typically values like
            High, Medium, or Low.
          example: High
        domain:
          type: string
          description: >-
            Broad business domains that are often connected to several product
            areas. These represent the main domains of the company.
          example: Product
        product_area:
          type: string
          description: More specific area of the business product related to the idea.
          example: UX Design
        product_sub_area:
          type: string
          description: Further refines the product categorization.
          example: Prototyping
        status:
          type: string
          description: The current status set for the idea
          example: Pending
        link:
          type: string
          description: Direct link to view the idea in Bagel
          example: https://app.bagel.ai/idea/12345
        owner:
          type: object
          description: A Bagel user associated with this idea
          properties:
            id:
              type: string
              description: The owner's UUID
              example: abc123
            name:
              type: string
              description: The owner's name
              example: Jane Doe
            email:
              type: string
              format: email
              description: The owner's email
              example: jane.doe@example.com
        delivery_item:
          type: object
          description: External item linked to the idea (usually a Jira issue)
          properties:
            id:
              type: string
              description: The delivery item ID
              example: delivery123
            status:
              type: string
              description: The status of the linked external item/issue
              example: In Progress
            link:
              type: string
              description: Direct link to the item/issue in the external application
              example: https://delivery.example.com
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the idea was initially created
          example: '2023-12-01T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: >-
            Timestamp when any idea fields were last updated (title,
            description, priority, status, owner, etc.)
          example: '2023-12-05T15:00:00.000Z'
        impact:
          type: object
          description: >-
            Aggregated impact properties for the idea, keyed by impact property
            name. Each entry contains assigned, suggested, and total values.
            Impact properties are defined in the idea configuration.
          additionalProperties:
            $ref: '#/components/schemas/ApiIdeaImpactValue'
          example:
            totalRevenue:
              label: Total Revenue
              assigned: 50000
              suggested: 75000
              total: 125000
            companiesCount:
              label: Companies
              assigned: 10
              suggested: 5
              total: 15
    ApiIdeaImpactValue:
      type: object
      description: Impact aggregation breakdown for a single impact property
      properties:
        label:
          type: string
          description: The display label for this impact property
          example: Total Revenue
        assigned:
          type: number
          description: The manually assigned impact value
          example: 50000
        suggested:
          type: number
          description: The AI-suggested impact value
          example: 75000
        total:
          type: number
          description: The combined total impact value (assigned + suggested)
          example: 125000
    ApiEvidence:
      type: object
      properties:
        id:
          type: string
          description: Unique Bagel ID for the evidence
          example: evid123
        title:
          type: string
          description: The title of the evidence
          example: Evidence for Compliance
        origin:
          type: string
          description: >-
            The source system where this evidence was created (can be Bagel or
            external apps like Salesforce, Zendesk, etc.)
          example: System
        origin_id:
          type: string
          description: >-
            Optional ID of the item that this evidence originated from in the
            external system
          example: orig5678
        description:
          type: string
          description: The description of the evidence
          example: Supporting evidence for compliance case.
        priority:
          type: string
          description: >-
            The priority of the evidence, usually set to default and can be
            selected when evidences are created from GTM apps
          example: Medium
        domain:
          type: string
          description: >-
            Broad business domains that are often connected to several product
            areas. These represent the main domains of the company.
          example: Legal
        product_area:
          type: string
          description: More specific area of the business product related to the idea
          example: Risk Management
        product_sub_area:
          type: string
          description: Further refines the product categorization
          example: Fraud Detection
        type:
          type: string
          description: >
            The type of evidence. Can be either 'gap' or 'request'.

            - 'gap': Evidence automatically extracted from various data sources
            such as:
              * Support calls and interactions
              * Customer surveys
              * Customer feedback
              * And other customer touchpoint data
              These represent identified gaps.

            - 'request': Evidence created and submitted primarily by GTM teams
            using their apps (Salesforce, Zendesk) or created inside Bagel
            platform by Bagel users.
          enum:
            - gap
            - request
            - null
          example: request
        state:
          type: string
          description: >
            The state of the evidence (formerly known as status). Only
            applicable for evidence of type 'request' as these go through a
            review process.

            Evidence of type 'gap' are considered connected to an idea simply by
            having an ideaId or not.


            Possible states:

            - 'inReview': The evidence request is waiting for review

            - 'assigned': The evidence has been assigned to idea

            - 'dismissed': The evidence request has been dismissed/rejected

            - null: state for 'gap' evidence
          enum:
            - inReview
            - assigned
            - dismissed
            - null
          example: inReview
        business_name:
          type: string
          description: The business name of the evidence
          example: Acme Corp
        source:
          type: string
          description: The source of the evidence
          example: Internal Audit
        owner:
          type: object
          description: >
            A Bagel user who is set as the owner of this evidence. Ownership is
            typically assigned automatically 

            based on the evidence's product area - each product area in Bagel
            settings has a designated owner, 

            and when evidence is created or assigned to a product area, its
            owner is set to match that area's owner.
          properties:
            id:
              type: string
              description: The owner's unique identifier in Bagel
              example: owner123
            name:
              type: string
              description: The owner's name
              example: John Smith
            email:
              type: string
              format: email
              description: The owner's email address
              example: john.smith@example.com
        delivery_item:
          type: object
          description: >
            External item (usually a Jira issue) that is inherited from the
            associated idea. 

            This field is present when the evidence has either:

            - ideaId: Direct connection to an idea

            - gtmIdeaId: Connection to an idea suggested by GTM team during
            request submission


            The delivery item details mirror those of the connected idea's
            delivery item.
          properties:
            id:
              type: string
              description: The delivery item Bagel ID
              example: delivery567
            origin:
              type: string
              description: The source system of this delivery item
              example: jira
            origin_id:
              type: string
              description: The ID of the delivery item in the external system
              example: JIRA-123
            title:
              type: string
              description: The title of the delivery item
              example: 2FA Implementation
            description:
              type: string
              description: The description of the delivery item
              example: >-
                Implement 2FA for all users with support for Google
                Authenticator, Microsoft Authenticator, and SMS. should support
                setting policy for different roles.
            status:
              type: string
              description: The current status of the linked external item/issue
              example: Completed
            link:
              type: string
              description: Direct link to access the item/issue in the external system
              example: https://delivery.example.com/item/567
        origin_object:
          type: object
          properties:
            id:
              type: string
              description: The related item Id
              example: '12345'
            origin:
              type: string
              description: The related item origin
              example: salesforce
            origin_id:
              type: string
              description: The related item Id at origin
              example: sFOpportunity123
            title:
              type: string
              description: The title of the item
              example: Opportunity Title
            description:
              type: string
              description: The description of the item
              example: Opportunity Description
            type:
              type: string
              description: The type of the item
              example: opportunity
            link:
              type: string
              description: The link of item
              example: https://example.salforce.com/item/567
        gtm_idea:
          type: object
          description: >
            Represents an idea that was suggested by the GTM team during
            evidence submission.

            When GTM teams submit evidence through their apps (like Salesforce
            or Zendesk),

            they can suggest an existing idea that this evidence should be
            connected to.

            This is different from a direct idea connection and serves as a
            suggestion

            that can be reviewed by the evidence owner.
          properties:
            id:
              type: string
              description: The ID of the suggested idea
              example: idea789
            status:
              type: string
              description: The current status of the suggested idea
              example: Implemented
            title:
              type: string
              description: The title of the suggested idea
              example: Streamlined Workflow
        submitter:
          type: object
          description: >
            Information about the user who submitted the request. Only present
            for evidence of type 'request'.

            Not applicable for evidence of type 'gap'.
          properties:
            id:
              type: string
              description: The submitter's unique identifier in bagel
              example: submit123
            name:
              type: string
              description: The submitter's name
              example: Alice Johnson
            email:
              type: string
              format: email
              description: The submitter's email address
              example: alice.johnson@example.com
        company:
          type: object
          description: >
            The company/account linked to this evidence. The connection is
            established differently based on evidence type and origin:

            - For Salesforce submissions: Automatically set based on the account
            from which the evidence was submitted

            - For Zendesk/Chrome extension: Manually set during submission

            - For 'gap' type evidence: Set to the account connected to the item
            from which the gap was extracted


            Company IDs from different systems are stored to maintain proper
            linking across integrations.

            Currently supports Salesforce and Zendesk as primary sources.
          properties:
            external_id:
              type: string
              description: Generic external identifier for the company
              example: comp123
            name:
              type: string
              description: The company's display name
              example: Tech Solutions Inc.
            intercom_id:
              type: string
              description: The company's Intercom identifier
              example: intercom567
            sf_id:
              type: string
              description: The company's Salesforce account ID
              example: sf789
            zendesk_id:
              type: string
              description: The company's Zendesk organization ID
              example: zendesk456
            crm_id:
              type: string
              description: The company's CRM identifier (typically matches Salesforce ID)
              example: 001Rt000001i4OsTQZ
        reject_info:
          type: object
          description: >
            Information about the rejection of an evidence request. This is only
            present when a GTM-submitted evidence 

            has been rejected by a Product Manager during the review process.
            This helps track why and by whom 

            the evidence request was rejected.
          properties:
            reason:
              type: string
              description: The reason category selected for rejecting the evidence request
              example: Insufficient data
            comment:
              type: string
              description: Additional explanation provided by the PM for the rejection
              example: Please provide additional supporting documents.
            rejected_at:
              type: string
              description: Timestamp when the evidence was rejected by the PM
              format: date-time
              example: '2023-12-01T00:00:00.000Z'
            rejecting_user:
              type: object
              description: Information about the Product Manager who rejected the evidence
              properties:
                id:
                  type: string
                  description: The PM's unique identifier in bagel
                  example: rejectuser123
                name:
                  type: string
                  description: The PM's name
                  example: Bob Carter
                email:
                  type: string
                  format: email
                  description: The PM's email address
                  example: bob.carter@example.com
        createdAt:
          type: string
          format: date-time
          description: The creation date of the evidence
          example: '2023-12-01T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: The last updated date of the evidence
          example: '2023-12-05T15:00:00.000Z'
tags:
  - name: Export API
    description: Export ideas / evidence
  - name: Sync API
    description: Sync feedback items into Bagel
security:
  - ApiToken: []
