openapi: 3.0.1 info: title: Reforge Insights (formerly Monterey AI) API version: 1.0.5 servers: - url: https://insights.reforge.com/api/v1 components: securitySchemes: BearerAuth: type: http scheme: bearer description: Bearer authentication header of the form Bearer , where is your auth token. AdminBearerAuth: type: http scheme: bearer description: Bearer authentication header of the form Bearer , where is your auth token. **Admin-level permissions required** schemas: Feedback: type: object properties: id: type: string description: type: string customerId: type: string projectId: type: string rating: type: number sourceId: type: string sourceData: type: object Customer: type: object properties: id: type: string name: type: string email: type: string Customers: type: array items: $ref: "#/components/schemas/Customer" FeedbackCategory: type: object properties: id: type: string title: type: string FeedbackCategories: type: array items: $ref: "#/components/schemas/FeedbackCategory" AssociateExistingCustomer: description: Used when associating to an existing, known customer, the `id` is the customer ID from Reforge Insights. If the a customer with the provided ID does not exist, the feedback will not be associated to a customer. type: object nullable: true properties: id: description: The Reforge Insights ID of the customer type: string FindOrCreateCustomer: description: Used when associating to a new customer, or when not knowing the ID, for which it will be de-duplicated by the email field. The `email` field can be any string, such as a valid email OR a unique identifier from your own system. type: object nullable: true properties: name: type: string email: type: string sourceData: type: object description: Dictionary to provide other key-value pairs such as the url, identifier, or other information nullable: true AssociateExistingCustomerAccount: description: Used when associating to an existing, known customer account, the `id` is the customer account ID from Reforge Insights. If the a customer account with the provided ID does not exist, the feedback will not be associated to a customer account. type: object nullable: true properties: id: description: The Reforge Insights ID of the customer account type: string FindOrCreateCustomerAccount: description: Used when associating to a new customer account, or when not knowing the ID, for which it will be de-duplicated by the name or domain field. The `name` and 'domain' fields can be any string, such as a valid name/domain OR a unique identifier from your own system. type: object nullable: true properties: name: type: string domain: type: string contractValue: type: number nullable: true sourceData: type: object description: Dictionary to provide other key-value pairs such as the url, identifier, or other information nullable: true Project: description: A project response object type: object properties: id: type: string name: type: string description: type: string Projects: type: array items: $ref: "#/components/schemas/Project" AssociateExistingProject: description: Used when associating to an existing, known project type: object nullable: true properties: id: type: string FindOrCreateProject: description: Used when associating to a new project, or when not knowing the ID, for which it will be de-duplicated by the name. type: object nullable: true properties: name: type: string Account: type: object required: - id properties: id: type: string description: The unique identifier for the account. example: account-789 shouldUnflattenProperties: type: boolean description: 'Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`' nullable: true properties: type: object required: - $name - $domain properties: $name: type: string description: The name of the account. example: Acme, Inc. $domain: type: string description: The domain of the account. example: acme.com $createdAt: type: string format: date-time nullable: true $updatedAt: type: string format: date-time nullable: true $contractValue: type: number description: The contract value of the account. example: 100000 nullable: true Contact: type: object required: - id properties: id: type: string description: External contact ID nullable: false shouldUnflattenProperties: type: boolean description: 'Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`' nullable: true properties: description: Properties prefixed with `$` are handled specially. Otherwise, additional key-value pairs will be metadata once ingested into the system type: object nullable: true properties: $email: type: string nullable: true $name: type: string nullable: true $createdAt: type: string format: date-time nullable: true $updatedAt: type: string format: date-time nullable: true $contractValue: type: number description: The contract value of the contact. example: 100000 nullable: true additionalProperties: true account: $ref: "#/components/schemas/Account" nullable: true source: type: string description: Source system to limit search to nullable: true ContactPurgeRequest: type: object properties: id: type: string description: External contact ID nullable: true email: type: string description: Contact email address nullable: true source: type: string description: Source system to limit search to nullable: true anyOf: - required: ["id"] - required: ["email"] paths: /feedbacks: post: summary: Create a new Feedback Record security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - description properties: title: type: string description: The feedback title, when provided nullable: true description: type: string description: The feedback content. Can be plain text or include basic HTML elements isTranscript: type: boolean description: Whether the feedback is a transcript nullable: true tags: description: A list of string tags to apply to the feedback. If excluded or null value provided, tags will be auto-generated based on description content. type: array items: type: string nullable: true isExternalContactId: type: boolean description: True if the contactId/contact.id is an external ID, false if it is a Reforge Insights contact ID. default: false contact: description: The Contact who provided the feedback. If providing an external ID, set isExternalContactId to true. oneOf: - $ref: "#/components/schemas/FindOrCreateCustomer" - $ref: "#/components/schemas/AssociateExistingCustomer" contactId: type: string description: ID of Contact to associate to. If providing an external ID, set isExternalContactId to true. nullable: true isExternalAccountId: type: boolean description: True if the accountId/account.id is an external ID, false if it is a Reforge Insights account ID. default: false account: description: The customer account to which the feedback should be associated. If providing an external ID, set isExternalAccountId to true. oneOf: - $ref: "#/components/schemas/FindOrCreateCustomerAccount" - $ref: "#/components/schemas/AssociateExistingCustomerAccount" nullable: true accountId: type: string description: ID of CustomerAccount to associate to. If providing an external ID, set isExternalAccountId to true. nullable: true source: type: string description: "The source of the feedback. Default: API (when excluded or provided as null" nullable: true sourceId: type: string description: A unique identifier for this specific record from the source system (e.g., a Jira ticket key like "ABC-1234", a Zendesk ticket ID, or a Salesforce case number). This is NOT the same as the `source` field—it identifies the individual record, not the integration. Used for deduplication and linking back to the original record. nullable: true shouldUnflattenSourceData: type: boolean description: 'Whether to unflatten sourceData that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`' nullable: true sourceData: type: object description: Dictionary to provide other key-value pairs such as the url, view identifier, or other information nullable: true rating: type: number description: The numeric rating (integer) nullable: true responses: 201: description: The feedback was created successfully content: application/json: schema: properties: feedback: $ref: "#/components/schemas/Feedback" /contacts/identify: post: summary: Identify a contact security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Contact" responses: 201: description: The customer was identified successfully content: application/json: schema: type: object properties: success: type: boolean /contacts/purge: post: summary: Delete contact data description: Permanently deletes a contact and all associated data. security: - AdminBearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ContactPurgeRequest" examples: purge-by-id-with-source: summary: Purge by ID with specific source description: Purge a contact by ID from a specific source system value: id: "user123" source: "salesforce" purge-by-id-all-sources: summary: Purge by ID across all sources description: Purge a contact by ID across all source systems value: id: "user123" purge-by-email-with-source: summary: Purge by email with specific source description: Purge a contact by email from a specific source system value: email: "john.doe@example.com" source: "salesforce" purge-by-email-all-sources: summary: Purge by email across all sources description: Purge a contact by email across all source systems value: email: "john.doe@example.com" responses: 200: description: The contact purge was initiated successfully content: application/json: schema: type: object properties: success: type: boolean 404: description: No contacts found matching the provided criteria content: application/json: schema: type: object properties: error: type: string example: "No contacts found" /accounts/identify: post: summary: Identify an account security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/Account" responses: 201: description: The account was identified successfully content: application/json: schema: type: object properties: success: type: boolean /conversations: post: summary: Submit a conversation description: Submits conversation data to the system for processing. This can be content like a call transcript, email thread, or chat conversation. security: - BearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: id: type: string description: The unique identifier for the conversation. example: conversation-123 title: type: string description: The title of the conversation. example: Customer Support Request nullable: true source: type: string description: The source of the conversation. example: intercom createdAt: type: string format: date-time description: The date and time the conversation was created. example: 2024-01-01T00:00:00.000Z updatedAt: type: string format: date-time description: The date and time the conversation was last updated. example: 2024-01-01T00:00:00.000Z nullable: true contacts: type: array items: $ref: "#/components/schemas/Contact" messages: type: array items: type: object properties: id: type: string description: The unique identifier for the message. example: message-789 incoming: type: boolean description: Indicates if the message is incoming (from an external user or customer) or outgoing (e.g. from a support agent or sales person on your team). example: true contactId: type: string description: The unique identifier for the contact that sent this message. example: user-456 content: type: string description: The content of the message. example: Hello! I'm having trouble... createdAt: type: string format: date-time description: The date and time the message was created. example: 2024-01-01T00:00:00.000Z shouldUnflattenProperties: type: boolean description: 'Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`' nullable: true properties: type: object description: Additional metadata properties (key-value pairs) additionalProperties: true sourceUrl: type: string description: URL linking to the source of this message nullable: true rating: type: number description: The numeric rating (integer) nullable: true shouldUnflattenProperties: type: boolean description: 'Whether to unflatten properties that are meant to be nested objects for example `{ "plan.type": "Pro" }` will be unflattened to `{ "plan": { "type": "Pro" } }`' nullable: true propagatePropertiesToMessages: type: boolean description: When true, conversation-level properties are merged into each message's rawData. Message properties take precedence over conversation properties when there are key conflicts. default: false nullable: true properties: type: object description: Additional metadata properties (key-value pairs) additionalProperties: true responses: 200: description: Conversation submitted successfully. content: application/json: schema: type: object properties: success: type: boolean example: true 400: description: Bad request. content: application/json: schema: type: object properties: error: type: array items: type: object properties: message: type: string example: "Invalid input" 429: description: Rate limit exceeded. content: application/json: schema: type: object properties: error: type: string example: "We are limiting to 10 per minute, please try again later"