{ "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.\nuse the token as the value for the `authorization` header in the following format: Authorization: `Bearer {token}`.\n", "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'.\n- 'gap': Evidence automatically extracted from various data sources such as:\n * Support calls and interactions\n * Customer surveys\n * Customer feedback\n * And other customer touchpoint data\n These represent identified gaps.\n\n- 'request': Evidence created and submitted primarily by GTM teams using their apps (Salesforce, Zendesk) or created inside Bagel platform by Bagel users.\n", "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.\nEvidence of type 'gap' are considered connected to an idea simply by having an ideaId or not.\n\nPossible states:\n- 'inReview': The evidence request is waiting for review\n- 'assigned': The evidence has been assigned to idea\n- 'dismissed': The evidence request has been dismissed/rejected\n- null: state for 'gap' evidence\n", "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 \nbased on the evidence's product area - each product area in Bagel settings has a designated owner, \nand when evidence is created or assigned to a product area, its owner is set to match that area's owner.\n", "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. \nThis field is present when the evidence has either:\n- ideaId: Direct connection to an idea\n- gtmIdeaId: Connection to an idea suggested by GTM team during request submission\n\nThe delivery item details mirror those of the connected idea's delivery item.\n", "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.\nWhen GTM teams submit evidence through their apps (like Salesforce or Zendesk),\nthey can suggest an existing idea that this evidence should be connected to.\nThis is different from a direct idea connection and serves as a suggestion\nthat can be reviewed by the evidence owner.\n", "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'.\nNot applicable for evidence of type 'gap'.\n", "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:\n- For Salesforce submissions: Automatically set based on the account from which the evidence was submitted\n- For Zendesk/Chrome extension: Manually set during submission\n- For 'gap' type evidence: Set to the account connected to the item from which the gap was extracted\n\nCompany IDs from different systems are stored to maintain proper linking across integrations.\nCurrently supports Salesforce and Zendesk as primary sources.\n", "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 \nhas been rejected by a Product Manager during the review process. This helps track why and by whom \nthe evidence request was rejected.\n", "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": [] } ] }