{ "openapi": "3.1.0", "info": { "title": "Featurebase API", "version": "2026-01-01.nova", "description": "Welcome to the Featurebase API. This API allows you to programmatically interact with your Featurebase organization.\n\nThis documentation reflects API version **2026-01-01.nova**.", "contact": { "name": "Featurebase Support", "url": "https://featurebase.app" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://do.featurebase.app", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "API Versioning", "description": "This API uses **date-based versioning**. Each version is identified by a release date and slug, e.g., `2026-01-01.nova`.\n\n**Specifying a Version**\n\nInclude the version in the request header:\n\n```\nFeaturebase-Version: 2026-01-01.nova\n```\n\nOr set a default version for your organization in the dashboard settings.\n\n**Version Compatibility**\n\n- **Newer versions** may add new fields to responses (always backwards-compatible)\n- **Breaking changes** (removed/renamed fields, changed behavior) only occur in new versions\n- **Your integration will continue to work** as long as you pin to a specific version" }, { "name": "Authentication", "description": "All API requests require authentication via API key.\n\nInclude in headers:\n```\nAuthorization: Bearer \n```\n\n[Create and manage your API keys](https://auth.featurebase.app/login?redirect=/settings/api) in the Featurebase dashboard." }, { "name": "Error Handling", "description": "The API uses conventional HTTP response codes to indicate success or failure:\n\n- `2xx` - Success\n- `4xx` - Client errors (bad request, unauthorized, not found, etc.)\n- `5xx` - Server errors (internal error)\n\n**Error Response Format**\n\nAll errors follow a consistent format:\n\n```json\n{\n \"error\": {\n \"type\": \"invalid_request_error\",\n \"code\": \"resource_not_found\",\n \"message\": \"Post not found\",\n \"param\": \"id\",\n \"status\": 404\n }\n}\n```\n\n**Error Types**\n\n| Type | Description |\n|------|-------------|\n| `authentication_error` | Authentication failed (401) |\n| `authorization_error` | Permission denied (403) |\n| `invalid_request_error` | Invalid request parameters or resource not found (400, 404, 410) |\n| `api_error` | Server-side error (500) |\n| `rate_limit_error` | Too many requests (429) |" }, { "name": "Boards", "description": "Boards (post categories) organize feedback into distinct containers with their own settings." }, { "name": "Posts", "description": "User-submitted feedback and feature requests. Posts belong to boards and can be upvoted, commented on, and tracked through statuses." }, { "name": "Post Statuses", "description": "Post statuses define the workflow stages for posts (e.g., In Review, Active, Completed)." }, { "name": "Comments", "description": "Threaded discussions on posts and changelogs. Comments support voting, moderation, and privacy controls." }, { "name": "Changelogs", "description": "Release notes and updates published by the organization. Changelogs keep users informed about new features, improvements, and fixes." }, { "name": "Admins", "description": "Team members who manage your Featurebase organization. Admins have roles that define their permissions." }, { "name": "Custom Fields", "description": "Configurable input fields for posts in your Featurebase organization. Custom fields allow you to collect additional structured data when users create posts." }, { "name": "Surveys", "description": "Surveys allow you to collect targeted feedback from your users within your product. Surveys can be targeted to specific user segments or pages and can contain multiple questions with conditional logic." }, { "name": "Help Centers", "description": "Help centers allow organizations to create and manage knowledge bases with articles and collections. Currently, Featurebase supports one help center per organization." }, { "name": "Contacts", "description": "Contacts are the customers and leads in your Featurebase organization. Use this endpoint to list and retrieve contact information." }, { "name": "Teams", "description": "Teams are groups within your Featurebase organization. Use this endpoint to list and retrieve team information for conversation assignment and organization management." }, { "name": "Companies", "description": "Companies represent organizations or businesses that your users belong to. Use this endpoint to list and retrieve company information." }, { "name": "Brands", "description": "Brands represent distinct brand identities within your organization. Each brand can have its own help center and email sending address. Use this endpoint to list and retrieve brand information." }, { "name": "Conversations", "description": "Conversations are messenger/inbox conversations in your Featurebase organization. Use this endpoint to list and retrieve conversation information." }, { "name": "Webhooks", "description": "Webhooks allow you to receive real-time HTTP callbacks when events occur in your Featurebase organization. Configure webhook endpoints to subscribe to specific event types." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key as Bearer token. Use: Authorization: Bearer sk_..." } }, "schemas": { "ValidationError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_parameter", "missing_parameter", "invalid_cursor", "invalid_content", "invalid_request", "contact_not_customer", "contact_not_attached", "parameter_not_supported", "business_validation_error" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "example": "Invalid post ID format" }, "param": { "type": "string", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 }, "details": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "example": "body.name" }, "message": { "type": "string", "example": "Required" } }, "required": [ "path", "message" ] }, "description": "Additional validation error details" } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] }, "NotFoundError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "resource_not_found", "post_not_found", "comment_not_found", "changelog_not_found", "admin_not_found", "contact_not_found", "conversation_not_found", "conversation_part_not_found", "team_not_found", "survey_not_found", "company_not_found", "help_center_not_found", "collection_not_found", "article_not_found", "custom_field_not_found", "board_not_found", "voter_not_found", "participant_not_found", "webhook_not_found", "redirect_rule_not_found", "brand_not_found", "version_not_supported" ], "description": "Machine-readable error code", "example": "resource_not_found" }, "message": { "type": "string", "example": "Post not found" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] }, "ServerError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "api_error" ], "description": "The type of error returned", "example": "api_error" }, "code": { "type": "string", "enum": [ "database_error", "internal_error", "fetch_error", "create_error", "update_error", "delete_error" ], "description": "Machine-readable error code", "example": "database_error" }, "message": { "type": "string", "example": "An internal error occurred" }, "status": { "type": "number", "enum": [ 500 ], "description": "HTTP status code", "example": 500 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] }, "FeaturebaseVersion": { "type": "string", "example": "2026-01-01.nova" }, "BoardAccess": { "type": "object", "properties": { "adminOnly": { "type": "boolean", "description": "If true, only admins can see this board", "example": false }, "segments": { "type": "array", "items": { "type": "string" }, "description": "Segment IDs that can access (empty = all)", "example": [] }, "allowedRoles": { "type": "array", "items": { "type": "string" }, "description": "Role IDs allowed access (empty = all)", "example": [] }, "deniedRoles": { "type": "array", "items": { "type": "string" }, "description": "Role IDs explicitly denied access", "example": [ "role_blocked" ] } }, "required": [ "adminOnly", "segments", "allowedRoles", "deniedRoles" ] }, "BoardFeatures": { "type": "object", "properties": { "postingEnabled": { "type": "boolean", "description": "Whether users can create new posts", "example": true }, "commentsEnabled": { "type": "boolean", "description": "Whether users can comment on posts", "example": true }, "createdDatesVisible": { "type": "boolean", "description": "Whether creation dates are visible on posts", "example": true } }, "required": [ "postingEnabled", "commentsEnabled", "createdDatesVisible" ] }, "BoardPostDefaults": { "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "public", "authorOnly", "companyOnly" ], "description": "Default visibility for new posts", "example": "public" } }, "required": [ "visibility" ] }, "BoardLocalization": { "type": "object", "properties": { "name": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Localized board name (language code → text)", "example": { "en": "Feature Requests", "es": "Solicitudes de funciones" } }, "description": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Localized description", "example": { "en": "Submit and vote on feature ideas" } }, "formPlaceholder": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Placeholder text in the post creation form", "example": { "en": "Describe your feature idea..." } }, "heroTitle": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Hero title shown on the board page", "example": { "en": "Share your ideas" } }, "heroDescription": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Hero description/subtitle", "example": null }, "submitButtonText": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Submit button text", "example": { "en": "Submit Feedback" } } }, "required": [ "name", "description", "formPlaceholder", "heroTitle", "heroDescription", "submitButtonText" ] }, "Board": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "board" ], "description": "Object type identifier", "example": "board" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Display name in organization's default locale", "example": "Feature Requests" }, "icon": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "emoji" ], "description": "Emoji icon type", "example": "emoji" }, "value": { "type": "string", "description": "A single emoji character", "example": "💡" } }, "required": [ "type", "value" ], "description": "An emoji character as the board icon", "title": "EmojiIcon", "example": { "type": "emoji", "value": "💡" } }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "icon" ], "description": "Predefined icon type", "example": "icon" }, "value": { "type": "string", "description": "Icon name from the predefined icon set (e.g., lightbulb, bug, star, rocket, flag, heart, check, question, megaphone, gift)", "example": "lightbulb" } }, "required": [ "type", "value" ], "description": "A predefined icon from the built-in icon library", "title": "PredefinedIcon", "example": { "type": "icon", "value": "lightbulb" } }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "url" ], "description": "External URL icon type", "example": "url" }, "value": { "type": "string", "format": "uri", "description": "HTTPS URL to a custom icon image (PNG, SVG, or WebP recommended)", "example": "https://cdn.example.com/icons/custom-board-icon.png" } }, "required": [ "type", "value" ], "description": "A custom icon loaded from an external URL", "title": "UrlIcon", "example": { "type": "url", "value": "https://cdn.example.com/icons/custom-board-icon.png" } }, { "type": "null" } ], "description": "The board's icon. Can be one of three types:\n- **emoji**: A single emoji character (e.g., 💡, 🚀, ⭐)\n- **icon**: A predefined icon from the built-in library (e.g., lightbulb, bug, star)\n- **url**: A custom image URL (HTTPS required)\n\nCan be `null` if no icon is set.", "title": "BoardIcon" }, "access": { "$ref": "#/components/schemas/BoardAccess" }, "features": { "$ref": "#/components/schemas/BoardFeatures" }, "postDefaults": { "$ref": "#/components/schemas/BoardPostDefaults" }, "customFields": { "type": "array", "items": { "type": "string" }, "description": "Custom field IDs attached to this board", "example": [ "cf_priority", "cf_category" ] }, "localization": { "$ref": "#/components/schemas/BoardLocalization" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2023-12-12T00:00:00.000Z" } }, "required": [ "object", "id", "name", "icon", "access", "features", "postDefaults", "customFields", "localization", "createdAt" ] }, "BoardList": { "type": "array", "items": { "$ref": "#/components/schemas/Board" } }, "PostAuthor": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Author unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Author display name", "example": "John Doe" }, "email": { "type": [ "string", "null" ], "description": "Author email (if available)", "example": "john@example.com" }, "profilePicture": { "type": [ "string", "null" ], "description": "Author profile picture URL", "example": "https://cdn.example.com/avatars/john.png" }, "type": { "type": "string", "enum": [ "admin", "customer", "guest", "integration", "bot", "lead" ], "description": "Type of user who authored the post", "example": "customer" } }, "required": [ "id", "name", "email", "profilePicture", "type" ] }, "PostStatus": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "post_status" ], "description": "Object type identifier", "example": "post_status" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Display name", "example": "In Progress" }, "color": { "type": "string", "description": "Color for UI display", "example": "Blue" }, "type": { "type": "string", "enum": [ "reviewing", "unstarted", "active", "completed", "canceled" ], "description": "The workflow stage this status represents", "example": "active" }, "isDefault": { "type": "boolean", "description": "Whether this is the default status for new posts", "example": false } }, "required": [ "object", "id", "name", "color", "type", "isDefault" ] }, "PostTag": { "type": "object", "properties": { "id": { "type": "string", "description": "Tag unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Tag name", "example": "bug" }, "color": { "type": [ "string", "null" ], "description": "Tag color hex code", "example": "#FF5722" } }, "required": [ "id", "name", "color" ] }, "PostFeatures": { "type": "object", "properties": { "commentsEnabled": { "type": "boolean", "description": "Whether comments are allowed on this post", "example": true } }, "required": [ "commentsEnabled" ] }, "PostAccess": { "type": "object", "properties": { "userIds": { "type": "array", "items": { "type": "string" }, "description": "User IDs explicitly granted access to this post. Empty array means no user-level restrictions (post uses board/org visibility). Non-empty means only these users (plus admins) can see the post.", "example": [] }, "companyExternalIds": { "type": "array", "items": { "type": "string" }, "description": "External company IDs explicitly granted access to this post. Empty array means no company-level restrictions. Non-empty means only users belonging to these companies can see the post.", "example": [] } }, "required": [ "userIds", "companyExternalIds" ] }, "Post": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "post" ], "description": "Object type identifier", "example": "post" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "add-dark-mode-support" }, "postUrl": { "type": "string", "description": "Full URL to view the post", "example": "https://feedback.example.com/p/add-dark-mode-support" }, "title": { "type": "string", "description": "Post title", "example": "Add dark mode support" }, "content": { "type": "string", "description": "Post content in HTML format", "example": "

It would be great to have a dark mode option for the dashboard.

" }, "boardId": { "type": "string", "description": "Board (category) ID this post belongs to", "example": "507f1f77bcf86cd799439011" }, "author": { "$ref": "#/components/schemas/PostAuthor" }, "status": { "$ref": "#/components/schemas/PostStatus" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/PostTag" }, "description": "Tags attached to this post", "example": [ { "id": "507f1f77bcf86cd799439011", "name": "bug", "color": "#FF5722" } ] }, "features": { "$ref": "#/components/schemas/PostFeatures" }, "upvotes": { "type": "number", "description": "Total number of upvotes", "example": 42 }, "commentCount": { "type": "number", "description": "Total number of comments", "example": 5 }, "inReview": { "type": "boolean", "description": "Whether the post is pending moderation review", "example": false }, "isPinned": { "type": "boolean", "description": "Whether the post is pinned to the top", "example": false }, "access": { "$ref": "#/components/schemas/PostAccess" }, "assigneeId": { "type": [ "string", "null" ], "description": "ID of the admin assigned to this post, null if unassigned", "example": "507f1f77bcf86cd799439013" }, "eta": { "type": [ "string", "null" ], "description": "Estimated completion time as ISO 8601 timestamp, null if not set", "example": "2025-01-01T00:00:00.000Z" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Custom field values keyed by field ID", "example": { "cf_priority": "high", "cf_effort": 3 } }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2023-12-12T00:00:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last modified", "example": "2023-12-13T00:00:00.000Z" }, "integrations": { "type": "object", "properties": { "linear": { "type": "array", "items": { "type": "object", "properties": { "issueId": { "type": "string", "description": "Linear issue ID", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "issueUrl": { "type": [ "string", "null" ], "description": "URL to the Linear issue", "example": "https://linear.app/team/issue/ENG-123" } }, "required": [ "issueId", "issueUrl" ] } }, "jira": { "type": "array", "items": { "type": "object", "properties": { "issueId": { "type": "string", "description": "Jira issue ID", "example": "10042" }, "issueUrl": { "type": [ "string", "null" ], "description": "URL to the Jira issue", "example": "https://myteam.atlassian.net/browse/PROJ-123" } }, "required": [ "issueId", "issueUrl" ] } }, "clickup": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ClickUp task ID", "example": "86a1b2c3d" }, "url": { "type": "string", "description": "URL to the ClickUp task", "example": "https://app.clickup.com/t/86a1b2c3d" }, "title": { "type": "string", "description": "ClickUp task title", "example": "Add dark mode support" } }, "required": [ "id", "url", "title" ] } }, "github": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "GitHub issue ID", "example": "1234567890" }, "number": { "type": "string", "description": "GitHub issue number", "example": "42" }, "repositoryName": { "type": "string", "description": "Repository name", "example": "backend" }, "repositoryFullName": { "type": "string", "description": "Full repository name (owner/repo)", "example": "acme/backend" }, "url": { "type": "string", "description": "URL to the GitHub issue", "example": "https://github.com/acme/backend/issues/42" }, "title": { "type": "string", "description": "GitHub issue title", "example": "Add dark mode support" } }, "required": [ "id", "number", "repositoryName", "repositoryFullName", "url", "title" ] } }, "devops": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number", "description": "Azure DevOps work item ID", "example": 1234 }, "url": { "type": "string", "description": "URL to the work item", "example": "https://dev.azure.com/org/project/_workitems/edit/1234" }, "projectId": { "type": "string", "description": "Azure DevOps project ID", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "projectName": { "type": "string", "description": "Azure DevOps project name", "example": "My Project" }, "title": { "type": "string", "description": "Work item title", "example": "Add dark mode support" } }, "required": [ "id", "url", "projectId", "projectName", "title" ] } }, "hubspot": { "type": "array", "items": { "type": "object", "properties": { "objectId": { "type": "number", "description": "HubSpot object ID", "example": 123456789 }, "type": { "type": "string", "enum": [ "TICKET", "DEAL", "CONTACT" ], "description": "HubSpot object type", "example": "TICKET" }, "dealAmount": { "type": [ "number", "null" ], "description": "Deal amount (for DEAL type)", "example": 5000 }, "dealClosed": { "type": [ "boolean", "null" ], "description": "Whether the deal is closed (for DEAL type)", "example": false } }, "required": [ "objectId", "type", "dealAmount", "dealClosed" ] } } }, "required": [ "linear", "jira", "clickup", "github", "devops", "hubspot" ], "description": "Third-party integration links associated with this post" } }, "required": [ "object", "id", "slug", "postUrl", "title", "content", "boardId", "author", "status", "tags", "features", "upvotes", "commentCount", "inReview", "isPinned", "access", "assigneeId", "eta", "customFields", "createdAt", "updatedAt", "integrations" ] }, "PaginationMetadata": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" }, "PostList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Post" }, "description": "Array of posts", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "pagination": { "$ref": "#/components/schemas/PaginationMetadata" } }, "required": [ "object", "data", "nextCursor" ] }, "AuthorInput": { "type": "object", "properties": { "id": { "type": "string", "description": "Featurebase user ID to attribute content to", "example": "507f1f77bcf86cd799439011" }, "userId": { "type": "string", "maxLength": 255, "description": "External user ID from your system (matched via SSO)", "example": "usr_12345" }, "email": { "type": "string", "format": "email", "description": "Author email (used to find or create user)", "example": "john@example.com" }, "name": { "type": "string", "maxLength": 255, "description": "Author display name", "example": "John Doe" }, "profilePicture": { "type": "string", "description": "Author profile picture URL", "example": "https://example.com/avatar.png" } }, "description": "Author to attribute the post to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email." }, "CreatePostBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 512, "description": "Post title", "example": "Add dark mode support" }, "content": { "type": "string", "default": "", "description": "Post content (HTML)", "example": "

It would be great to have dark mode.

" }, "boardId": { "type": "string", "description": "Board ID to create post in", "example": "507f1f77bcf86cd799439011" }, "tags": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 50 } ], "description": "Tag names to attach", "example": [ "feature", "ui" ] }, "commentsEnabled": { "type": [ "boolean", "null" ], "default": true, "description": "Whether comments are enabled on this post", "example": true }, "statusId": { "type": "string", "description": "Status ID to set", "example": "507f1f77bcf86cd799439012" }, "author": { "$ref": "#/components/schemas/AuthorInput" }, "inReview": { "type": [ "boolean", "null" ], "default": false, "description": "Whether post is pending moderation", "example": false }, "customFields": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 100 }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "string", "maxLength": 10000 }, { "type": [ "string", "null" ] }, { "type": "null" }, { "type": "null" } ] }, "description": "Custom field values. Keys must be valid ObjectIds. Values can be: string, boolean, number, ISO date string, array of strings, ObjectId string, or null.", "example": { "507f1f77bcf86cd799439011": "high" } }, "eta": { "type": [ "string", "null" ], "description": "Estimated completion date", "example": "2025-12-31T23:59:59.000Z" }, "createdAt": { "type": [ "string", "null" ], "description": "Creation date (for backdating imports)", "example": "2025-01-15T10:30:00.000Z" }, "assigneeId": { "type": "string", "description": "Admin ID to assign this post to", "example": "507f1f77bcf86cd799439013" }, "visibility": { "type": "string", "enum": [ "public", "authorOnly", "companyOnly" ], "description": "Post visibility. 'public' = visible to all users, 'authorOnly' = only visible to the author and admins, 'companyOnly' = only visible to users in the same company as the author", "example": "public" }, "upvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Initial upvotes count. Defaults to 1 (post author is automatically added as voter). Use 0 to create a post without any votes.", "example": 5 }, "integrations": { "type": "object", "properties": { "linear": { "type": "boolean", "default": false, "description": "Push to Linear", "example": true }, "clickup": { "type": "boolean", "default": false, "description": "Push to ClickUp", "example": false }, "github": { "type": "boolean", "default": false, "description": "Push to GitHub", "example": false }, "jira": { "type": "boolean", "default": false, "description": "Push to Jira", "example": false }, "discord": { "type": "boolean", "default": false, "description": "Push to Discord", "example": false }, "slack": { "type": "boolean", "default": false, "description": "Push to Slack", "example": false } }, "default": {}, "description": "Push the created post to third-party integrations configured on your organization. Each integration must be explicitly set to true to trigger; omitted integrations will not be pushed to." } }, "required": [ "title", "boardId" ], "additionalProperties": false }, "UpdatePostBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 512, "description": "Post title", "example": "Updated: Add dark mode support" }, "content": { "type": "string", "description": "Post content (HTML)", "example": "

Updated content with more details.

" }, "boardId": { "type": "string", "description": "Board ID to move post to", "example": "507f1f77bcf86cd799439011" }, "tags": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 50 } ], "description": "Tag names to set (replaces existing)", "example": [ "feature", "ui" ] }, "commentsEnabled": { "type": [ "boolean", "null" ], "description": "Whether comments are enabled on this post", "example": true }, "statusId": { "type": "string", "description": "Status ID to set", "example": "507f1f77bcf86cd799439012" }, "inReview": { "type": [ "boolean", "null" ], "description": "Whether post is pending moderation", "example": false }, "customFields": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "array", "items": { "type": "string", "maxLength": 1000 }, "maxItems": 100 }, { "type": "boolean" }, { "type": "number" }, { "type": "string" }, { "type": "string", "maxLength": 10000 }, { "type": [ "string", "null" ] }, { "type": "null" }, { "type": "null" } ] }, "description": "Custom field values. Keys must be valid ObjectIds. Values can be: string, boolean, number, ISO date string, array of strings, ObjectId string, or null.", "example": { "507f1f77bcf86cd799439011": "high" } }, "eta": { "type": [ "string", "null" ], "description": "Estimated completion date (null to clear)", "example": "2025-12-31T23:59:59.000Z" }, "createdAt": { "type": [ "string", "null" ], "description": "Creation date (for backdating)", "example": "2025-01-15T10:30:00.000Z" }, "sendStatusUpdateEmail": { "type": [ "boolean", "null" ], "description": "Whether to send status update email to voters", "example": false }, "assigneeId": { "type": [ "string", "null" ], "description": "Admin ID to assign this post to (null to unassign)", "example": "507f1f77bcf86cd799439013" }, "visibility": { "type": "string", "enum": [ "public", "authorOnly", "companyOnly" ], "description": "Post visibility. 'public' = visible to all users, 'authorOnly' = only visible to the author and admins, 'companyOnly' = only visible to users in the same company as the author", "example": "public" }, "author": { "allOf": [ { "$ref": "#/components/schemas/AuthorInput" }, { "description": "Change the post author. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email. If user not found, a new user will be created." } ] }, "upvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Set the upvotes count directly. Use with caution as this overrides the actual vote count.", "example": 10 } }, "additionalProperties": false }, "DeletedPost": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted post", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "post" ], "description": "Object type identifier", "example": "post" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "Company": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "company" ], "description": "Object type identifier", "example": "company" }, "id": { "type": "string", "description": "Featurebase internal ID", "example": "507f1f77bcf86cd799439011" }, "companyId": { "type": "string", "description": "External company ID from your system", "example": "comp_12345" }, "name": { "type": "string", "description": "Company name", "example": "Acme Inc" }, "monthlySpend": { "type": [ "number", "null" ], "description": "Monthly spend", "example": 5000 }, "industry": { "type": [ "string", "null" ], "description": "Industry", "example": "Technology" }, "website": { "type": [ "string", "null" ], "description": "Company website URL", "example": "https://acme.com" }, "plan": { "type": [ "string", "null" ], "description": "Plan or tier name", "example": "enterprise" }, "linkedUsers": { "type": [ "number", "null" ], "description": "Number of users linked to this company", "example": 15 }, "companySize": { "type": [ "number", "null" ], "description": "Company employee headcount", "example": 250 }, "lastActivity": { "type": [ "string", "null" ], "description": "ISO date of last activity", "example": "2025-01-15T00:00:00.000Z" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Custom field values", "example": { "location": "Europe", "priority": "high" } }, "createdAt": { "type": [ "string", "null" ], "description": "ISO date when company was created", "example": "2025-01-01T12:00:00.000Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "ISO date when company was last updated", "example": "2025-01-10T15:30:00.000Z" } }, "required": [ "object", "id", "companyId", "name", "monthlySpend", "industry", "website", "plan", "linkedUsers", "companySize", "lastActivity", "createdAt", "updatedAt" ] }, "User": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier", "example": "676f0f6765bdaa7d7d760f88" }, "userId": { "type": "string", "description": "External user ID from SSO", "example": "676f0f673dbb299c8a4f3057" }, "organizationId": { "type": "string", "description": "Organization ID the user belongs to", "example": "5febde12dc56d60012d47db6" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "description": "Companies the user belongs to" }, "email": { "type": [ "string", "null" ], "description": "User email", "example": "john@example.com" }, "name": { "type": "string", "description": "User display name", "example": "John Steezy" }, "profilePicture": { "type": [ "string", "null" ], "description": "Profile picture URL", "example": "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png" }, "commentsCreated": { "type": "number", "description": "Number of comments created", "example": 0 }, "postsCreated": { "type": "number", "description": "Number of posts created", "example": 0 }, "lastActivity": { "type": "string", "description": "Last activity ISO timestamp", "example": "2025-01-03T21:42:30.181Z" }, "subscribedToChangelog": { "type": "boolean", "description": "Whether subscribed to changelog", "example": true }, "manuallyOptedOutFromChangelog": { "type": "boolean", "description": "Whether manually opted out from changelog", "example": false }, "roles": { "type": "array", "items": { "type": "string" }, "description": "User roles", "example": [] }, "locale": { "type": "string", "description": "User locale", "example": "en" }, "verified": { "type": "boolean", "description": "Whether email is verified", "example": true }, "type": { "type": "string", "enum": [ "admin", "customer", "guest", "integration", "bot", "lead" ], "description": "Type of user", "example": "customer" }, "description": { "type": "string", "description": "User description/bio", "example": "" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Custom field values on the user" } }, "required": [ "object", "id", "name", "type" ] }, "UserList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/User" }, "description": "Array of users", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" } }, "required": [ "object", "data", "nextCursor" ] }, "AddVoterResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "voter" ], "description": "Object type identifier", "example": "voter" }, "added": { "type": "boolean", "enum": [ true ], "description": "Indicates the voter was added", "example": true }, "id": { "type": "string", "description": "Voter unique identifier", "example": "507f1f77bcf86cd799439011" }, "postId": { "type": "string", "description": "Post ID the voter was added to", "example": "507f1f77bcf86cd799439012" } }, "required": [ "object", "added", "id", "postId" ] }, "AddVoterBody": { "type": "object", "properties": { "id": { "type": "string", "description": "Featurebase user ID to add as voter", "example": "507f1f77bcf86cd799439011" }, "userId": { "type": "string", "maxLength": 255, "description": "External user ID from your system (matched via SSO)", "example": "usr_12345" }, "email": { "type": "string", "format": "email", "description": "Voter email (used to find or create user)", "example": "john@example.com" }, "name": { "type": "string", "maxLength": 255, "description": "Voter display name (used when creating new user)", "example": "John Doe" }, "profilePicture": { "type": "string", "description": "Voter profile picture URL", "example": "https://example.com/avatar.png" } }, "additionalProperties": false }, "RemoveVoterResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "voter" ], "description": "Object type identifier", "example": "voter" }, "removed": { "type": "boolean", "enum": [ true ], "description": "Indicates the voter was removed", "example": true }, "id": { "type": "string", "description": "Voter unique identifier", "example": "507f1f77bcf86cd799439011" }, "postId": { "type": "string", "description": "Post ID the voter was removed from", "example": "507f1f77bcf86cd799439012" } }, "required": [ "object", "removed", "id", "postId" ] }, "RemoveVoterBody": { "type": "object", "properties": { "id": { "type": "string", "description": "Featurebase user ID to remove as voter", "example": "507f1f77bcf86cd799439011" }, "userId": { "type": "string", "maxLength": 255, "description": "External user ID from your system (matched via SSO)", "example": "usr_12345" }, "email": { "type": "string", "format": "email", "description": "Voter email to identify user", "example": "john@example.com" } }, "additionalProperties": false }, "PostStatusList": { "type": "array", "items": { "$ref": "#/components/schemas/PostStatus" } }, "CommentAuthor": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ], "description": "Author unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Author display name", "example": "John Doe" }, "profilePicture": { "type": [ "string", "null" ], "description": "Author profile picture URL", "example": "https://cdn.example.com/avatars/john.png" }, "type": { "type": "string", "enum": [ "admin", "customer", "guest", "integration", "bot", "lead" ], "description": "Type of user who authored the comment", "example": "customer" } }, "required": [ "id", "name", "profilePicture", "type" ] }, "Comment": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "comment" ], "description": "Object type identifier", "example": "comment" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "postId": { "type": [ "string", "null" ], "description": "Post ID this comment belongs to", "example": "507f1f77bcf86cd799439012" }, "changelogId": { "type": [ "string", "null" ], "description": "Changelog ID this comment belongs to", "example": "507f1f77bcf86cd799439013" }, "parentCommentId": { "type": [ "string", "null" ], "description": "Parent comment ID for replies, null for root comments", "example": "507f1f77bcf86cd799439014" }, "content": { "type": "string", "description": "Comment content in HTML format", "example": "

This is a great idea!

" }, "author": { "$ref": "#/components/schemas/CommentAuthor" }, "upvotes": { "type": "number", "description": "Number of upvotes", "example": 5 }, "downvotes": { "type": "number", "description": "Number of downvotes", "example": 0 }, "score": { "type": "number", "description": "Net score (upvotes - downvotes)", "example": 5 }, "isPrivate": { "type": "boolean", "description": "Whether the comment is private", "example": false }, "isDeleted": { "type": "boolean", "description": "Whether the comment is deleted", "example": false }, "isPinned": { "type": "boolean", "description": "Whether the comment is pinned", "example": false }, "inReview": { "type": "boolean", "description": "Whether the comment is in review", "example": false }, "isSpam": { "type": "boolean", "description": "Whether the comment is spam", "example": false }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2023-12-12T00:00:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when updated", "example": "2023-12-13T00:00:00.000Z" } }, "required": [ "object", "id", "postId", "changelogId", "parentCommentId", "content", "author", "upvotes", "downvotes", "score", "isPrivate", "isDeleted", "isPinned", "inReview", "isSpam", "createdAt", "updatedAt" ] }, "CommentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "description": "Array of comments", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" } }, "required": [ "object", "data", "nextCursor" ] }, "CreateCommentBody": { "type": "object", "properties": { "content": { "type": "string", "minLength": 2, "description": "Comment content in HTML format", "example": "

This is a great idea!

" }, "postId": { "type": "string", "description": "Post ID to comment on (accepts ObjectId or slug)", "example": "507f1f77bcf86cd799439011" }, "changelogId": { "type": "string", "description": "Changelog ID to comment on (accepts ObjectId or slug)", "example": "507f1f77bcf86cd799439012" }, "parentCommentId": { "type": "string", "description": "Parent comment ID if this is a reply", "example": "507f1f77bcf86cd799439013" }, "isPrivate": { "type": [ "boolean", "null" ], "default": false, "description": "Whether the comment is private (only visible to admins)", "example": false }, "sendNotification": { "type": [ "boolean", "null" ], "default": true, "description": "Whether to notify voters of the submission about the comment", "example": true }, "author": { "allOf": [ { "$ref": "#/components/schemas/AuthorInput" }, { "description": "Author to attribute the comment to. If not provided, uses the authenticated user. Supports multiple identification methods: id (Featurebase ID), userId (external SSO ID), or email." } ] }, "createdAt": { "type": [ "string", "null" ], "description": "Set the date when the comment was created. Useful for importing comments from other platforms.", "example": "2025-01-15T10:30:00.000Z" }, "upvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Initial upvotes count. Useful for importing comments from other platforms. Score will be calculated as upvotes - downvotes.", "example": 5 }, "downvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Initial downvotes count. Useful for importing comments from other platforms. Score will be calculated as upvotes - downvotes.", "example": 0 } }, "required": [ "content" ], "additionalProperties": false }, "UpdateCommentBody": { "type": "object", "properties": { "content": { "type": "string", "minLength": 2, "description": "Comment content in HTML format", "example": "

This is my updated comment.

" }, "isPrivate": { "type": [ "boolean", "null" ], "description": "Whether the comment is private (only visible to admins)", "example": false }, "isPinned": { "type": [ "boolean", "null" ], "description": "Whether the comment is pinned at the top", "example": true }, "inReview": { "type": [ "boolean", "null" ], "description": "Whether the comment is pending moderation review", "example": false }, "createdAt": { "type": [ "string", "null" ], "description": "Update the creation date (useful for imports)", "example": "2025-01-15T10:30:00.000Z" }, "upvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Set the upvotes count directly. Score will be recalculated as upvotes - downvotes.", "example": 10 }, "downvotes": { "type": [ "integer", "null" ], "minimum": 0, "description": "Set the downvotes count directly. Score will be recalculated as upvotes - downvotes.", "example": 2 } }, "additionalProperties": false }, "DeletedComment": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted comment", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "comment" ], "description": "Object type identifier", "example": "comment" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "ChangelogCategory": { "type": "object", "properties": { "id": { "type": "string", "description": "Category unique identifier", "example": "6438a1efda3640f8feb72121" }, "name": { "type": "string", "description": "Category name", "example": "New Features" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Roles allowed to view this category", "example": [] } }, "required": [ "id", "name" ] }, "ChangelogLocaleNotification": { "type": "object", "properties": { "sendEmailNotification": { "type": "boolean", "description": "Whether email notification should be sent for this locale", "example": true }, "hideFromBoardAndWidgets": { "type": "boolean", "description": "Whether the changelog is hidden from the board and widgets", "example": false }, "scheduledDate": { "type": [ "string", "null" ], "description": "Scheduled publication date as ISO 8601 timestamp", "example": "2024-01-15T12:00:00.000Z" }, "emailSent": { "type": "boolean", "description": "Whether the email notification has been sent", "example": true } }, "required": [ "scheduledDate" ] }, "Changelog": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "changelog" ], "description": "Object type identifier", "example": "changelog" }, "id": { "type": "string", "description": "Unique identifier", "example": "6457e3ff70afca5d8c27dccc" }, "title": { "type": "string", "description": "Changelog title", "example": "Your awesome changelog!" }, "slug": { "type": "string", "description": "URL-friendly slug", "example": "your-awesome-changelog" }, "url": { "type": "string", "description": "Public URL to view the changelog", "example": "https://myorg.featurebase.app/en/changelog/your-awesome-changelog" }, "content": { "type": "string", "description": "Content in HTML format", "example": "

Your changelog content in HTML format.

" }, "markdownContent": { "type": [ "string", "null" ], "description": "Content in markdown format", "example": "Your changelog content in markdown format." }, "featuredImage": { "type": [ "string", "null" ], "description": "Featured image URL", "example": "https://cdn.example.com/images/feature.png" }, "date": { "type": "string", "description": "Publication date as ISO 8601 timestamp", "example": "2023-05-07T12:59:59.000Z" }, "state": { "type": "string", "enum": [ "live", "draft" ], "description": "State of the changelog", "example": "live" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale of the changelog", "example": "en" }, "isPublished": { "type": "boolean", "description": "Whether the changelog is published (has a live version) in this locale", "example": true }, "isDraftDiffersFromLive": { "type": "boolean", "description": "Whether the draft content differs from the published live content", "example": false }, "publishedLocales": { "type": "array", "items": { "type": "string" }, "description": "Array of locale codes where the changelog is published", "example": [ "en", "de" ] }, "availableLocales": { "type": "array", "items": { "type": "string" }, "description": "Array of locale codes where the changelog has content", "example": [ "en", "de", "fr" ] }, "slugs": { "type": "object", "additionalProperties": { "type": "string" }, "description": "URL-friendly slugs for each locale", "example": { "en": "your-awesome-changelog", "de": "dein-tolles-changelog" } }, "commentCount": { "type": "number", "description": "Number of comments", "example": 2 }, "categories": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogCategory" }, "description": "Categories the changelog belongs to" }, "organization": { "type": "string", "description": "Organization identifier", "example": "myorg" }, "notifications": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ChangelogLocaleNotification" }, "description": "Notification settings for each locale" }, "allowedSegmentIds": { "type": "array", "items": { "type": "string" }, "description": "Segment IDs that are allowed to view this changelog", "example": [] }, "emailSentToSubscribers": { "type": "boolean", "description": "Whether email notification was sent to subscribers", "example": true }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2023-12-12T00:00:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when updated", "example": "2023-12-13T00:00:00.000Z" } }, "required": [ "object", "id", "title", "slug", "url", "content", "markdownContent", "featuredImage", "date", "state", "locale", "isPublished", "isDraftDiffersFromLive", "publishedLocales", "availableLocales", "slugs", "commentCount", "categories", "organization", "notifications", "allowedSegmentIds", "emailSentToSubscribers", "createdAt", "updatedAt" ] }, "ChangelogList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Changelog" }, "description": "Array of changelogs", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" } }, "required": [ "object", "data", "nextCursor" ] }, "CreateChangelogBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The title of the changelog", "example": "New Features Update" }, "htmlContent": { "type": "string", "description": "The HTML content of the changelog. Provide either htmlContent or markdownContent. For images, external URLs and base64 data URIs are automatically processed and stored.", "example": "

Exciting new features to explore.

" }, "markdownContent": { "type": "string", "description": "The markdown content of the changelog. Provide either htmlContent or markdownContent. For images, external URLs and base64 data URIs are automatically processed and stored.", "example": "Exciting new features to explore." }, "categories": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 100, "description": "An array of category names to which the changelog belongs", "example": [ "New", "Fixed", "Improved" ] }, "featuredImage": { "type": "string", "description": "The URL of the featured image for the changelog. External URLs will be uploaded to our storage.", "example": "https://example.com/image.png" }, "allowedSegmentIds": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "An array of segment IDs that are allowed to view the changelog", "example": [ "507f1f77bcf86cd799439011" ] }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "The locale of the changelog, defaulting to the organization default locale", "example": "en" }, "date": { "type": [ "string", "null" ], "description": "The date of the changelog", "example": "2024-01-15" }, "state": { "type": "string", "enum": [ "draft", "live" ], "default": "draft", "description": "The state of the changelog (draft or live)", "example": "draft" } }, "required": [ "title" ], "additionalProperties": false }, "UpdateChangelogBody": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The title of the changelog", "example": "Updated Features Release" }, "htmlContent": { "type": "string", "description": "The HTML content of the changelog. Provide either htmlContent or markdownContent. For images, external URLs and base64 data URIs are automatically processed and stored.", "example": "

Updated features to explore.

" }, "markdownContent": { "type": "string", "description": "The markdown content of the changelog. Provide either htmlContent or markdownContent. For images, external URLs and base64 data URIs are automatically processed and stored.", "example": "Updated features to explore." }, "categories": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 100, "description": "An array of category names to which the changelog belongs", "example": [ "New", "Fixed", "Improved" ] }, "featuredImage": { "type": "string", "description": "The URL of the featured image for the changelog. External URLs will be uploaded to our storage.", "example": "https://example.com/image.png" }, "allowedSegmentIds": { "type": "array", "items": { "type": "string" }, "maxItems": 100, "description": "An array of segment IDs that are allowed to view the changelog", "example": [ "507f1f77bcf86cd799439011" ] }, "date": { "type": [ "string", "null" ], "description": "The date of the changelog", "example": "2024-01-15" } }, "additionalProperties": false }, "DeletedChangelog": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted changelog", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "changelog" ], "description": "Object type identifier", "example": "changelog" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "PublishUnpublishSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "description": "Indicates the operation was successful", "example": true }, "state": { "type": "string", "enum": [ "published", "scheduled", "unpublished" ], "description": "The state of the changelog after the operation", "example": "published" } }, "required": [ "success" ] }, "PublishChangelogBody": { "type": "object", "properties": { "sendEmail": { "type": [ "boolean", "null" ], "default": false, "description": "A flag indicating whether to send an email notification to subscribers.", "example": true }, "locales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "default": [], "description": "An array of locales to publish the changelog to. An empty array publishes to all locales.", "example": [ "en", "de" ] }, "scheduledDate": { "anyOf": [ { "type": "string" }, { "type": "null" }, { "type": "null" } ], "description": "The date when the changelog should be published. Must be a future date. Pass null or omit to publish immediately.", "example": "2023-12-01T00:00:00Z" } }, "additionalProperties": false }, "UnpublishChangelogBody": { "type": "object", "properties": { "locales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "default": [], "description": "An array of locales to unpublish the changelog from. An empty array unpublishes from all locales.", "example": [ "en" ] } }, "additionalProperties": false }, "ChangelogSubscribersImport": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "changelog_subscribers_import" ], "description": "Object type identifier", "example": "changelog_subscribers_import" }, "count": { "type": "number", "description": "Number of email addresses processed", "example": 150 } }, "required": [ "object", "count" ] }, "AddChangelogSubscribersBody": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 1000, "description": "Array of email addresses to add as changelog subscribers", "example": [ "john@example.com", "jane@example.com" ] }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "The locale for the subscribers. Defaults to organization default locale.", "example": "en" } }, "required": [ "emails" ], "additionalProperties": false }, "ChangelogSubscribersRemoval": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "changelog_subscribers_removal" ], "description": "Object type identifier", "example": "changelog_subscribers_removal" }, "count": { "type": "number", "description": "Number of email addresses processed", "example": 150 } }, "required": [ "object", "count" ] }, "RemoveChangelogSubscribersBody": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1, "maxItems": 1000, "description": "Array of email addresses to remove from changelog subscribers", "example": [ "john@example.com", "jane@example.com" ] } }, "required": [ "emails" ], "additionalProperties": false }, "Admin": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "admin" ], "description": "Object type identifier", "example": "admin" }, "id": { "type": "string", "description": "Unique identifier", "example": "5fef50c5e9458a0012f82456" }, "name": { "type": "string", "description": "Admin display name", "example": "John Doe" }, "email": { "type": "string", "description": "Admin email address", "example": "john@example.com" }, "profilePicture": { "type": [ "string", "null" ], "description": "Profile picture URL", "example": "https://example.com/avatar.png" }, "roleId": { "type": "string", "description": "Role ID assigned to this admin", "example": "6648f22b7b23fb2f4307aafe" } }, "required": [ "object", "id" ] }, "AdminList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Admin" }, "description": "Array of admins", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" } }, "required": [ "object", "data", "nextCursor" ] }, "AdminRolePermissions": { "type": "object", "properties": { "view_comments_private": { "type": "boolean", "description": "View private comments", "example": false }, "manage_comments": { "type": "boolean", "description": "Manage comments", "example": true }, "manage_comments_private": { "type": "boolean", "description": "Manage private comments", "example": false }, "set_comment_pinned": { "type": "boolean", "description": "Pin/unpin comments", "example": true }, "moderate_comments": { "type": "boolean", "description": "Moderate comments", "example": true }, "set_post_category": { "type": "boolean", "description": "Set post category/board", "example": true }, "set_post_pinned": { "type": "boolean", "description": "Pin/unpin posts", "example": true }, "set_post_eta": { "type": "boolean", "description": "Set post ETA", "example": true }, "set_post_tags": { "type": "boolean", "description": "Set post tags", "example": true }, "set_post_author": { "type": "boolean", "description": "Set post author", "example": true }, "set_post_status": { "type": "boolean", "description": "Set post status", "example": true }, "set_post_assignee": { "type": "boolean", "description": "Assign posts", "example": true }, "set_post_custom_fields": { "type": "boolean", "description": "Set post custom fields", "example": true }, "post_vote_on_behalf": { "type": "boolean", "description": "Vote on posts on behalf of users", "example": false }, "post_merge": { "type": "boolean", "description": "Merge posts", "example": true }, "post_import": { "type": "boolean", "description": "Import posts", "example": false }, "post_export": { "type": "boolean", "description": "Export posts", "example": true }, "moderate_posts": { "type": "boolean", "description": "Moderate posts", "example": true }, "view_users": { "type": "boolean", "description": "View users", "example": true }, "manage_users": { "type": "boolean", "description": "Manage users", "example": true }, "view_posts_private": { "type": "boolean", "description": "View private posts", "example": false }, "view_private_post_tags": { "type": "boolean", "description": "View private post tags", "example": false }, "manage_changelogs": { "type": "boolean", "description": "Manage changelogs", "example": true }, "manage_surveys": { "type": "boolean", "description": "Manage surveys", "example": true }, "manage_branding": { "type": "boolean", "description": "Manage branding", "example": false }, "manage_billing": { "type": "boolean", "description": "Manage billing", "example": false }, "manage_team_members": { "type": "boolean", "description": "Manage team members", "example": true }, "manage_sso": { "type": "boolean", "description": "Manage SSO", "example": false }, "manage_api": { "type": "boolean", "description": "Manage API settings", "example": false }, "manage_statuses": { "type": "boolean", "description": "Manage post statuses", "example": true }, "manage_boards": { "type": "boolean", "description": "Manage boards", "example": true }, "manage_post_tags": { "type": "boolean", "description": "Manage post tags", "example": true }, "manage_custom_fields": { "type": "boolean", "description": "Manage custom fields", "example": true }, "manage_moderation_settings": { "type": "boolean", "description": "Manage moderation settings", "example": true }, "manage_roadmap": { "type": "boolean", "description": "Manage roadmap", "example": true }, "manage_user_roles": { "type": "boolean", "description": "Manage user roles", "example": true }, "manage_prioritization": { "type": "boolean", "description": "Manage prioritization", "example": true }, "manage_notifications": { "type": "boolean", "description": "Manage notifications", "example": true }, "manage_custom_domain": { "type": "boolean", "description": "Manage custom domain", "example": false }, "manage_integrations": { "type": "boolean", "description": "Manage integrations", "example": false }, "use_integrations": { "type": "boolean", "description": "Use integrations", "example": true }, "manage_help_center": { "type": "boolean", "description": "Manage help center", "example": true }, "auto_approve_posts": { "type": "boolean", "description": "Auto-approve posts", "example": false } }, "description": "Role permissions" }, "AdminRole": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "admin_role" ], "description": "Object type identifier", "example": "admin_role" }, "id": { "type": "string", "description": "Role unique identifier", "example": "6648f22b7b23fb2f4307aafe" }, "name": { "type": "string", "description": "Role name", "example": "Admin" }, "permissions": { "$ref": "#/components/schemas/AdminRolePermissions" } }, "required": [ "object", "id", "name", "permissions" ] }, "AdminRoleList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AdminRole" }, "description": "Array of admin roles", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "CustomFieldOption": { "type": "object", "properties": { "id": { "type": "string", "description": "Option unique identifier", "example": "65d26304b2e65b1e1278170d" }, "label": { "type": "string", "description": "Option display label", "example": "High Priority" } }, "required": [ "id", "label" ] }, "CustomField": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "custom_field" ], "description": "Object type identifier", "example": "custom_field" }, "id": { "type": "string", "description": "Unique identifier", "example": "65d26304b2e65b1e1278170c" }, "label": { "type": "string", "description": "Field label displayed to users", "example": "Your @username" }, "type": { "type": "string", "enum": [ "text", "number", "select", "multi-select", "checkbox", "date" ], "description": "Field type", "example": "text" }, "required": { "type": "boolean", "description": "Whether the field is required", "example": true }, "placeholder": { "type": "string", "description": "Placeholder text", "example": "Enter your username" }, "public": { "type": "boolean", "description": "Whether the field value is publicly visible", "example": false }, "internal": { "type": "boolean", "description": "Whether the field is for internal use only", "example": false }, "options": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldOption" }, "description": "Options for select/multi-select fields", "example": [ { "id": "65d26304b2e65b1e1278170d", "label": "High Priority" } ] }, "createdAt": { "type": "string", "description": "ISO timestamp when created", "example": "2025-04-06T14:11:58.141Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when last updated", "example": "2025-04-06T14:11:58.141Z" } }, "required": [ "object", "id", "label", "type" ] }, "CustomFieldList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" }, "description": "Array of custom fields", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null }, "pagination": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Items per page", "example": 10 }, "total": { "type": "number", "description": "Total number of items", "example": 42 }, "totalPages": { "type": "number", "description": "Total number of pages", "example": 5 } }, "required": [ "page", "limit", "total", "totalPages" ], "description": "Pagination metadata for page-based requests" } }, "required": [ "object", "data", "nextCursor" ] }, "SurveyUrlTargeting": { "type": "object", "properties": { "value": { "type": "string", "description": "URL pattern to match", "example": "/dashboard/posts" }, "matchType": { "type": "string", "enum": [ "exact", "contains", "regex" ], "description": "Type of URL matching", "example": "contains" }, "id": { "type": "string", "description": "Rule ID", "example": "674375cfd8bf964ec2562cdc" } }, "required": [ "value", "matchType" ] }, "SurveyCssTargeting": { "type": "object", "properties": { "value": { "type": "string", "description": "CSS selector", "example": ".feedback-button" } }, "required": [ "value" ] }, "SurveyTargeting": { "type": "object", "properties": { "segmentIds": { "type": "array", "items": { "type": "string" }, "description": "Segment IDs to target", "example": [ "6636438b7fcdc515999042eb" ] }, "url": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyUrlTargeting" }, "description": "URL targeting rules" }, "css": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyCssTargeting" }, "description": "CSS selector targeting rules" }, "loginRequired": { "type": "boolean", "description": "Whether login is required", "example": false } }, "description": "Targeting configuration" }, "SurveyChoice": { "type": "object", "properties": { "id": { "type": "string", "description": "Choice ID", "example": "66dc54128b989696d050008b" }, "choice": { "type": "string", "description": "Choice text", "example": "Very satisfied" } }, "required": [ "id" ] }, "SurveyNextAction": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "page", "end", "next" ], "description": "Type of next action", "example": "page" }, "pageId": { "type": "string", "description": "Page ID to navigate to", "example": "6743754dd8bf964ec2562cda" } }, "required": [ "type" ], "description": "Action to take if condition matches" }, "SurveyPageLogic": { "type": "object", "properties": { "id": { "type": "string", "description": "Logic rule ID", "example": "6743755fd8bf964ec2562cdb" }, "comparator": { "type": "string", "description": "Comparison operator", "example": "less than" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "items": { "type": "string" } } ], "description": "Value to compare against", "example": 4 }, "next": { "$ref": "#/components/schemas/SurveyNextAction" } }, "required": [ "comparator", "value", "next" ] }, "SurveyPage": { "type": "object", "properties": { "id": { "type": "string", "description": "Page ID", "example": "6743752ca81ae59d25cf834c" }, "type": { "type": "string", "enum": [ "text", "link", "rating", "multiple-choice" ], "description": "Page type", "example": "rating" }, "title": { "type": "string", "description": "Page title", "example": "How happy are you with our product?" }, "description": { "type": "string", "description": "Page description", "example": "We really want to hear from you." }, "placeholder": { "type": "string", "description": "Placeholder for text input", "example": "Type your answer here" }, "linkButtonText": { "type": "string", "description": "Button text for link", "example": "Visit our website" }, "linkRedirectUrl": { "type": "string", "description": "URL to redirect to", "example": "https://example.com" }, "linkTarget": { "type": "string", "enum": [ "_blank", "_self", "_parent", "_top" ], "description": "Link target", "example": "_blank" }, "subType": { "type": "string", "enum": [ "number", "emoji", "generic", "featurebase-posts", "nps" ], "description": "Sub-type for rating/multiple-choice", "example": "emoji" }, "scale": { "type": "number", "description": "Rating scale", "example": 5 }, "lowLabel": { "type": "string", "description": "Label for low rating", "example": "Could be improved" }, "highLabel": { "type": "string", "description": "Label for high rating", "example": "It's awesome!" }, "allowSelectMultiple": { "type": "boolean", "description": "Allow multiple selections", "example": false }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyChoice" }, "description": "Available choices" }, "logic": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPageLogic" }, "description": "Conditional logic rules" }, "defaultAction": { "allOf": [ { "$ref": "#/components/schemas/SurveyNextAction" }, { "description": "Default action if no logic matches" } ] } }, "required": [ "id", "type", "title" ] }, "Survey": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "survey" ], "description": "Object type identifier", "example": "survey" }, "id": { "type": "string", "description": "Unique identifier", "example": "6743752ca81ae59d25cf834b" }, "title": { "type": "string", "description": "Survey title", "example": "Get feedback for Feedback module" }, "description": { "type": "string", "description": "Survey description", "example": "Measure what we can improve" }, "isActive": { "type": "boolean", "description": "Whether the survey is active", "example": true }, "organization": { "type": "string", "description": "Organization ID", "example": "5febde12dc56d60012d47db6" }, "responseCount": { "type": "number", "description": "Number of responses", "example": 85 }, "targeting": { "$ref": "#/components/schemas/SurveyTargeting" }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyPage" }, "description": "Survey pages", "example": [] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-11-24T18:49:16.755Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last updated", "example": "2025-04-10T08:58:51.148Z" } }, "required": [ "object", "id", "title", "isActive", "organization", "responseCount", "pages", "createdAt", "updatedAt" ] }, "SurveyList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Survey" }, "description": "Array of surveys", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "Contact": { "type": [ "object", "null" ], "properties": { "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier", "example": "contact" }, "id": { "type": "string", "description": "Unique identifier", "example": "676f0f6765bdaa7d7d760f88" }, "userId": { "type": "string", "description": "External user ID from SSO", "example": "676f0f673dbb299c8a4f3057" }, "organizationId": { "type": "string", "description": "Organization ID the contact belongs to", "example": "5febde12dc56d60012d47db6" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "description": "Companies the contact belongs to", "example": [] }, "email": { "type": [ "string", "null" ], "description": "Contact email", "example": "john@example.com" }, "name": { "type": "string", "description": "Contact display name", "example": "John Steezy" }, "profilePicture": { "type": [ "string", "null" ], "description": "Profile picture URL", "example": "https://fb-usercontent.fra1.cdn.digitaloceanspaces.com/anon_23.png" }, "commentsCreated": { "type": "number", "description": "Number of comments created", "example": 0 }, "postsCreated": { "type": "number", "description": "Number of posts created", "example": 0 }, "lastActivity": { "type": "string", "description": "Last activity ISO timestamp", "example": "2025-01-03T21:42:30.181Z" }, "subscribedToChangelog": { "type": "boolean", "description": "Whether subscribed to changelog", "example": true }, "manuallyOptedOutFromChangelog": { "type": "boolean", "description": "Whether manually opted out from changelog", "example": false }, "roles": { "type": "array", "items": { "type": "string" }, "description": "Contact roles", "example": [] }, "locale": { "type": "string", "description": "Contact locale", "example": "en" }, "verified": { "type": "boolean", "description": "Whether email is verified", "example": true }, "type": { "type": "string", "enum": [ "customer", "lead" ], "description": "Type of contact", "example": "customer" }, "description": { "type": "string", "description": "Contact description/bio", "example": "" }, "customFields": { "type": "object", "additionalProperties": {}, "description": "Custom field values on the contact" } }, "required": [ "object", "id", "name", "type" ], "description": "User who submitted the response" }, "SurveySingleResponse": { "type": "object", "properties": { "pageId": { "type": "string", "description": "Page ID this response is for", "example": "66dc53c5a64824f0e84a4c1e" }, "type": { "type": "string", "enum": [ "text", "link", "rating", "multiple-choice" ], "description": "Response type", "example": "multiple-choice" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ], "description": "Response value", "example": [ "66dc54128b989696d050008b" ] }, "id": { "type": "string", "description": "Response ID", "example": "6712e2d175904ce24b2f9638" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-10-18T22:36:01.270Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when updated", "example": "2024-10-18T22:36:01.270Z" } }, "required": [ "pageId", "type", "value" ] }, "SurveyResponse": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "survey_response" ], "description": "Object type identifier", "example": "survey_response" }, "id": { "type": "string", "description": "Unique identifier", "example": "6712e2d175904ce24b2f9637" }, "user": { "$ref": "#/components/schemas/Contact" }, "responses": { "type": "array", "items": { "$ref": "#/components/schemas/SurveySingleResponse" }, "description": "Individual responses to questions", "example": [] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-10-18T22:36:01.269Z" } }, "required": [ "object", "id", "user", "responses", "createdAt" ] }, "SurveyResponseList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SurveyResponse" }, "description": "Array of survey responses", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "HelpCenterNavItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "link", "button" ], "description": "Navigation item type", "example": "link" }, "title": { "type": "string", "description": "Navigation item title", "example": "Developer Docs" }, "url": { "type": "string", "description": "Navigation item URL", "example": "https://developers.featurebase.app/install" }, "icon": { "type": [ "string", "null" ], "description": "Navigation item icon", "example": null } }, "required": [ "type", "title", "url" ] }, "HelpCenterUrls": { "type": "object", "properties": { "featurebaseSubpath": { "type": "string", "description": "Featurebase subpath", "example": "/help" }, "externalDomain": { "type": "string", "description": "External custom domain", "example": "help.example.com" } }, "description": "URLs configuration" }, "HelpCenterTranslation": { "type": "object", "properties": { "displayName": { "type": "string", "description": "Display name for this locale", "example": "My English Help Center" }, "title": { "type": "string", "description": "Title for this locale", "example": "Help Center" }, "description": { "type": "string", "description": "Description for this locale", "example": "Find answers to common questions" }, "searchPlaceholder": { "type": "string", "description": "Search placeholder for this locale", "example": "Search articles..." }, "navItems": { "type": "array", "items": { "$ref": "#/components/schemas/HelpCenterNavItem" }, "description": "Navigation items for this locale" } } }, "HelpCenter": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "help_center" ], "description": "Object type identifier", "example": "help_center" }, "id": { "type": "string", "description": "Help center unique identifier", "example": "2tgy0ig982j54qfl" }, "displayName": { "type": "string", "description": "Help center display name", "example": "Your Help Center" }, "title": { "type": "string", "description": "Help center title", "example": "Help Center" }, "description": { "type": "string", "description": "Help center description", "example": "" }, "searchPlaceholder": { "type": "string", "description": "Search input placeholder", "example": "Search for help..." }, "isPublic": { "type": "boolean", "description": "Whether the help center is public", "example": true }, "hideAuthorInfo": { "type": "boolean", "description": "Whether to hide author info on articles", "example": false }, "hideDateInfo": { "type": "boolean", "description": "Whether to hide date info on articles", "example": false }, "externalLinksOpenInNewTab": { "type": "boolean", "description": "Whether external links in articles open in a new tab", "example": true }, "internalLinksOpenInNewTab": { "type": "boolean", "description": "Whether internal links in articles open in a new tab", "example": false }, "defaultLocale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Default locale for the help center", "example": "en" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Current locale", "example": "en" }, "availableLocales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "description": "Available locales", "example": [ "en" ] }, "navItems": { "type": "array", "items": { "$ref": "#/components/schemas/HelpCenterNavItem" }, "description": "Navigation items" }, "urls": { "$ref": "#/components/schemas/HelpCenterUrls" }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "bs": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "pt-BR": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "bg": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ca": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "hr": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "cs": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "da": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "nl": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "en": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "et": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "fi": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "fr": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "de": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "el": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "hi": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "hu": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "id": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "it": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ja": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ko": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "lv": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "lt": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ms": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "mn": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "nb": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "pl": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "pt": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ro": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "ru": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "sr": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "zh-CN": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "sk": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "sl": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "es": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "sw": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "sv": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "th": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "zh-TW": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "tr": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "uk": { "$ref": "#/components/schemas/HelpCenterTranslation" }, "vi": { "$ref": "#/components/schemas/HelpCenterTranslation" } }, "description": "Translations for different locales" }, "organization": { "type": "string", "description": "Organization ID", "example": "6595518396205e06b897ad65" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-06-26T13:27:21.920Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last updated", "example": "2024-06-26T13:52:19.415Z" } }, "required": [ "object", "id", "isPublic", "defaultLocale", "locale", "availableLocales", "organization", "createdAt", "updatedAt" ] }, "HelpCenterList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/HelpCenter" }, "description": "Array of help centers", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "CollectionIcon": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "description": "Icon type", "example": "emoji" }, "value": { "type": "string", "description": "Icon value", "example": "🥾" } }, "required": [ "type", "value" ], "description": "Collection icon" }, "CollectionAuthor": { "type": "object", "properties": { "name": { "type": "string", "description": "Author name", "example": "John Doe" }, "authorId": { "type": "string", "description": "Author ID", "example": "507f1f77bcf86cd799439011" }, "avatarUrl": { "type": [ "string", "null" ], "description": "Author avatar URL", "example": "https://example.com/avatar.png" } } }, "CollectionTranslation": { "type": "object", "properties": { "name": { "type": "string", "description": "Collection name", "example": "English Collection" }, "description": { "type": "string", "description": "Collection description", "example": "A collection of articles" }, "slug": { "type": "string", "description": "URL slug", "example": "3416135-english-collection" }, "featurebaseUrl": { "type": "string", "description": "Featurebase URL", "example": "https://yourorg.featurebase.app/en/help/collections/3416135-english-collection" }, "externalUrl": { "type": "string", "description": "External URL", "example": "https://help.yourdomain.com/en/collections/3416135-english-collection" }, "articleCount": { "type": "number", "description": "Number of articles", "example": 15 }, "authorCount": { "type": "number", "description": "Number of authors", "example": 3 }, "authors": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionAuthor" }, "description": "List of authors" } } }, "Collection": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "collection" ], "description": "Object type identifier", "example": "collection" }, "id": { "type": "string", "description": "Collection unique identifier", "example": "6474684" }, "name": { "type": "string", "description": "Collection name", "example": "English Collection Name" }, "description": { "type": "string", "description": "Collection description", "example": "A description in English" }, "slug": { "type": "string", "description": "URL slug", "example": "6474684-english-version" }, "icon": { "$ref": "#/components/schemas/CollectionIcon" }, "parentId": { "type": [ "string", "null" ], "description": "Parent collection ID", "example": null }, "helpCenterId": { "type": "string", "description": "Help center ID", "example": "j7c5g8ah3ewxp4lo" }, "organization": { "type": "string", "description": "Organization ID", "example": "6595518396205e06b897ad65" }, "defaultLocale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Default locale", "example": "en" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Current locale", "example": "en" }, "availableLocales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "description": "Available locales", "example": [ "en", "de" ] }, "featurebaseUrl": { "type": "string", "description": "Featurebase URL", "example": "https://yourorg.featurebase.app/en/help/collections/6474684-english-version" }, "externalUrl": { "type": "string", "description": "External URL", "example": "https://help.yourdomain.com/en/collections/6474684-english-version" }, "articleCount": { "type": "number", "description": "Number of articles", "example": 15 }, "authorCount": { "type": "number", "description": "Number of authors", "example": 3 }, "order": { "type": [ "number", "null" ], "description": "Display order", "example": 1 }, "path": { "type": "string", "description": "Collection path", "example": "ox6qrqprmsuqaunj/3876752/3513543" }, "collapseSidebar": { "type": "boolean", "description": "Whether to collapse sidebar", "example": false }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/CollectionTranslation" }, "bs": { "$ref": "#/components/schemas/CollectionTranslation" }, "pt-BR": { "$ref": "#/components/schemas/CollectionTranslation" }, "bg": { "$ref": "#/components/schemas/CollectionTranslation" }, "ca": { "$ref": "#/components/schemas/CollectionTranslation" }, "hr": { "$ref": "#/components/schemas/CollectionTranslation" }, "cs": { "$ref": "#/components/schemas/CollectionTranslation" }, "da": { "$ref": "#/components/schemas/CollectionTranslation" }, "nl": { "$ref": "#/components/schemas/CollectionTranslation" }, "en": { "$ref": "#/components/schemas/CollectionTranslation" }, "et": { "$ref": "#/components/schemas/CollectionTranslation" }, "fi": { "$ref": "#/components/schemas/CollectionTranslation" }, "fr": { "$ref": "#/components/schemas/CollectionTranslation" }, "de": { "$ref": "#/components/schemas/CollectionTranslation" }, "el": { "$ref": "#/components/schemas/CollectionTranslation" }, "hi": { "$ref": "#/components/schemas/CollectionTranslation" }, "hu": { "$ref": "#/components/schemas/CollectionTranslation" }, "id": { "$ref": "#/components/schemas/CollectionTranslation" }, "it": { "$ref": "#/components/schemas/CollectionTranslation" }, "ja": { "$ref": "#/components/schemas/CollectionTranslation" }, "ko": { "$ref": "#/components/schemas/CollectionTranslation" }, "lv": { "$ref": "#/components/schemas/CollectionTranslation" }, "lt": { "$ref": "#/components/schemas/CollectionTranslation" }, "ms": { "$ref": "#/components/schemas/CollectionTranslation" }, "mn": { "$ref": "#/components/schemas/CollectionTranslation" }, "nb": { "$ref": "#/components/schemas/CollectionTranslation" }, "pl": { "$ref": "#/components/schemas/CollectionTranslation" }, "pt": { "$ref": "#/components/schemas/CollectionTranslation" }, "ro": { "$ref": "#/components/schemas/CollectionTranslation" }, "ru": { "$ref": "#/components/schemas/CollectionTranslation" }, "sr": { "$ref": "#/components/schemas/CollectionTranslation" }, "zh-CN": { "$ref": "#/components/schemas/CollectionTranslation" }, "sk": { "$ref": "#/components/schemas/CollectionTranslation" }, "sl": { "$ref": "#/components/schemas/CollectionTranslation" }, "es": { "$ref": "#/components/schemas/CollectionTranslation" }, "sw": { "$ref": "#/components/schemas/CollectionTranslation" }, "sv": { "$ref": "#/components/schemas/CollectionTranslation" }, "th": { "$ref": "#/components/schemas/CollectionTranslation" }, "zh-TW": { "$ref": "#/components/schemas/CollectionTranslation" }, "tr": { "$ref": "#/components/schemas/CollectionTranslation" }, "uk": { "$ref": "#/components/schemas/CollectionTranslation" }, "vi": { "$ref": "#/components/schemas/CollectionTranslation" } }, "description": "Translations by locale code" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-10-18T12:33:09.099Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last updated", "example": "2024-10-18T13:03:25.921Z" } }, "required": [ "object", "id", "parentId", "helpCenterId", "organization", "locale", "availableLocales", "createdAt", "updatedAt" ] }, "CollectionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" }, "description": "Array of collections", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "CollectionIcon_Nova": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "emoji", "predefined" ], "description": "Icon type (e.g., \"emoji\")", "example": "emoji" }, "value": { "type": "string", "maxLength": 255, "description": "Icon value", "example": "📝" } }, "required": [ "type", "value" ], "description": "An updated icon object for the collection" }, "CollectionTranslationInput_Nova": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Collection name in this locale", "example": "German Collection" }, "description": { "type": "string", "maxLength": 512, "description": "Collection description in this locale", "example": "This is a collection of articles in German." } } }, "UpdateCollectionBody_Nova": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "The new name of the collection", "example": "Updated Collection" }, "description": { "type": "string", "maxLength": 512, "description": "The new description of the collection", "example": "Updated description in English." }, "icon": { "$ref": "#/components/schemas/CollectionIcon_Nova" }, "parentId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The new parent collection ID, if applicable", "example": null }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "bs": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pt-BR": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "bg": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ca": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "cs": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "da": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "nl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "en": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "et": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "fi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "fr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "de": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "el": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hu": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "id": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "it": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ja": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ko": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "lv": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "lt": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ms": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "mn": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "nb": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pt": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ro": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ru": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "zh-CN": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sk": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "es": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sw": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sv": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "th": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "zh-TW": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "tr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "uk": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "vi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" } }, "description": "A dictionary of updated translations keyed by locale" } }, "additionalProperties": false }, "CreateCollectionBody_Nova": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255, "description": "The name of the collection", "example": "English Collection" }, "description": { "type": "string", "maxLength": 512, "description": "A description of the collection", "example": "This is a collection of articles in English." }, "icon": { "allOf": [ { "$ref": "#/components/schemas/CollectionIcon_Nova" }, { "description": "An icon object representing the collection icon" } ] }, "parentId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The ID of the parent collection, if any", "example": null }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "bs": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pt-BR": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "bg": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ca": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "cs": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "da": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "nl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "en": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "et": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "fi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "fr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "de": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "el": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "hu": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "id": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "it": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ja": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ko": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "lv": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "lt": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ms": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "mn": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "nb": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "pt": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ro": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "ru": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "zh-CN": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sk": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sl": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "es": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sw": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "sv": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "th": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "zh-TW": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "tr": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "uk": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" }, "vi": { "$ref": "#/components/schemas/CollectionTranslationInput_Nova" } }, "description": "A dictionary of translations keyed by locale" } }, "required": [ "name" ], "additionalProperties": false }, "DeletedCollection": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted collection", "example": "3416135" }, "object": { "type": "string", "enum": [ "collection" ], "description": "Object type identifier", "example": "collection" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "ArticleIcon": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "emoji", "custom" ], "description": "Icon type", "example": "emoji" }, "value": { "type": "string", "description": "Icon value (emoji or URL)", "example": "📖" } }, "required": [ "type", "value" ], "description": "Article icon" }, "ArticleAuthor": { "type": "object", "properties": { "name": { "type": "string", "description": "Author name", "example": "John Doe" }, "authorId": { "type": "string", "description": "Author user ID", "example": "507f1f77bcf86cd799439011" }, "avatarUrl": { "type": [ "string", "null" ], "description": "Author avatar URL", "example": null } }, "required": [ "name", "authorId" ], "description": "Article author" }, "ArticleTranslation": { "type": "object", "properties": { "title": { "type": "string", "description": "Article title", "example": "Getting Started Guide" }, "description": { "type": "string", "description": "Article description", "example": "Learn how to get started" }, "body": { "type": "string", "description": "Article body content (HTML)", "example": "

Welcome to our guide.

" }, "slug": { "type": "string", "description": "URL slug", "example": "1234567-getting-started-guide" }, "featurebaseUrl": { "type": "string", "description": "Featurebase URL", "example": "https://yourorg.featurebase.app/en/help/articles/1234567-getting-started-guide" }, "externalUrl": { "type": "string", "description": "External URL", "example": "https://help.yourdomain.com/en/articles/1234567-getting-started-guide" }, "author": { "allOf": [ { "$ref": "#/components/schemas/ArticleAuthor" }, { "description": "Article author for this translation" } ] }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when translation was created", "example": "2024-10-18T12:33:09.099Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when translation was last updated", "example": "2024-10-19T14:22:15.123Z" } } }, "Article": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "article" ], "description": "Object type identifier", "example": "article" }, "id": { "type": "string", "description": "Article unique identifier", "example": "1234567" }, "title": { "type": "string", "description": "Article title", "example": "Getting Started Guide" }, "description": { "type": "string", "description": "Article description", "example": "Learn how to get started" }, "body": { "type": "string", "description": "Article body content (HTML)", "example": "

Welcome to our guide.

" }, "slug": { "type": "string", "description": "URL slug", "example": "1234567-getting-started-guide" }, "icon": { "$ref": "#/components/schemas/ArticleIcon" }, "parentId": { "type": [ "string", "null" ], "description": "Parent collection ID", "example": "6474684" }, "helpCenterId": { "type": "string", "description": "Help Center ID", "example": "j7c5g8ah3ewxp4lo" }, "organization": { "type": "string", "description": "Organization ID", "example": "6595518396205e06b897ad65" }, "state": { "type": "string", "enum": [ "live", "draft" ], "description": "Article state", "example": "live" }, "defaultLocale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Default locale", "example": "en" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Current locale", "example": "en" }, "availableLocales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "description": "Available locales", "example": [ "en", "de" ] }, "publishedLocales": { "type": "array", "items": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for localized content", "example": "en" }, "description": "Published locales", "example": [ "en" ] }, "featurebaseUrl": { "type": "string", "description": "Featurebase URL", "example": "https://yourorg.featurebase.app/en/help/articles/1234567-getting-started-guide" }, "externalUrl": { "type": "string", "description": "External URL", "example": "https://help.yourdomain.com/en/articles/1234567-getting-started-guide" }, "author": { "$ref": "#/components/schemas/ArticleAuthor" }, "order": { "type": [ "number", "null" ], "description": "Display order", "example": 1 }, "isPublished": { "type": "boolean", "description": "Whether the article is published", "example": true }, "isDraftDiffersFromLive": { "type": "boolean", "description": "Whether draft differs from live", "example": false }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/ArticleTranslation" }, "bs": { "$ref": "#/components/schemas/ArticleTranslation" }, "pt-BR": { "$ref": "#/components/schemas/ArticleTranslation" }, "bg": { "$ref": "#/components/schemas/ArticleTranslation" }, "ca": { "$ref": "#/components/schemas/ArticleTranslation" }, "hr": { "$ref": "#/components/schemas/ArticleTranslation" }, "cs": { "$ref": "#/components/schemas/ArticleTranslation" }, "da": { "$ref": "#/components/schemas/ArticleTranslation" }, "nl": { "$ref": "#/components/schemas/ArticleTranslation" }, "en": { "$ref": "#/components/schemas/ArticleTranslation" }, "et": { "$ref": "#/components/schemas/ArticleTranslation" }, "fi": { "$ref": "#/components/schemas/ArticleTranslation" }, "fr": { "$ref": "#/components/schemas/ArticleTranslation" }, "de": { "$ref": "#/components/schemas/ArticleTranslation" }, "el": { "$ref": "#/components/schemas/ArticleTranslation" }, "hi": { "$ref": "#/components/schemas/ArticleTranslation" }, "hu": { "$ref": "#/components/schemas/ArticleTranslation" }, "id": { "$ref": "#/components/schemas/ArticleTranslation" }, "it": { "$ref": "#/components/schemas/ArticleTranslation" }, "ja": { "$ref": "#/components/schemas/ArticleTranslation" }, "ko": { "$ref": "#/components/schemas/ArticleTranslation" }, "lv": { "$ref": "#/components/schemas/ArticleTranslation" }, "lt": { "$ref": "#/components/schemas/ArticleTranslation" }, "ms": { "$ref": "#/components/schemas/ArticleTranslation" }, "mn": { "$ref": "#/components/schemas/ArticleTranslation" }, "nb": { "$ref": "#/components/schemas/ArticleTranslation" }, "pl": { "$ref": "#/components/schemas/ArticleTranslation" }, "pt": { "$ref": "#/components/schemas/ArticleTranslation" }, "ro": { "$ref": "#/components/schemas/ArticleTranslation" }, "ru": { "$ref": "#/components/schemas/ArticleTranslation" }, "sr": { "$ref": "#/components/schemas/ArticleTranslation" }, "zh-CN": { "$ref": "#/components/schemas/ArticleTranslation" }, "sk": { "$ref": "#/components/schemas/ArticleTranslation" }, "sl": { "$ref": "#/components/schemas/ArticleTranslation" }, "es": { "$ref": "#/components/schemas/ArticleTranslation" }, "sw": { "$ref": "#/components/schemas/ArticleTranslation" }, "sv": { "$ref": "#/components/schemas/ArticleTranslation" }, "th": { "$ref": "#/components/schemas/ArticleTranslation" }, "zh-TW": { "$ref": "#/components/schemas/ArticleTranslation" }, "tr": { "$ref": "#/components/schemas/ArticleTranslation" }, "uk": { "$ref": "#/components/schemas/ArticleTranslation" }, "vi": { "$ref": "#/components/schemas/ArticleTranslation" } }, "description": "Translations by locale code" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2024-10-18T12:33:09.099Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last updated", "example": "2024-10-18T13:03:25.921Z" }, "liveUpdatedAt": { "type": "string", "description": "ISO 8601 timestamp when live version was last updated", "example": "2024-10-18T13:03:25.921Z" }, "path": { "type": "string", "description": "Path to article within help center hierarchy", "example": "/getting-started" }, "surveyId": { "type": "string", "description": "Associated survey ID", "example": "6743752ca81ae59d25cf834b" }, "visibleBy": { "type": "array", "items": { "type": "string" }, "description": "Visibility settings", "example": [ "everyone" ] }, "translationCreatedAt": { "type": "string", "description": "ISO 8601 timestamp when translation was created", "example": "2024-10-18T12:33:09.099Z" }, "translationUpdatedAt": { "type": "string", "description": "ISO 8601 timestamp when translation was last updated", "example": "2024-10-19T14:22:15.123Z" } }, "required": [ "object", "id", "helpCenterId", "organization", "state", "locale", "availableLocales", "createdAt", "updatedAt" ] }, "ArticleList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Article" }, "description": "Array of article objects", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9" } }, "required": [ "object", "data", "nextCursor" ] }, "ArticleIconInput_Nova": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "maxLength": 255, "description": "Icon value", "example": "📖" }, "type": { "type": "string", "enum": [ "emoji", "predefined" ], "description": "Type of icon (emoji or predefined only)", "example": "emoji" } }, "required": [ "value", "type" ], "description": "Icon object for the article" }, "ArticleTranslationInput_Nova": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 512, "description": "Article title in this locale", "example": "Getting Started Guide" }, "description": { "type": "string", "maxLength": 512, "description": "Article description in this locale", "example": "Learn how to get started" }, "body": { "type": "string", "description": "Article body content in this locale (HTML or markdown)", "example": "

Welcome to our guide.

" } } }, "CreateArticleBody_Nova": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 512, "description": "The title of the article", "example": "Getting Started Guide" }, "description": { "type": "string", "maxLength": 512, "description": "A brief description of the article", "example": "Learn how to get started with our platform" }, "body": { "type": "string", "description": "The HTML content of the article (supports external image URLs and base64 data URIs)", "example": "

Welcome to our getting started guide.

" }, "formatter": { "type": "string", "enum": [ "default", "ai" ], "default": "default", "description": "Content formatter - \"ai\" converts markdown/html to Featurebase format using AI", "example": "default" }, "parentId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The ID of the parent collection", "example": "6474684" }, "icon": { "$ref": "#/components/schemas/ArticleIconInput_Nova" }, "state": { "type": "string", "enum": [ "live", "draft" ], "default": "draft", "description": "Article state - \"live\" publishes immediately, \"draft\" saves as draft", "example": "draft" }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "bs": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pt-BR": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "bg": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ca": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "cs": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "da": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "nl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "en": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "et": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "fi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "fr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "de": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "el": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hu": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "id": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "it": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ja": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ko": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "lv": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "lt": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ms": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "mn": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "nb": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pt": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ro": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ru": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "zh-CN": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sk": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "es": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sw": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sv": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "th": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "zh-TW": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "tr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "uk": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "vi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" } }, "description": "Dictionary of translations keyed by locale code" } }, "required": [ "title" ], "additionalProperties": false }, "UpdateArticleBody_Nova": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 512, "description": "The new title of the article", "example": "Updated Getting Started Guide" }, "description": { "type": "string", "maxLength": 512, "description": "The new description of the article", "example": "Updated description" }, "body": { "type": "string", "description": "The new HTML content of the article", "example": "

Updated content.

" }, "formatter": { "type": "string", "enum": [ "default", "ai" ], "default": "default", "description": "Content formatter", "example": "default" }, "icon": { "allOf": [ { "$ref": "#/components/schemas/ArticleIconInput_Nova" }, { "description": "Updated icon object for the article" } ] }, "parentId": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "New parent collection ID", "example": "6474684" }, "authorId": { "type": "string", "description": "ID of the new author (must be a member of the organization)", "example": "507f1f77bcf86cd799439011" }, "state": { "type": "string", "enum": [ "live", "draft" ], "description": "Article state - if \"live\", publishes immediately", "example": "live" }, "translations": { "type": "object", "properties": { "bn": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "bs": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pt-BR": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "bg": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ca": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "cs": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "da": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "nl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "en": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "et": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "fi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "fr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "de": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "el": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "hu": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "id": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "it": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ja": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ko": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "lv": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "lt": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ms": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "mn": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "nb": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "pt": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ro": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "ru": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "zh-CN": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sk": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sl": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "es": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sw": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "sv": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "th": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "zh-TW": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "tr": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "uk": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" }, "vi": { "$ref": "#/components/schemas/ArticleTranslationInput_Nova" } }, "description": "Dictionary of updated translations keyed by locale code" } }, "additionalProperties": false }, "DeletedArticle": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted article", "example": "1234567" }, "object": { "type": "string", "enum": [ "article" ], "description": "Object type identifier", "example": "article" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "RedirectRule": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "redirect_rule" ], "description": "Object type identifier", "example": "redirect_rule" }, "id": { "type": "string", "description": "Redirect rule unique identifier", "example": "507f1f77bcf86cd799439011" }, "helpCenterId": { "type": "string", "description": "Help center identifier", "example": "ox6qrqprmsuqaunj" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for the redirect rule", "example": "en" }, "fromUrl": { "type": "string", "description": "Canonical source URL being redirected from (query and hash stripped)", "example": "https://help.example.com/en/old/getting-started" }, "targetType": { "type": "string", "enum": [ "article", "collection" ], "description": "Type of content the redirect points to", "example": "article" }, "targetId": { "type": "string", "description": "Target article or collection ID", "example": "1234567" }, "createdAt": { "type": "string", "description": "ISO 8601 timestamp when created", "example": "2026-02-11T12:00:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO 8601 timestamp when last updated", "example": "2026-02-11T12:00:00.000Z" } }, "required": [ "object", "id", "helpCenterId", "locale", "fromUrl", "targetType", "targetId", "createdAt", "updatedAt" ] }, "RedirectRuleList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/RedirectRule" }, "description": "Array of redirect rules", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page. Null if there are no more results.", "example": null } }, "required": [ "object", "data", "nextCursor" ] }, "CreateRedirectRuleBody_Nova": { "type": "object", "properties": { "helpCenterId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Help center identifier this redirect rule belongs to", "example": "ox6qrqprmsuqaunj" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for the redirect rule. Used to resolve the target article/collection translation.", "example": "en" }, "fromUrl": { "type": "string", "maxLength": 2048, "description": "Full absolute URL to redirect from. Must use http or https protocol. Query parameters and hash fragments are stripped during normalization. The hostname must match the Help Center custom domain.", "example": "https://help.example.com/en/old/getting-started" }, "targetType": { "type": "string", "enum": [ "article", "collection" ], "description": "Type of content the redirect points to", "example": "article" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "ID of the target article or collection", "example": "10021362" } }, "required": [ "helpCenterId", "locale", "fromUrl", "targetType", "targetId" ], "additionalProperties": false }, "UpdateRedirectRuleBody_Nova": { "type": "object", "properties": { "helpCenterId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Help center identifier", "example": "ox6qrqprmsuqaunj" }, "locale": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Locale code for the redirect rule", "example": "en" }, "fromUrl": { "type": "string", "maxLength": 2048, "description": "Full absolute URL to redirect from. Must use http or https protocol. Query parameters and hash fragments are stripped during normalization. The hostname must match the Help Center custom domain.", "example": "https://help.example.com/en/old/getting-started" }, "targetType": { "type": "string", "enum": [ "article", "collection" ], "description": "Type of content the redirect points to", "example": "article" }, "targetId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "ID of the target article or collection", "example": "10021362" } }, "additionalProperties": false }, "DeletedRedirectRule": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted redirect rule", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "redirect_rule" ], "description": "Object type identifier", "example": "redirect_rule" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "ContactList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] }, "description": "Array of contacts", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" } }, "required": [ "object", "data", "nextCursor" ] }, "UpsertContactCompany": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External company ID from your system", "example": "company_123" }, "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Company name", "example": "Acme Inc" }, "createdAt": { "type": [ "string", "null" ], "description": "When the company was created (ISO 8601)", "example": "2024-01-15T10:30:00Z" }, "monthlySpend": { "type": "number", "minimum": 0, "description": "Monthly spend/revenue from this company", "example": 500 }, "customFields": { "type": "object", "description": "Custom field values on the company. Values can be string, number, boolean, null, or array of primitives.", "properties": { "plan": { "type": "string", "example": "enterprise" }, "industry": { "type": "string", "example": "Technology" }, "priority": { "type": "string", "example": "high" } } }, "companyHash": { "type": "string", "maxLength": 256, "description": "HMAC-SHA256 hash of company ID for identity verification", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" }, "companySize": { "type": [ "number", "null" ], "minimum": 0, "description": "Number of employees in the company", "example": 50 }, "industry": { "type": "string", "maxLength": 500, "description": "Industry the company operates in", "example": "Technology" }, "website": { "type": "string", "maxLength": 500, "description": "Company website URL", "example": "https://acme.com" }, "plan": { "type": "string", "maxLength": 500, "description": "Current plan/subscription name", "example": "enterprise" } }, "required": [ "id", "name" ], "additionalProperties": false }, "UpsertContactBody": { "type": "object", "properties": { "email": { "type": "string", "maxLength": 500, "format": "email", "description": "Contact email address. Used for identification if userId is not provided.", "example": "john@example.com" }, "name": { "type": "string", "maxLength": 500, "description": "Contact display name", "example": "John Doe" }, "userId": { "type": "string", "maxLength": 500, "description": "External user ID from your system. Takes precedence over email for identification.", "example": "usr_12345" }, "userHash": { "type": "string", "maxLength": 256, "description": "HMAC-SHA256 hash of userId or email for identity verification", "example": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" }, "profilePicture": { "type": [ "string", "null" ], "format": "uri", "description": "Profile picture URL", "example": "https://example.com/avatar.png" }, "companies": { "type": "array", "items": { "$ref": "#/components/schemas/UpsertContactCompany" }, "maxItems": 100, "description": "Companies the contact belongs to" }, "createdAt": { "type": [ "string", "null" ], "description": "When the contact was created in your system (ISO 8601)", "example": "2024-01-15T10:30:00Z" }, "customFields": { "type": "object", "description": "Custom field values on the contact. Values can be string, number, boolean, null, or array of primitives.", "properties": { "plan": { "type": "string", "example": "pro" }, "signupSource": { "type": "string", "example": "website" }, "accountType": { "type": "string", "example": "premium" } } }, "subscribedToChangelog": { "type": "boolean", "description": "Whether the contact is subscribed to changelog updates", "example": true }, "locale": { "type": "string", "maxLength": 10, "description": "Contact locale/language preference", "example": "en" }, "phone": { "type": [ "string", "null" ], "maxLength": 500, "description": "Contact phone number", "example": "+1234567890" }, "roles": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 100, "description": "Array of role IDs to assign to the contact", "example": [ "role_vip", "role_beta" ] } }, "additionalProperties": false }, "DeletedContact": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted contact", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier", "example": "contact" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "BlockedContact": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the blocked contact", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier", "example": "contact" }, "blocked": { "type": "boolean", "enum": [ true ], "description": "Indicates the contact was blocked", "example": true } }, "required": [ "id", "object", "blocked" ] }, "UnblockedContact": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the unblocked contact", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "contact" ], "description": "Object type identifier", "example": "contact" }, "unblocked": { "type": "boolean", "enum": [ true ], "description": "Indicates the contact was unblocked", "example": true } }, "required": [ "id", "object", "unblocked" ] }, "Icon": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "description": "Icon value", "example": "👥" }, "type": { "type": "string", "enum": [ "emoji", "predefined", "external" ], "description": "Type of icon", "example": "emoji" } }, "required": [ "value", "type" ], "description": "Team icon" }, "Team": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "team" ], "description": "Object type identifier", "example": "team" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Team name", "example": "Support Team" }, "color": { "type": "string", "description": "Team color in hex format", "example": "#3B82F6" }, "icon": { "$ref": "#/components/schemas/Icon" }, "members": { "type": "array", "items": { "type": "string" }, "description": "Array of admin IDs who are members of this team", "example": [ "5fef50c5e9458a0012f82456", "5fef50c5e9458a0012f82457" ] } }, "required": [ "object", "id", "name", "color", "icon", "members" ] }, "TeamList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Team" }, "description": "Array of teams", "example": [] } }, "required": [ "object", "data" ] }, "CompanyList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" }, "description": "Array of companies", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" } }, "required": [ "object", "data", "nextCursor" ] }, "UpsertCompanyBody": { "type": "object", "properties": { "companyId": { "type": "string", "minLength": 1, "maxLength": 500, "description": "External company ID from your system. Used as the unique identifier for upsert matching.", "example": "comp_12345" }, "name": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Company name", "example": "Acme Inc" }, "monthlySpend": { "type": "number", "minimum": 0, "description": "Monthly spend/revenue from this company", "example": 5000 }, "industry": { "type": "string", "maxLength": 500, "description": "Industry the company operates in", "example": "Technology" }, "website": { "type": "string", "maxLength": 500, "description": "Company website URL", "example": "https://acme.com" }, "plan": { "type": "string", "maxLength": 500, "description": "Current plan/subscription name", "example": "enterprise" }, "companySize": { "type": [ "number", "null" ], "minimum": 0, "description": "Number of employees in the company", "example": 250 }, "createdAt": { "type": [ "string", "null" ], "description": "When the company was created in your system (ISO 8601)", "example": "2024-01-15T10:30:00Z" }, "customFields": { "type": "object", "description": "Custom field values on the company. Values can be string, number, boolean, null, or array of primitives.", "properties": { "region": { "type": "string", "example": "EMEA" }, "tier": { "type": "string", "example": "gold" }, "priority": { "type": "string", "example": "high" } } } }, "required": [ "companyId", "name" ], "additionalProperties": false }, "DeletedCompany": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted company", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "company" ], "description": "Object type identifier", "example": "company" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "AttachContactToCompanyBody": { "type": "object", "properties": { "contactId": { "type": "string", "description": "The Featurebase internal ID of the contact to attach (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439012" } }, "required": [ "contactId" ] }, "Brand": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "brand" ], "description": "Object type identifier", "example": "brand" }, "id": { "type": "string", "description": "Featurebase internal ID", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Brand display name", "example": "Default Brand" }, "isDefault": { "type": "boolean", "description": "Whether this is the default brand", "example": true }, "createdAt": { "type": [ "string", "null" ], "description": "ISO date when brand was created", "example": "2025-01-01T12:00:00.000Z" }, "updatedAt": { "type": [ "string", "null" ], "description": "ISO date when brand was last updated", "example": "2025-01-10T15:30:00.000Z" }, "helpCenterId": { "type": [ "string", "null" ], "description": "The ID of the help center associated with this brand", "example": "11" }, "senderEmailAddressId": { "type": [ "string", "null" ], "description": "The ID of the default sending email address for this brand", "example": "507f1f77bcf86cd799439012" } }, "required": [ "object", "id", "name", "isDefault", "createdAt", "updatedAt", "helpCenterId", "senderEmailAddressId" ] }, "BrandList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Brand" }, "description": "Array of brands", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "maxLength": 512, "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" } }, "required": [ "object", "data", "nextCursor" ] }, "ConversationParticipant": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "customer", "lead", "admin", "bot", "guest", "integration" ], "description": "Type of participant", "example": "customer" }, "id": { "type": "string", "description": "Participant ID", "example": "676f0f6765bdaa7d7d760f88" } }, "required": [ "type", "id" ] }, "MessageSource": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "unknown", "desktop", "android", "ios", "email" ], "description": "Channel through which the conversation was initiated", "example": "desktop" }, "deliveredAs": { "type": "string", "enum": [ "customer_initiated", "admin_initiated" ], "description": "How the conversation was initiated", "example": "customer_initiated" }, "subject": { "type": "string", "description": "Subject line for email conversations", "example": "Question about pricing" }, "bodyHtml": { "type": "string", "description": "Body of the initial message as HTML with signed image URLs", "example": "

Hi, I have a question about your enterprise plan...

" }, "bodyMarkdown": { "type": "string", "description": "Body of the initial message as markdown", "example": "Hi, I have a question about your enterprise plan..." }, "author": { "$ref": "#/components/schemas/ConversationParticipant" }, "url": { "type": "string", "description": "URL where the conversation was initiated", "example": "https://example.com/pricing" } }, "required": [ "channel", "bodyHtml", "bodyMarkdown" ] }, "ReadReceipt": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal ID of the user", "example": "507f1f77bcf86cd799439011" }, "userType": { "type": "string", "enum": [ "admin", "customer", "lead" ], "description": "Type of user who has read the conversation", "example": "admin" }, "lastReadPartId": { "type": "string", "description": "The ID of the last conversation part this user has read. Note: This reflects the system-tracked read position and may reference a part the user cannot directly access (e.g., internal notes for contacts). The read state is advanced to the latest part in the conversation regardless of part visibility.", "example": "8" } }, "required": [ "id", "userType", "lastReadPartId" ] }, "ConversationPartAuthor": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "customer", "lead", "admin", "bot", "guest", "integration" ], "description": "Type of author", "example": "customer" }, "id": { "type": [ "string", "null" ], "description": "Author ID", "example": "676f0f6765bdaa7d7d760f88" }, "name": { "type": "string", "description": "Author display name", "example": "John Doe" }, "email": { "type": "string", "description": "Author email address", "example": "john@example.com" }, "profilePicture": { "type": [ "string", "null" ], "description": "Author profile picture URL", "example": "https://cdn.example.com/avatars/user.png" } }, "required": [ "type", "id" ] }, "UserMessagePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "user_msg" ], "description": "User message type", "example": "user_msg" }, "bodyHtml": { "type": [ "string", "null" ], "description": "Message body content as HTML with signed image URLs", "example": "

Hello, I have a question about your product.

" }, "bodyMarkdown": { "type": [ "string", "null" ], "description": "Message body content as markdown", "example": "Hello, I have a question about your product." }, "channel": { "type": "string", "enum": [ "unknown", "desktop", "android", "ios", "email" ], "description": "Channel through which the message was sent", "example": "desktop" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown", "channel" ], "description": "Message from a customer or lead", "title": "User Message" }, "AdminMessagePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "admin_msg" ], "description": "Admin message type", "example": "admin_msg" }, "bodyHtml": { "type": [ "string", "null" ], "description": "Message body content as HTML with signed image URLs", "example": "

Thanks for reaching out! I can help you with that.

" }, "bodyMarkdown": { "type": [ "string", "null" ], "description": "Message body content as markdown", "example": "Thanks for reaching out! I can help you with that." }, "channel": { "type": "string", "enum": [ "unknown", "desktop", "android", "ios", "email" ], "description": "Channel through which the message was sent", "example": "desktop" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown", "channel" ], "description": "Message from an admin or support agent", "title": "Admin Message" }, "AdminNotePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "admin_note" ], "description": "Admin internal note type", "example": "admin_note" }, "bodyHtml": { "type": [ "string", "null" ], "description": "Note body content as HTML with signed image URLs", "example": "

Customer seems frustrated, escalating to tier 2.

" }, "bodyMarkdown": { "type": [ "string", "null" ], "description": "Note body content as markdown", "example": "Customer seems frustrated, escalating to tier 2." } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown" ], "description": "Internal note visible only to admins", "title": "Admin Note" }, "EmailMessagePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "email_msg" ], "description": "Email message type", "example": "email_msg" }, "bodyHtml": { "type": [ "string", "null" ], "description": "Email body content as HTML with signed image URLs", "example": "

Thank you for your email...

" }, "bodyMarkdown": { "type": [ "string", "null" ], "description": "Email body content as markdown", "example": "Thank you for your email..." }, "channel": { "type": "string", "enum": [ "email" ], "description": "Email channel", "example": "email" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown", "channel" ], "description": "Message sent via email", "title": "Email Message" }, "BotMessagePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "bot_msg" ], "description": "Bot message type", "example": "bot_msg" }, "bodyHtml": { "type": [ "string", "null" ], "description": "Bot message body content as HTML with signed image URLs", "example": "

Based on your question, here is what I found...

" }, "bodyMarkdown": { "type": [ "string", "null" ], "description": "Bot message body content as markdown", "example": "Based on your question, here is what I found..." }, "channel": { "type": "string", "enum": [ "unknown", "desktop", "android", "ios", "email" ], "description": "Channel through which the message was sent", "example": "desktop" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown" ], "description": "Automated message from AI or bot", "title": "Bot Message" }, "QuickReplyOptionsPart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "quick_reply_opts" ], "description": "Quick reply options type", "example": "quick_reply_opts" }, "replyOptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Option ID", "example": "opt_1" }, "text": { "type": "string", "description": "Option text", "example": "Yes, that helps!" } }, "required": [ "id", "text" ] }, "description": "Available reply options", "example": [ { "id": "opt_1", "text": "Yes, that helps!" } ] } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "replyOptions" ], "description": "Presents options for user to choose from", "title": "Quick Reply Options" }, "QuickReplyResponsePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "quick_reply_resp" ], "description": "Quick reply response type", "example": "quick_reply_resp" }, "bodyHtml": { "type": "string", "description": "The selected option text as HTML", "example": "Yes, that helps!" }, "bodyMarkdown": { "type": "string", "description": "The selected option text as markdown", "example": "Yes, that helps!" }, "selectedOptionId": { "type": "string", "description": "ID of the selected option", "example": "opt_1" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "bodyHtml", "bodyMarkdown", "selectedOptionId" ], "description": "User's selection from quick reply options", "title": "Quick Reply Response" }, "AttributeCollectionPromptPart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "author": { "$ref": "#/components/schemas/ConversationPartAuthor" }, "redacted": { "type": "boolean", "description": "Whether this message has been redacted", "example": false }, "partType": { "type": "string", "enum": [ "attr_prompt" ], "description": "Attribute collection prompt type", "example": "attr_prompt" }, "form": { "type": "object", "properties": { "id": { "type": "string", "description": "Form ID", "example": "form_123" }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string", "description": "Field identifier", "example": "email" }, "name": { "type": "string", "description": "Field display name", "example": "Email Address" }, "type": { "type": "string", "description": "Field type", "example": "text" } }, "required": [ "identifier", "name", "type" ] }, "description": "Form fields", "example": [ { "identifier": "email", "name": "Email Address", "type": "text" } ] } }, "required": [ "id", "attributes" ], "description": "Form configuration" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "form" ], "description": "Requests information from user via form", "title": "Attribute Collection Prompt" }, "AttributeCollectionCompletePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "partType": { "type": "string", "enum": [ "attr_complete" ], "description": "Attribute collection complete type", "example": "attr_complete" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType" ], "description": "Indicates form was completed", "title": "Attribute Collection Complete" }, "AssignmentPart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "partType": { "type": "string", "enum": [ "assign" ], "description": "Assignment type", "example": "assign" }, "adminAssigneeId": { "type": [ "string", "null" ], "description": "ID of the admin assigned to the conversation", "example": "507f1f77bcf86cd799439011" }, "adminAssignerId": { "type": [ "string", "null" ], "description": "ID of the admin who made the assignment", "example": "507f1f77bcf86cd799439012" }, "teamAssigneeId": { "type": [ "string", "null" ], "description": "ID of the team assigned to the conversation", "example": "507f1f77bcf86cd799439013" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType" ], "description": "Conversation assigned to admin or team", "title": "Assignment" }, "StatusChangePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "partType": { "type": "string", "enum": [ "status" ], "description": "Status change type", "example": "status" }, "status": { "type": "string", "enum": [ "open", "closed", "snoozed" ], "description": "New conversation status", "example": "open" }, "snoozedUntil": { "type": [ "string", "null" ], "description": "ISO timestamp until conversation is snoozed (if snoozed)", "example": "2025-01-16T09:00:00.000Z" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "status" ], "description": "Conversation state changed (open/closed/snoozed)", "title": "Status Change" }, "PriorityChangePart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "partType": { "type": "string", "enum": [ "priority" ], "description": "Priority change type", "example": "priority" }, "isPriority": { "type": "boolean", "description": "Whether the conversation is now marked as priority", "example": true } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "isPriority" ], "description": "Conversation priority was updated", "title": "Priority Change" }, "ParticipantAddedPart": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation_part" ], "description": "Object type identifier", "example": "conversation_part" }, "id": { "type": "string", "description": "Unique part identifier", "example": "1" }, "createdAt": { "type": "string", "description": "ISO timestamp when the part was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the part was last updated", "example": "2025-01-15T10:30:00.000Z" }, "partType": { "type": "string", "enum": [ "part_add" ], "description": "Participant added type", "example": "part_add" }, "participant": { "type": "object", "properties": { "id": { "type": "string", "description": "Participant ID", "example": "676f0f6765bdaa7d7d760f88" }, "type": { "type": "string", "enum": [ "customer", "lead", "admin" ], "description": "Participant type", "example": "customer" } }, "required": [ "id", "type" ], "description": "The added participant" } }, "required": [ "object", "id", "createdAt", "updatedAt", "partType", "participant" ], "description": "New participant joined the conversation", "title": "Participant Added" }, "ConversationPart": { "oneOf": [ { "$ref": "#/components/schemas/UserMessagePart" }, { "$ref": "#/components/schemas/AdminMessagePart" }, { "$ref": "#/components/schemas/AdminNotePart" }, { "$ref": "#/components/schemas/EmailMessagePart" }, { "$ref": "#/components/schemas/BotMessagePart" }, { "$ref": "#/components/schemas/QuickReplyOptionsPart" }, { "$ref": "#/components/schemas/QuickReplyResponsePart" }, { "$ref": "#/components/schemas/AttributeCollectionPromptPart" }, { "$ref": "#/components/schemas/AttributeCollectionCompletePart" }, { "$ref": "#/components/schemas/AssignmentPart" }, { "$ref": "#/components/schemas/StatusChangePart" }, { "$ref": "#/components/schemas/PriorityChangePart" }, { "$ref": "#/components/schemas/ParticipantAddedPart" } ], "discriminator": { "propertyName": "partType", "mapping": { "user_msg": "#/components/schemas/UserMessagePart", "admin_msg": "#/components/schemas/AdminMessagePart", "admin_note": "#/components/schemas/AdminNotePart", "email_msg": "#/components/schemas/EmailMessagePart", "bot_msg": "#/components/schemas/BotMessagePart", "quick_reply_opts": "#/components/schemas/QuickReplyOptionsPart", "quick_reply_resp": "#/components/schemas/QuickReplyResponsePart", "attr_prompt": "#/components/schemas/AttributeCollectionPromptPart", "attr_complete": "#/components/schemas/AttributeCollectionCompletePart", "assign": "#/components/schemas/AssignmentPart", "status": "#/components/schemas/StatusChangePart", "priority": "#/components/schemas/PriorityChangePart", "part_add": "#/components/schemas/ParticipantAddedPart" } } }, "Conversation": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "conversation" ], "description": "Object type identifier", "example": "conversation" }, "id": { "type": "string", "description": "Unique conversation identifier", "example": "12345" }, "brandId": { "type": [ "string", "null" ], "description": "ID of the brand associated with this conversation", "example": "507f1f77bcf86cd799439011" }, "title": { "type": "string", "description": "Conversation title", "example": "Question about pricing" }, "state": { "type": "string", "enum": [ "open", "closed", "snoozed" ], "description": "Current state of the conversation", "example": "open" }, "isBlocked": { "type": "boolean", "description": "Whether the user is blocked", "example": false }, "priority": { "type": "boolean", "description": "Whether this conversation is marked as priority", "example": false }, "prioritySetAt": { "type": [ "string", "null" ], "description": "ISO timestamp when priority was set", "example": "2025-01-15T10:30:00.000Z" }, "adminAssigneeId": { "type": [ "string", "null" ], "description": "ID of the assigned admin", "example": "507f1f77bcf86cd799439011" }, "teamAssigneeId": { "type": [ "string", "null" ], "description": "ID of the assigned team", "example": "507f1f77bcf86cd799439012" }, "userPreferredLanguage": { "type": "string", "description": "User's preferred language", "example": "en" }, "hasAdminOverriddenLanguage": { "type": "boolean", "description": "Whether an admin has manually overridden the language for this conversation. When true, automatic language detection is disabled.", "example": false }, "source": { "$ref": "#/components/schemas/MessageSource" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationParticipant" }, "description": "Participants in this conversation" }, "botConversationState": { "type": "string", "enum": [ "active", "handed_off_to_human", "resolved" ], "description": "State of AI agent handling for this conversation", "example": "active" }, "botConversationStateLastUpdatedAt": { "type": [ "string", "null" ], "description": "ISO timestamp when bot state last changed", "example": "2025-01-15T10:30:00.000Z" }, "disableCustomerReply": { "type": "boolean", "description": "Whether customer replies are disabled", "example": false }, "awaitingCustomerReply": { "type": "boolean", "description": "Whether we are awaiting a customer reply", "example": true }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO timestamp of last activity", "example": "2025-01-15T12:30:00.000Z" }, "waitingSince": { "type": [ "string", "null" ], "description": "ISO timestamp when conversation started waiting", "example": "2025-01-15T10:30:00.000Z" }, "snoozedUntil": { "type": [ "string", "null" ], "description": "ISO timestamp until which conversation is snoozed", "example": "2025-01-16T09:00:00.000Z" }, "createdAt": { "type": "string", "description": "ISO timestamp when conversation was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when conversation was last updated", "example": "2025-01-15T12:30:00.000Z" }, "readReceipts": { "type": "array", "items": { "$ref": "#/components/schemas/ReadReceipt" }, "description": "Read receipts indicating how far each participant has read in the conversation. Each receipt maps a user to their last-read conversation part. The tracked position reflects the system read state and may reference parts the user cannot directly view (e.g., a contact's read position may point to an internal admin note). Use these receipts to render read indicators and typing awareness, not to infer content access." }, "conversationParts": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationPart" }, "description": "Array of conversation parts (messages). Only included when fetching a single conversation by ID." } }, "required": [ "object", "id", "brandId", "state", "isBlocked", "priority", "prioritySetAt", "adminAssigneeId", "teamAssigneeId", "userPreferredLanguage", "hasAdminOverriddenLanguage", "participants", "botConversationStateLastUpdatedAt", "lastActivityAt", "waitingSince", "snoozedUntil", "createdAt", "updatedAt" ] }, "ConversationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" }, "description": "Array of conversations" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page", "example": "eyJpZCI6IjEyMzQ1In0=" } }, "required": [ "object", "data", "nextCursor" ] }, "ConversationFromContact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact" ], "description": "The type of author. Use \"contact\" for customer/lead initiated conversations.", "example": "contact" }, "id": { "type": "string", "description": "The Featurebase contact ID", "example": "676f0f6765bdaa7d7d760f88" } }, "required": [ "type", "id" ], "description": "Conversation initiated by a contact", "title": "Contact From" }, "ConversationFromAdmin": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "admin" ], "description": "The type of author. Use \"admin\" for admin initiated outreach conversations.", "example": "admin" }, "id": { "type": "string", "description": "The Featurebase admin ID", "example": "507f1f77bcf86cd799439011" } }, "required": [ "type", "id" ], "description": "Conversation initiated by an admin (outreach)", "title": "Admin From" }, "ConversationFrom": { "anyOf": [ { "$ref": "#/components/schemas/ConversationFromContact" }, { "$ref": "#/components/schemas/ConversationFromAdmin" } ], "description": "The author initiating the conversation. Use type \"contact\" for customer/lead or \"admin\" for outreach.", "discriminator": { "propertyName": "type", "mapping": { "contact": "#/components/schemas/ConversationFromContact", "admin": "#/components/schemas/ConversationFromAdmin" } } }, "EmailRecipients": { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "maxItems": 50, "description": "Array of email addresses", "example": [ "john@example.com" ] }, "ids": { "type": "array", "items": { "type": "string" }, "maxItems": 50, "description": "Array of Featurebase contact IDs", "example": [ "676f0f6765bdaa7d7d760f88" ] } }, "description": "Primary recipients (To field)" }, "OutreachRecipients": { "type": "object", "properties": { "to": { "$ref": "#/components/schemas/EmailRecipients" }, "cc": { "allOf": [ { "$ref": "#/components/schemas/EmailRecipients" }, { "description": "Carbon copy recipients (CC field)" } ] }, "bcc": { "allOf": [ { "$ref": "#/components/schemas/EmailRecipients" }, { "description": "Blind carbon copy recipients (BCC field)" } ] } }, "required": [ "to" ], "description": "Recipients for admin-initiated outreach. Required when from.type is \"admin\". Specify at least one recipient in the \"to\" field." }, "CreateConversationBody": { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/ConversationFrom" }, "bodyMarkdown": { "type": "string", "minLength": 1, "description": "The content of the initial message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.", "example": "Hello, I have a question about your product.\n\n![screenshot](https://example.com/image.png)" }, "channel": { "type": "string", "enum": [ "desktop", "email" ], "default": "desktop", "description": "The channel for the conversation. Defaults to \"desktop\" (SDK/widget).", "example": "desktop" }, "recipients": { "$ref": "#/components/schemas/OutreachRecipients" }, "subject": { "type": "string", "maxLength": 500, "description": "Subject line for the email. Required when channel is \"email\" and from.type is \"admin\".", "example": "Following up on your inquiry" }, "createdAt": { "type": [ "string", "null" ], "description": "The time the conversation was created as an ISO timestamp. If not provided, the current time will be used. This field is recommended for migrating past conversations from another source.", "example": "2025-01-15T10:30:00.000Z" } }, "required": [ "from", "bodyMarkdown" ] }, "DeletedConversation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted conversation", "example": "12345" }, "object": { "type": "string", "enum": [ "conversation" ], "description": "Object type identifier", "example": "conversation" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] }, "ContactReplyBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "contact" ], "description": "The type of author. Use \"contact\" for customer/lead replies.", "example": "contact" }, "userId": { "type": "string", "maxLength": 255, "description": "The external user ID from your system", "example": "user_123" }, "id": { "type": "string", "description": "The Featurebase contact ID", "example": "676f0f6765bdaa7d7d760f88" }, "bodyMarkdown": { "type": "string", "minLength": 1, "description": "The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.", "example": "Thank you for your help!" }, "messageType": { "type": "string", "enum": [ "reply" ], "description": "The type of message. Always \"reply\" for contact replies.", "example": "reply" } }, "required": [ "type", "bodyMarkdown", "messageType" ], "description": "Reply from a customer or lead", "title": "Contact Reply" }, "AdminReplyBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "admin" ], "description": "The type of author. Use \"admin\" for admin replies.", "example": "admin" }, "id": { "type": "string", "description": "The Featurebase admin ID", "example": "507f1f77bcf86cd799439011" }, "bodyMarkdown": { "type": "string", "minLength": 1, "description": "The content of the reply message in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored.", "example": "I can help you with that!\n\nHere is a **bold** explanation." }, "messageType": { "type": "string", "enum": [ "reply", "note" ], "description": "The type of message. \"reply\" is visible to the customer, \"note\" is an internal note only visible to admins.", "example": "reply" } }, "required": [ "type", "id", "bodyMarkdown", "messageType" ], "description": "Reply or internal note from an admin", "title": "Admin Reply" }, "ReplyToConversationBody": { "anyOf": [ { "$ref": "#/components/schemas/ContactReplyBody" }, { "$ref": "#/components/schemas/AdminReplyBody" } ], "discriminator": { "propertyName": "type", "mapping": { "contact": "#/components/schemas/ContactReplyBody", "admin": "#/components/schemas/AdminReplyBody" } } }, "MarkAsRead": { "type": "object", "properties": { "allAdmins": { "type": [ "boolean", "null" ], "description": "If true, marks all admins with existing readReceipts as read.", "example": true }, "adminIds": { "type": "array", "items": { "type": "string" }, "maxItems": 255, "description": "Array of admin IDs to mark as read. Only admins with existing readReceipts will be updated.", "example": [ "507f1f77bcf86cd799439011" ] }, "allContacts": { "type": [ "boolean", "null" ], "description": "If true, marks all contacts (customers and leads) with existing readReceipts as read.", "example": true }, "contactIds": { "type": "array", "items": { "type": "string" }, "maxItems": 255, "description": "Array of contact IDs to mark as read. Only contacts with existing readReceipts will be updated.", "example": [ "676f0f6765bdaa7d7d760f88" ] } }, "description": "Mark the conversation as read for specific admins and/or contacts." }, "UpdateConversationBody": { "type": "object", "properties": { "actingAdminId": { "type": "string", "description": "The admin ID performing this action. Changes will be attributed to this admin. If not provided, changes are attributed to the system bot user. The admin must be a member of the organization.", "example": "507f1f77bcf86cd799439011" }, "state": { "type": "string", "enum": [ "open", "closed", "snoozed" ], "description": "The state of the conversation. Use \"snoozed\" with snoozedUntil to snooze.", "example": "open" }, "snoozedUntil": { "type": [ "string", "null" ], "description": "ISO datetime when the conversation should be unsnoozed. Required when state is \"snoozed\". Must be a future date.", "example": "2025-01-20T10:00:00.000Z" }, "adminAssigneeId": { "type": [ "string", "null" ], "description": "The admin ID to assign the conversation to, or null to unassign.", "example": "507f1f77bcf86cd799439011" }, "teamAssigneeId": { "type": [ "string", "null" ], "description": "The team ID to assign the conversation to, or null to unassign.", "example": "507f1f77bcf86cd799439012" }, "title": { "type": "string", "maxLength": 255, "description": "The title of the conversation.", "example": "Question about pricing" }, "customAttributes": { "type": "object", "additionalProperties": {}, "description": "Custom attributes to set on the conversation. Uses the same validation as v1 API.", "example": { "priority_level": "high", "category": "billing" } }, "markAsRead": { "$ref": "#/components/schemas/MarkAsRead" } } }, "ParticipantIdentifier": { "type": "object", "properties": { "id": { "type": "string", "description": "The Featurebase ID of the contact (customer or lead)", "example": "676f0f6765bdaa7d7d760f88" }, "userId": { "type": "string", "maxLength": 255, "description": "The external user ID from your system (matches customer type only)", "example": "user_123" }, "email": { "type": "string", "format": "email", "description": "The email address of the contact (matches customer type only)", "example": "john@example.com" } }, "description": "The contact to add as a participant. At least one of id, userId, or email is required." }, "AddParticipantBody": { "type": "object", "properties": { "participant": { "$ref": "#/components/schemas/ParticipantIdentifier" }, "actingAdminId": { "type": "string", "description": "The admin ID performing this action. If not provided, changes are attributed to the system bot user.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "participant" ] }, "RemoveParticipantBody": { "type": "object", "properties": { "id": { "type": "string", "description": "The Featurebase ID of the contact (customer or lead) to remove", "example": "676f0f6765bdaa7d7d760f88" }, "actingAdminId": { "type": "string", "description": "The admin ID performing this action. If not provided, changes are attributed to the system bot user.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "id" ] }, "RedactConversationPartBody": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "conversation_part" ], "description": "The type of item to redact. Currently only \"conversation_part\" is supported.", "example": "conversation_part" }, "conversationId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The conversation short ID that contains the part to redact", "example": "12345" }, "conversationPartId": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The conversation part short ID to redact", "example": "67890" }, "actingAdminId": { "type": "string", "description": "The admin ID performing this action. If not provided, changes are attributed to the system bot user.", "example": "507f1f77bcf86cd799439011" } }, "required": [ "type", "conversationId", "conversationPartId" ] }, "WebhookRequestConfig": { "type": "object", "properties": { "timeoutMs": { "type": "integer", "minimum": 1000, "maximum": 30000, "description": "Request timeout in milliseconds (1000-30000)", "example": 5000 }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Custom headers to send with webhook requests", "example": { "X-Custom-Header": "value" } } }, "required": [ "timeoutMs" ] }, "WebhookLastStatus": { "type": [ "object", "null" ], "properties": { "code": { "type": "integer", "description": "HTTP status code from last delivery attempt", "example": 200 }, "message": { "type": "string", "description": "Status message from last delivery attempt", "example": "Success" }, "timestamp": { "type": "string", "description": "ISO timestamp of last status update", "example": "2025-01-15T10:30:00.000Z" } }, "required": [ "code", "message", "timestamp" ], "description": "Last delivery attempt status" }, "WebhookHealth": { "type": "object", "properties": { "lastResponseTime": { "type": "number", "description": "Last response time in milliseconds", "example": 150 }, "avgResponseTime": { "type": "number", "description": "Average response time in milliseconds", "example": 200 }, "lastSuccessAt": { "type": [ "string", "null" ], "description": "ISO timestamp of last successful delivery", "example": "2025-01-15T10:30:00.000Z" }, "errorsSinceLastSuccess": { "type": "integer", "description": "Number of errors since last successful delivery", "example": 0 }, "consecutiveFailures": { "type": "integer", "description": "Number of consecutive delivery failures", "example": 0 } }, "required": [ "lastResponseTime", "avgResponseTime", "lastSuccessAt", "errorsSinceLastSuccess", "consecutiveFailures" ] }, "Webhook": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "webhook" ], "description": "Object type identifier", "example": "webhook" }, "id": { "type": "string", "description": "Unique identifier", "example": "507f1f77bcf86cd799439011" }, "name": { "type": "string", "description": "Human-readable webhook name", "example": "Production Webhook" }, "url": { "type": "string", "description": "Webhook endpoint URL", "example": "https://example.com/webhooks" }, "secret": { "type": "string", "description": "Webhook signing secret for verifying payloads", "example": "whsec_abc123def456ghi789" }, "description": { "type": [ "string", "null" ], "description": "Optional description of the webhook purpose", "example": "Handles all production events" }, "topics": { "type": "array", "items": { "type": "string", "enum": [ "post.created", "post.updated", "post.deleted", "post.voted", "changelog.published", "comment.created", "comment.updated", "comment.deleted", "conversation.user.created", "conversation.user.replied", "conversation.admin.replied", "conversation.admin.closed", "conversation.handover_requested", "conversation.admin.assigned", "conversation.admin.noted", "conversation.admin.snoozed", "conversation.admin.unsnoozed", "conversation.admin.opened", "conversation.priority.updated", "conversation.deleted", "conversation.contact.attached", "conversation.contact.detached", "conversation.read", "conversation_part.redacted" ], "description": "Webhook event topic", "example": "post.created" }, "description": "Array of event topics the webhook subscribes to", "example": [ "post.created", "post.updated" ] }, "status": { "type": "string", "enum": [ "active", "paused", "suspended" ], "description": "Current status of the webhook", "example": "active" }, "requestConfig": { "$ref": "#/components/schemas/WebhookRequestConfig" }, "lastStatus": { "$ref": "#/components/schemas/WebhookLastStatus" }, "health": { "$ref": "#/components/schemas/WebhookHealth" }, "version": { "type": "string", "description": "API version for webhook payloads", "example": "1.0" }, "createdAt": { "type": "string", "description": "ISO timestamp when the webhook was created", "example": "2025-01-15T10:30:00.000Z" }, "updatedAt": { "type": "string", "description": "ISO timestamp when the webhook was last updated", "example": "2025-01-15T10:30:00.000Z" } }, "required": [ "object", "id", "name", "url", "secret", "description", "topics", "status", "requestConfig", "lastStatus", "health", "version", "createdAt", "updatedAt" ] }, "WebhookList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "Object type identifier", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Array of webhooks", "example": [] }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching the next page (cursor-based pagination)", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" } }, "required": [ "object", "data", "nextCursor" ] }, "WebhookRequestConfigInput": { "type": "object", "properties": { "headers": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 1024 }, "description": "Custom headers to send with webhook requests (max 10)", "example": { "X-Custom-Header": "value" } } }, "description": "Request configuration for webhook delivery" }, "CreateWebhookBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable name for the webhook", "example": "Production Webhook" }, "url": { "type": "string", "description": "Webhook endpoint URL (must be HTTPS)", "example": "https://example.com/webhooks" }, "description": { "type": "string", "maxLength": 500, "description": "Optional description of the webhook purpose", "example": "Handles all production events" }, "topics": { "type": "array", "items": { "type": "string", "enum": [ "post.created", "post.updated", "post.deleted", "post.voted", "changelog.published", "comment.created", "comment.updated", "comment.deleted", "conversation.user.created", "conversation.user.replied", "conversation.admin.replied", "conversation.admin.closed", "conversation.handover_requested", "conversation.admin.assigned", "conversation.admin.noted", "conversation.admin.snoozed", "conversation.admin.unsnoozed", "conversation.admin.opened", "conversation.priority.updated", "conversation.deleted", "conversation.contact.attached", "conversation.contact.detached", "conversation.read", "conversation_part.redacted" ], "description": "Webhook event topic", "example": "post.created" }, "minItems": 1, "description": "Array of event topics to subscribe to", "example": [ "post.created", "post.updated" ] }, "requestConfig": { "$ref": "#/components/schemas/WebhookRequestConfigInput" } }, "required": [ "name", "url", "topics" ] }, "UpdateWebhookBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Human-readable name for the webhook", "example": "Production Webhook" }, "url": { "type": "string", "description": "Webhook endpoint URL (must be HTTPS)", "example": "https://example.com/webhooks" }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Optional description of the webhook purpose (null to clear)", "example": "Handles all production events" }, "topics": { "type": "array", "items": { "type": "string", "enum": [ "post.created", "post.updated", "post.deleted", "post.voted", "changelog.published", "comment.created", "comment.updated", "comment.deleted", "conversation.user.created", "conversation.user.replied", "conversation.admin.replied", "conversation.admin.closed", "conversation.handover_requested", "conversation.admin.assigned", "conversation.admin.noted", "conversation.admin.snoozed", "conversation.admin.unsnoozed", "conversation.admin.opened", "conversation.priority.updated", "conversation.deleted", "conversation.contact.attached", "conversation.contact.detached", "conversation.read", "conversation_part.redacted" ], "description": "Webhook event topic", "example": "post.created" }, "minItems": 1, "description": "Array of event topics to subscribe to", "example": [ "post.created", "post.updated" ] }, "status": { "type": "string", "enum": [ "active", "paused" ], "description": "Set to \"active\" to reactivate or \"paused\" to pause webhook delivery", "example": "active" }, "requestConfig": { "$ref": "#/components/schemas/WebhookRequestConfigInput" } } }, "DeletedWebhook": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the deleted webhook", "example": "507f1f77bcf86cd799439011" }, "object": { "type": "string", "enum": [ "webhook" ], "description": "Object type identifier", "example": "webhook" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Indicates the resource was deleted", "example": true } }, "required": [ "id", "object", "deleted" ] } }, "parameters": { "FeaturebaseVersion": { "schema": { "$ref": "#/components/schemas/FeaturebaseVersion" }, "required": false, "description": "API version for this request. Defaults to your organization's configured API version if not specified.", "name": "Featurebase-Version", "in": "header" } } }, "paths": { "/v2/boards": { "get": { "operationId": "listBoards", "summary": "List all boards", "description": "Returns all boards (post categories) for the authenticated organization.\n\nBoards are containers for posts/feedback. Each board can have different:\n- Access controls (public, private, segment-restricted)\n- Feature toggles (comments, posting enabled)\n- Custom fields\n\nThis endpoint returns all boards without pagination. Organizations typically have a small number of boards.", "tags": [ "Boards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/boards/{id}": { "get": { "operationId": "getBoard", "summary": "Get a board by ID", "description": "Retrieves a single board by its unique identifier.\n\nReturns the full board object including all access controls,\nfeature toggles, and localization settings.", "tags": [ "Boards" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Board unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The board ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `board_not_found`: No board exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "board_not_found" ], "description": "Machine-readable error code", "example": "board_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts": { "get": { "operationId": "listPosts", "summary": "List all posts", "description": "Returns all posts (feedback submissions) for the authenticated organization.\n\nPosts are user-submitted feedback items. Each post belongs to a board and can have:\n- Status (in progress, complete, etc.)\n- Tags for categorization\n- Upvotes from users\n- Comments (if enabled)\n- Custom field values\n\n### Pagination\n\nThis endpoint uses **cursor-based pagination**:\n\n- `limit` - Number of posts to return (1-100, default 10)\n- `cursor` - Opaque cursor from a previous response's `nextCursor` field\n\n**Example:** To paginate through results:\n1. First request: `GET /v2/posts?limit=10`\n2. If `nextCursor` is not null, use it for the next page\n3. Next request: `GET /v2/posts?limit=10&cursor={nextCursor}`\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of post objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Filtering\n\nFilter posts using query parameters:\n- `boardId` - Filter by board (category) ID\n- `statusId` - Filter by status ID\n- `tags` - Filter by tag names (can be comma-separated or repeated)\n- `q` - Search query for title/content\n- `inReview` - Include posts pending moderation\n\n### Sorting\n\nUse `sortBy` to sort results:\n- `createdAt` - Sort by creation date (default)\n- `upvotes` - Sort by vote count\n- `trending` - Sort by trending score\n- `recent` - Sort by most recently updated", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of posts to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ], "description": "Filter by board (category) ID(s)", "example": "507f1f77bcf86cd799439011" }, "required": false, "name": "boardId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "maxItems": 50 } ], "description": "Filter by status ID(s)", "example": "507f1f77bcf86cd799439012" }, "required": false, "name": "statusId", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 50 } ], "description": "Filter by tag names", "example": [ "bug", "feature" ] }, "required": false, "name": "tags", "in": "query" }, { "schema": { "type": "string", "maxLength": 255, "description": "Search query to filter posts by title/content", "example": "dark mode" }, "required": false, "name": "q", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "description": "Include posts that are in review", "example": true }, "required": false, "name": "inReview", "in": "query" }, { "schema": { "type": "string", "enum": [ "createdAt", "upvotes", "trending", "recent" ], "default": "createdAt", "description": "Sort order for posts", "example": "upvotes" }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction", "example": "desc" }, "required": false, "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createPost", "summary": "Create a new post", "description": "Creates a new post (feedback submission) in the specified board.\n\n### Required Fields\n\n- `title` - Post title (minimum 2 characters)\n- `boardId` - Board ID to create the post in\n\n### Optional Fields\n\n- `content` - Post content in HTML format\n- `tags` - Array of tag names to attach\n- `statusId` - Status ID to set (defaults to board's default status)\n- `commentsEnabled` - Whether comments are allowed (default: true)\n- `inReview` - Whether post is pending moderation (default: false)\n- `customFields` - Custom field values as key-value pairs\n- `eta` - Estimated completion date (Unix timestamp or ISO date)\n- `assigneeId` - Admin ID to assign this post to\n- `visibility` - Post-level visibility restriction: 'public' (no additional restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only users in author's company). Note: even 'public' posts are still subject to board-level and organization-level access controls.\n\n### Author Attribution\n\nFor posts created on behalf of users, use the `author` object:\n- `id` - Featurebase user ID\n- `userId` - External SSO user ID\n- `email` - User's email address\n- `name` - Display name\n- `profilePicture` - Profile picture URL\n\nResolution priority: `id` > `userId` > `email` > authenticated user\n\n### Backdating (Imports)\n\n- `createdAt` - Override creation date for importing historical data\n\n### Response\n\nReturns the created post object with all fields populated.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePostBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid or missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `board_not_found`: The specified boardId does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "board_not_found" ], "description": "Machine-readable error code", "example": "board_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{id}": { "get": { "operationId": "getPost", "summary": "Get a post by ID", "description": "Retrieves a single post by its unique identifier.\n\nReturns the full post object including:\n- Author information\n- Current status\n- Tags\n- Voting stats\n- Engagement metrics\n- Custom field values", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updatePost", "summary": "Update a post", "description": "Updates an existing post. Only provided fields will be modified.\n\n### Updatable Fields\n\n- `title` - Post title (minimum 2 characters)\n- `content` - Post content in HTML format\n- `boardId` - Move post to a different board\n- `statusId` - Update post status\n- `tags` - Replace existing tags with new set\n- `commentsEnabled` - Enable/disable comments\n- `inReview` - Put post in/out of moderation queue\n- `customFields` - Update custom field values\n- `eta` - Set estimated completion date (null to clear)\n- `createdAt` - Update creation date (for backdating)\n- `assigneeId` - Admin ID to assign this post to (null to unassign)\n- `visibility` - Post-level visibility restriction: 'public' (no additional restrictions), 'authorOnly' (only author and admins), or 'companyOnly' (only users in author's company). Note: even 'public' posts are still subject to board-level and organization-level access controls.\n- `author` - Change post attribution (id, userId, email, name, profilePicture)\n\n### Status Update Notifications\n\n- `sendStatusUpdateEmail` - When changing status, optionally send email notification to voters (default: false)\n\n### Response\n\nReturns the updated post object with all fields populated.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePostBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Post" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid\n- `invalid_request`: Invalid update parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deletePost", "summary": "Delete a post", "description": "Permanently deletes a post. This action cannot be undone.\n\n### What Gets Deleted\n\nWhen you delete a post:\n- The post itself is permanently removed\n- All comments on the post are deleted\n- Vote records are removed\n- Any associated notifications are cleared\n\n### Response\n\nReturns a deletion confirmation object with:\n- `id` - The ID of the deleted post\n- `object` - Always \"post\"\n- `deleted` - Always true\n\n### Permissions\n\nRequires member-level access or higher to delete posts.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedPost" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/posts/{id}/voters": { "get": { "operationId": "listVoters", "summary": "List voters on a post", "description": "Returns all voters (upvoters) for a specific post.\n\nVoters are users who have upvoted the post. Each voter is returned in the standard user format with:\n- Basic info: id, name, email, profilePicture\n- User type (admin, customer, guest, etc.)\n- Companies the user belongs to\n- Activity stats: commentsCreated, postsCreated, lastActivity\n- Preferences: subscribedToChangelog, locale, verified\n\n### Pagination\n\nThis endpoint uses **cursor-based pagination**:\n\n- `limit` - Number of voters to return (1-100, default 10)\n- `cursor` - Opaque cursor from a previous response's `nextCursor` field\n\n**Example:** To paginate through results:\n1. First request: `GET /v2/posts/{id}/voters?limit=10`\n2. If `nextCursor` is not null, use it for the next page\n3. Next request: `GET /v2/posts/{id}/voters?limit=10&cursor={nextCursor}`\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of user objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Permissions\n\nRequires member-level access or higher.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of voters to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "addVoter", "summary": "Add a voter to a post", "description": "Adds a voter (upvote) to a post.\n\n### Voter Identification\n\nTo add a vote on behalf of a user, provide one or more identification fields:\n- `id` - Featurebase user ID\n- `userId` - External SSO user ID from your system\n- `email` - User's email address\n- `name` - Display name (used when creating a new user)\n- `profilePicture` - Profile picture URL (used when creating a new user)\n\nResolution priority: `id` > `userId` > `email` > authenticated user\n\nIf no fields are provided, the authenticated user's vote is added.\n\nIf the user doesn't exist, a new customer will be created with the provided information.\n\n### Idempotency\n\nIf the user has already voted on this post, the request succeeds but no duplicate vote is added.\n\n### Response\n\nReturns a confirmation object with:\n- `object` - Always \"voter\"\n- `added` - Always true\n- `id` - The voter's user ID\n- `postId` - The post ID the vote was added to\n\n### Permissions\n\nRequires member-level access or higher.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddVoterBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddVoterResponse" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid\n- `invalid_request`: Invalid voter identification parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "removeVoter", "summary": "Remove a voter from a post", "description": "Removes a voter (upvote) from a post.\n\n### Voter Identification\n\nTo remove a vote on behalf of a user, provide one or more identification fields:\n- `id` - Featurebase user ID\n- `userId` - External SSO user ID from your system\n- `email` - User's email address\n\nResolution priority: `id` > `userId` > `email` > authenticated user\n\nIf no fields are provided, the authenticated user's vote will be removed.\n\n### Response\n\nReturns a confirmation object with:\n- `object` - Always \"voter\"\n- `removed` - Always true\n- `id` - The voter's user ID\n- `postId` - The post ID the vote was removed from\n\n### Permissions\n\nRequires member-level access or higher.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveVoterBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveVoterResponse" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The post ID format is invalid\n- `invalid_request`: Invalid voter identification parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: No post exists with this ID\n- `voter_not_found`: The user has not voted on this post", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found", "voter_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/post_statuses": { "get": { "operationId": "listPostStatuses", "summary": "List all post statuses", "description": "Returns all post statuses for the authenticated organization.\n\nPost statuses define workflow stages for posts. Each status has:\n- A display name and color\n- A type indicating the workflow stage (reviewing, unstarted, active, completed, canceled)\n- A flag indicating if it's the default status for new posts\n\nThis endpoint returns all post statuses without pagination. Organizations typically have a small number of statuses.", "tags": [ "Post Statuses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatusList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/post_statuses/{id}": { "get": { "operationId": "getPostStatus", "summary": "Get a post status by ID", "description": "Retrieves a single post status by its unique identifier.\n\nReturns the full post status object including name, color, type, and default flag.", "tags": [ "Post Statuses" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Post status unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PostStatus" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The status ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `resource_not_found`: No post status exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "resource_not_found" ], "description": "Machine-readable error code", "example": "resource_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/comments": { "get": { "operationId": "listComments", "summary": "List comments", "description": "Returns comments for your organization.\n\nComments are threaded discussions. Each comment can have:\n- Author information\n- Voting (upvotes/downvotes)\n- Privacy settings (public/private)\n- Moderation status\n- Parent comment reference for threading\n\n### Filtering\n\nOptionally filter by:\n- `postId` - Get comments for a specific post\n- `changelogId` - Get comments for a specific changelog\n\nIf no filter is provided, returns all comments across the organization.\n\n### Pagination\n\nThis endpoint uses **cursor-based pagination**:\n\n- `limit` - Number of comments to return (1-100, default 10)\n- `cursor` - Opaque cursor from a previous response's `nextCursor` field\n\n**Example:** To paginate through results:\n1. First request: `GET /v2/comments?postId={id}&limit=10`\n2. If `nextCursor` is not null, use it for the next page\n3. Next request: `GET /v2/comments?postId={id}&limit=10&cursor={nextCursor}`\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of comment objects (flat structure with `parentCommentId` for threading)\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Comment Structure\n\nEach comment includes:\n- `id` - Unique comment identifier\n- `postId` / `changelogId` - Reference to the parent content\n- `parentCommentId` - Reference to parent comment (null for root comments)\n- `content` - Comment content in HTML format\n- `author` - Author information (id, name, profilePicture, type)\n- `upvotes` / `downvotes` / `score` - Voting metrics\n- `isPrivate` - Whether comment is only visible to admins\n- `inReview` - Whether comment is pending moderation\n- `created` / `updated` - Unix timestamps\n\n### Additional Filters\n\n- `privacy` - Filter by privacy: \"public\", \"private\", or \"all\"\n- `inReview` - Filter by moderation status (true/false)\n\n### Sorting\n\nUse `sortBy` to sort results:\n- `best` - Sort by confidence score (default, like Reddit)\n- `top` - Sort by net score (upvotes - downvotes)\n- `new` - Sort by creation date, newest first\n- `old` - Sort by creation date, oldest first", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Filter comments by post ID", "example": "507f1f77bcf86cd799439011" }, "required": false, "name": "postId", "in": "query" }, { "schema": { "type": "string", "description": "Filter comments by changelog ID", "example": "507f1f77bcf86cd799439012" }, "required": false, "name": "changelogId", "in": "query" }, { "schema": { "type": "string", "enum": [ "public", "private", "all" ], "description": "Filter comments by privacy", "example": "public" }, "required": false, "name": "privacy", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "description": "Filter by review status", "example": false }, "required": false, "name": "inReview", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of comments to return", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "Cursor for pagination. Use nextCursor from previous response.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "best", "top", "new", "old" ], "default": "best", "description": "Sort order for comments", "example": "best" }, "required": false, "name": "sortBy", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: The specified post or changelog was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createComment", "summary": "Create a new comment", "description": "Creates a new comment or reply to an existing comment.\n\nYou can create a comment for a post or changelog. Comments support:\n- HTML content (images are automatically uploaded to our storage)\n- Threading (replies via `parentCommentId`)\n- Privacy controls (private comments visible only to admins)\n- Author attribution (post on behalf of users)\n\n### Required Fields\n\n- `content` - Comment content in HTML format\n- `postId` OR `changelogId` - One is required to specify the target\n\n### Optional Fields\n\n- `parentCommentId` - Create a reply to an existing comment\n- `isPrivate` - Make comment visible only to admins (default: false)\n- `sendNotification` - Notify voters about the comment (default: true)\n- `author` - Post comment under a specific user (uses authenticated user if not provided)\n- `createdAt` - Backdate creation (useful for imports)\n\n### Author Object\n\nThe `author` field supports multiple identification methods:\n- `id` - Featurebase user ID (direct reference)\n- `userId` - External user ID from your system (via SSO)\n- `email` - Email address (finds existing or creates new user)\n- `name` - Display name (used with email for new users)\n- `profilePicture` - Profile picture URL\n\nIf no author is provided, the comment is posted under the authenticated user.\n\n### Content Format\n\nContent should be formatted as HTML. For images:\n- External URLs in `img src` attributes are automatically pulled into our storage\n- Base64 encoded data URIs (`data:image/...`) are also supported and processed\n\n### Response\n\nReturns the created comment object with all fields populated, including:\n- `id` - Unique comment identifier\n- `author` - Author information\n- Voting stats and timestamps\n\n### Errors\n\n- `400` - Invalid input (missing required fields, invalid IDs)\n- `403` - Commenting disabled or not authorized\n- `404` - Post/changelog not found or parent comment not found", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCommentBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid or missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `feature_disabled`: Commenting is disabled on this board", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "feature_disabled" ], "description": "Machine-readable error code", "example": "feature_disabled" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `post_not_found`: The specified post or changelog was not found\n- `comment_not_found`: The parent comment was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "post_not_found", "comment_not_found" ], "description": "Machine-readable error code", "example": "post_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/comments/{id}": { "get": { "operationId": "getComment", "summary": "Get a comment by ID", "description": "Retrieves a single comment by its unique identifier.\n\nReturns the full comment object including:\n- Author information\n- Voting stats (upvotes, downvotes, score)\n- Privacy and moderation status\n- Threading information (parentCommentId)\n- Timestamps\n\n### Response\n\nReturns a comment object with all fields populated.\n\n### Errors\n\n- `400` - Invalid comment ID format\n- `404` - Comment not found or doesn't belong to your organization", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Comment unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The comment ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `comment_not_found`: No comment exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "comment_not_found" ], "description": "Machine-readable error code", "example": "comment_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateComment", "summary": "Update a comment", "description": "Updates an existing comment by its unique identifier.\n\nYou can update:\n- **content** - Comment text (HTML format)\n- **isPrivate** - Privacy status (admin-only visibility)\n- **isPinned** - Pinned status (displayed at top)\n- **inReview** - Moderation status\n\n### Content Format\n\nContent should be formatted as HTML. For images:\n- External URLs in `img src` attributes are automatically pulled into our storage\n- Base64 encoded data URIs (`data:image/...`) are also supported and processed\n\n### Permissions\n\n- Comment authors can update their own comment content\n- Admin permissions required for:\n - `isPrivate` - Requires `manage_comments_private` permission\n - `isPinned` - Requires `set_comment_pinned` permission\n - `inReview` - Requires `moderate_comments` permission\n - Updating other users' comments - Requires `moderate_comments` permission\n\n### Response\n\nReturns the updated comment object with all fields populated.\n\n### Errors\n\n- `400` - Invalid comment ID format or input\n- `403` - Not authorized to update this comment\n- `404` - Comment not found", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Comment unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCommentBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The comment ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `comment_not_found`: No comment exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "comment_not_found" ], "description": "Machine-readable error code", "example": "comment_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteComment", "summary": "Delete a comment", "description": "Deletes a comment by its unique identifier.\n\n### Deletion Behavior\n\n- **Comments with replies**: Soft delete\n - Content is replaced with \"[deleted]\"\n - Author information is anonymized\n - Comment remains visible to maintain conversation context\n - Votes and scores are reset to 0\n\n- **Comments without replies**: Hard delete\n - Comment is permanently removed from the database\n - All associated data is deleted\n\n### Permissions\n\n- Comment authors can delete their own comments\n- Admins can delete any comment (subject to permissions)\n- Lite seat admins can only delete their own comments\n- Non-authors require `manage_comments` or `manage_comments_private` permission\n\n### Response\n\nReturns a deletion confirmation:\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"comment\",\n \"deleted\": true\n}\n```\n\n### Errors\n\n- `400` - Invalid comment ID format\n- `403` - Not authorized to delete this comment\n- `404` - Comment not found or doesn't belong to your organization", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Comment unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedComment" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The comment ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `comment_not_found`: No comment exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "comment_not_found" ], "description": "Machine-readable error code", "example": "comment_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/comment": { "delete": { "operationId": "deleteCommentClover", "summary": "Delete a comment", "description": "Deletes a comment using the legacy Clover API format.\n\nThis endpoint accepts the comment ID in the request body instead of the route parameter.\n\n### Request Body\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n### Deletion Behavior\n\n- **Comments with replies**: Soft delete\n - Content is replaced with \"[deleted]\"\n - Author information is anonymized\n - Comment remains visible to maintain conversation context\n - Votes and scores are reset to 0\n\n- **Comments without replies**: Hard delete\n - Comment is permanently removed from the database\n - All associated data is deleted\n\n### Permissions\n\n- Comment authors can delete their own comments\n- Admins can delete any comment (subject to permissions)\n- Lite seat admins can only delete their own comments\n- Non-authors require `manage_comments` or `manage_comments_private` permission\n\n### Response\n\nReturns a success confirmation (Clover format):\n\n```json\n{\n \"success\": true\n}\n```\n\nNote: Nova API returns `{ id, object: \"comment\", deleted: true }`, but Clover transformer converts it to `{ success: true }` for backwards compatibility.\n\n### Errors\n\n- `400` - Invalid comment ID format or missing ID in body\n- `403` - Not authorized to delete this comment\n- `404` - Comment not found or doesn't belong to your organization", "tags": [ "Comments" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment ID", "example": "507f1f77bcf86cd799439011" } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The comment ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `comment_not_found`: No comment exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "comment_not_found" ], "description": "Machine-readable error code", "example": "comment_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/changelogs": { "get": { "operationId": "listChangelogs", "summary": "List all changelogs", "description": "Returns all changelogs for the authenticated organization.\n\nChangelogs are release notes and updates that keep users informed about new features, improvements, and bug fixes. Each changelog can have:\n- Multiple translations (locales)\n- Categories for organization\n- Featured images\n- Scheduled publishing\n\n### Pagination\n\nThis endpoint uses **cursor-based pagination**:\n\n- `limit` - Number of changelogs to return (1-100, default 10)\n- `cursor` - Opaque cursor from a previous response's `nextCursor` field\n\n**Example:** To paginate through results:\n1. First request: `GET /v2/changelogs?limit=10`\n2. If `nextCursor` is not null, use it for the next page\n3. Next request: `GET /v2/changelogs?limit=10&cursor={nextCursor}`\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of changelog objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Filtering\n\nFilter changelogs using query parameters:\n- `id` - Find a specific changelog by ID or slug\n- `q` - Search query for title/content\n- `categories` - Filter by category names\n- `locale` - Get changelogs in a specific locale (defaults to org default)\n- `state` - Filter by state: `live`, `draft`, or `all`\n- `startDate` - Include changelogs dated on or after this date\n- `endDate` - Include changelogs dated on or before this date\n\n### Sorting\n\nResults are sorted by date (descending by default):\n- `sortBy` - Field to sort by (currently only `date`)\n- `sortOrder` - Sort direction: `asc` or `desc` (default: `desc`)", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Find changelog by its id (also accepts slug)", "example": "6457e3ff70afca5d8c27dccc" }, "required": false, "name": "id", "in": "query" }, { "schema": { "type": "string", "maxLength": 255, "description": "Search for changelogs by title or content", "example": "new feature" }, "required": false, "name": "q", "in": "query" }, { "schema": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 50 } ], "description": "Filter changelogs by category names (single value or array)", "example": [ "New", "Fixed" ] }, "required": false, "name": "categories", "in": "query" }, { "schema": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "The locale of the changelogs. Defaults to the organization default locale.", "example": "en" }, "required": false, "name": "locale", "in": "query" }, { "schema": { "type": "string", "enum": [ "draft", "live", "all" ], "default": "live", "description": "The state of the changelog. Use \"all\" to get both draft and live changelogs.", "example": "live" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": [ "string", "null" ], "description": "Include Changelogs dated on or after the specified start date", "example": "2024-01-01" }, "required": false, "name": "startDate", "in": "query" }, { "schema": { "type": [ "string", "null" ], "description": "Include Changelogs dated on or before the specified end date", "example": "2024-12-31" }, "required": false, "name": "endDate", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "Maximum number of changelogs to return", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "Cursor for pagination. Use nextCursor from previous response.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "date" ], "default": "date", "description": "Field to sort by", "example": "date" }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction", "example": "desc" }, "required": false, "name": "sortOrder", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createChangelog", "summary": "Create a new changelog", "description": "Creates a new changelog for the authenticated organization.\n\n### Required Fields\n\n- `title` - The title of the changelog\n\n### Content\n\nProvide content in one of two formats (at least one is required):\n- `htmlContent` - HTML content of the changelog\n- `markdownContent` - Markdown content of the changelog\n\n**Note:** For images in content, you can use:\n- External URLs in img src attributes (automatically uploaded to our storage)\n- Base64 encoded data URIs (data:image/...) which are processed and stored\n\n### Optional Fields\n\n- `categories` - Array of category names (e.g., [\"New\", \"Fixed\", \"Improved\"])\n- `featuredImage` - URL of the featured image (external URLs are uploaded to our storage)\n- `allowedSegmentIds` - Array of segment IDs that are allowed to view the changelog\n- `locale` - The locale of the changelog (defaults to organization default)\n- `date` - The date of the changelog\n- `state` - The state of the changelog: `draft` (default) or `live`\n\n### Response\n\nReturns the created changelog object.", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateChangelogBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changelog" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid or missing required fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/changelogs/{id}": { "get": { "operationId": "getChangelog", "summary": "Get a changelog by ID", "description": "Retrieves a single changelog by its unique identifier or slug.\n\nReturns the full changelog object including:\n- Title and content (in HTML and markdown formats)\n- Featured image\n- Publication date\n- Categories\n- Comment count\n- Email notification status\n\n### Localization\n\nThe changelog content is returned in the organization's default locale.\nIf the changelog doesn't exist in the default locale, the first available locale is used.\n\n### State\n\nBoth published (`live`) and draft changelogs can be retrieved.\nThe `state` field indicates the current publication status.", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Changelog unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changelog" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The changelog ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `changelog_not_found`: No changelog exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "changelog_not_found" ], "description": "Machine-readable error code", "example": "changelog_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateChangelog", "summary": "Update a changelog", "description": "Updates an existing changelog by its unique identifier.\n\nYou can update:\n- **title** - The changelog title\n- **htmlContent** - HTML content (one of htmlContent or markdownContent)\n- **markdownContent** - Markdown content (one of htmlContent or markdownContent)\n- **categories** - Array of category names\n- **featuredImage** - Featured image URL\n- **allowedSegmentIds** - Segment IDs for access control\n- **date** - The date of the changelog\n\n### Content Format\n\nProvide content in one of two formats:\n- `htmlContent` - HTML content of the changelog\n- `markdownContent` - Markdown content of the changelog\n\n**Note:** For images in content, you can use:\n- External URLs in img src attributes (automatically uploaded to our storage)\n- Base64 encoded data URIs (data:image/...) which are processed and stored\n\n### Categories\n\nProvide category names as an array. The categories must already exist in your organization.\n\n**Example:** `[\"New\", \"Fixed\", \"Improved\"]`\n\n### Response\n\nReturns the updated changelog object with all fields populated.\n\n### Errors\n\n- `400` - Invalid changelog ID format or invalid input\n- `404` - Changelog not found or doesn't belong to your organization", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Changelog unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateChangelogBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Changelog" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The changelog ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `changelog_not_found`: No changelog exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "changelog_not_found" ], "description": "Machine-readable error code", "example": "changelog_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteChangelog", "summary": "Delete a changelog", "description": "Deletes a changelog by its unique identifier.\n\n### Deletion Behavior\n\nThe changelog and all associated comments are permanently deleted. This action cannot be undone.\n\n### Permissions\n\nOnly organization admins can delete changelogs.\n\n### Response\n\nReturns a deletion confirmation:\n\n```json\n{\n \"id\": \"6457e3ff70afca5d8c27dccc\",\n \"object\": \"changelog\",\n \"deleted\": true\n}\n```\n\n### Errors\n\n- `400` - Invalid changelog ID format\n- `404` - Changelog not found or doesn't belong to your organization", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Changelog unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedChangelog" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The changelog ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `changelog_not_found`: No changelog exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "changelog_not_found" ], "description": "Machine-readable error code", "example": "changelog_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/changelogs/{id}/publish": { "post": { "operationId": "publishChangelog", "summary": "Publish a changelog", "description": "Publishes a changelog and optionally sends an email notification to subscribers.\n\n### Optional Fields\n\n- `sendEmail` - Whether to send an email notification to subscribers (default: false)\n- `locales` - Array of locales to publish. An empty array publishes to all available locales\n- `scheduledDate` - A future date/time when the changelog should be published\n\n### Scheduling\n\nIf `scheduledDate` is provided:\n- Must be a future date\n- The changelog will be scheduled for publishing at that time\n- Any existing scheduled publish for the same locales will be cancelled and replaced\n\n### Email Notifications\n\nIf `sendEmail` is true:\n- Email notifications are sent to all subscribers in the published locales\n- Emails are only sent once per locale (won't resend on republish)\n\n### Response\n\nReturns a success confirmation:\n\n```json\n{\n \"success\": true,\n \"state\": \"published\"\n}\n```\n\nOr for scheduled publishes:\n\n```json\n{\n \"success\": true,\n \"state\": \"scheduled\"\n}\n```\n\n### Errors\n\n- `400` - Invalid changelog ID or scheduled date is not in the future\n- `404` - Changelog not found or doesn't belong to your organization", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Changelog unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishChangelogBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishUnpublishSuccess" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The changelog ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `changelog_not_found`: No changelog exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "changelog_not_found" ], "description": "Machine-readable error code", "example": "changelog_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/changelogs/{id}/unpublish": { "post": { "operationId": "unpublishChangelog", "summary": "Unpublish a changelog", "description": "Unpublishes a changelog, removing it from public view.\n\n### Optional Fields\n\n- `locales` - Array of locales to unpublish from. An empty array unpublishes from all locales\n\n### Behavior\n\n- The changelog content is preserved (reverts to draft state)\n- Any scheduled publishes for the specified locales are cancelled\n- The changelog can be re-published later\n\n### Response\n\nReturns a success confirmation:\n\n```json\n{\n \"success\": true,\n \"state\": \"unpublished\"\n}\n```\n\n### Errors\n\n- `400` - Invalid changelog ID format\n- `404` - Changelog not found or doesn't belong to your organization", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Changelog unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnpublishChangelogBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublishUnpublishSuccess" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The changelog ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `changelog_not_found`: No changelog exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "changelog_not_found" ], "description": "Machine-readable error code", "example": "changelog_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/changelogs/subscribers": { "post": { "operationId": "addChangelogSubscribers", "summary": "Add changelog subscribers", "description": "Adds email addresses as changelog subscribers in bulk.\n\nSubscribers will receive email notifications when new changelogs are published (if email notifications are enabled during publishing).\n\n### Request Body\n\n- `emails` - Array of email addresses to add (required, 1-1000 emails)\n- `locale` - Locale for the subscribers (optional, defaults to organization default)\n\n### Email Validation\n\n- Invalid email addresses are automatically filtered out\n- Emails are normalized (trimmed, lowercased)\n- Duplicate emails are deduplicated\n\n### Rate Limiting\n\nThis endpoint is rate limited to prevent abuse. If you need to import more subscribers, please contact support.\n\n### Response\n\nReturns a confirmation with the count of processed emails:\n\n```json\n{\n \"object\": \"changelog_subscribers_import\",\n \"count\": 150\n}\n```\n\n### Errors\n\n- `400` - Invalid request (empty emails array, too many emails)\n- `429` - Rate limit exceeded", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddChangelogSubscribersBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogSubscribersImport" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Empty emails array or too many emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "removeChangelogSubscribers", "summary": "Remove changelog subscribers", "description": "Removes email addresses from changelog subscribers in bulk.\n\nRemoved subscribers will no longer receive email notifications when new changelogs are published.\n\n### Request Body\n\n- `emails` - Array of email addresses to remove (required, 1-1000 emails)\n\n### Email Handling\n\n- Emails that don't exist as subscribers are silently ignored\n- Emails are normalized (trimmed, lowercased) before matching\n\n### Response\n\nReturns a confirmation with the count of processed emails:\n\n```json\n{\n \"object\": \"changelog_subscribers_removal\",\n \"count\": 150\n}\n```\n\n### Errors\n\n- `400` - Invalid request (empty emails array, too many emails)", "tags": [ "Changelogs" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveChangelogSubscribersBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogSubscribersRemoval" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Empty emails array or too many emails", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/admins": { "get": { "operationId": "listAdmins", "summary": "List admins", "description": "Returns all admins for your organization.\n\nThis endpoint returns all admins at once (typically a small list). No pagination is supported.\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of admin objects\n- `nextCursor` - Always null\n\n### Admin Object\n\nEach admin includes:\n- `id` - Unique admin identifier\n- `name` - Admin's display name\n- `email` - Admin's email address\n- `picture` - Profile picture URL\n- `roleId` - ID of the role assigned to this admin", "tags": [ "Admins" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/admins/{id}": { "get": { "operationId": "getAdmin", "summary": "Get an admin by ID", "description": "Retrieves a single admin by their unique identifier.\n\nReturns the admin object if found and they belong to your organization.\n\n### Response\n\nReturns an admin object with:\n- `id` - Unique admin identifier\n- `name` - Admin's display name\n- `email` - Admin's email address\n- `picture` - Profile picture URL\n- `roleId` - ID of the role assigned to this admin\n\n### Errors\n\n- `404` - Admin not found or doesn't belong to your organization", "tags": [ "Admins" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Admin unique identifier", "example": "5fef50c5e9458a0012f82456" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Admin" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The admin ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `admin_not_found`: No admin exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "admin_not_found" ], "description": "Machine-readable error code", "example": "admin_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/admins/roles": { "get": { "operationId": "listAdminRoles", "summary": "List admin roles", "description": "Returns all available admin roles and their permissions.\n\nThis endpoint returns all roles at once (typically a small list). No pagination is supported.\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of admin role objects\n- `nextCursor` - Always null\n\n### Admin Role Object\n\nEach role includes:\n- `id` - Unique role identifier\n- `name` - Role name (e.g., \"Admin\", \"Viewer\")\n- `permissions` - Object containing permission flags\n\n### Permissions\n\nThe permissions object contains boolean flags for each permission:\n- `view_comments_private` - Can view private comments\n- `manage_comments` - Can manage comments\n- `manage_comments_private` - Can manage private comments\n- `set_comment_pinned` - Can pin comments\n- `moderate_comments` - Can moderate comments\n- `set_post_category` - Can change post categories\n- `set_post_pinned` - Can pin posts\n- `set_post_eta` - Can set post ETA\n- `set_post_tags` - Can manage post tags\n- `set_post_author` - Can change post author\n- `set_post_status` - Can change post status\n- `set_post_assignee` - Can assign posts\n- `set_post_custom_fields` - Can edit custom fields\n- `post_vote_on_behalf` - Can vote on behalf of users\n- `post_merge` - Can merge posts\n- `post_import` - Can import posts\n- `post_export` - Can export posts\n- `moderate_posts` - Can moderate posts\n- `view_users` - Can view users\n- `manage_users` - Can manage users\n- `view_posts_private` - Can view private posts\n- `view_private_post_tags` - Can view private tags\n- `manage_changelogs` - Can manage changelogs\n- `manage_surveys` - Can manage surveys\n- `manage_branding` - Can manage branding\n- `manage_billing` - Can manage billing\n- `manage_team_members` - Can manage team members\n- `manage_sso` - Can manage SSO settings\n- `manage_api` - Can manage API settings\n- `manage_statuses` - Can manage statuses\n- `manage_boards` - Can manage boards\n- `manage_post_tags` - Can manage post tags\n- `manage_custom_fields` - Can manage custom fields\n- `manage_moderation_settings` - Can manage moderation\n- `manage_roadmap` - Can manage roadmap\n- `manage_user_roles` - Can manage user roles\n- `manage_prioritization` - Can manage prioritization\n- `manage_notifications` - Can manage notifications\n- `manage_custom_domain` - Can manage custom domain\n- `manage_integrations` - Can manage integrations\n- `use_integrations` - Can use integrations\n- `manage_help_center` - Can manage help center\n- `auto_approve_posts` - Posts auto-approved", "tags": [ "Admins" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdminRoleList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/custom_fields": { "get": { "operationId": "listCustomFields", "summary": "List custom fields", "description": "Returns all custom fields configured in your organization.\n\nThis endpoint returns all custom fields at once (typically a small list). No pagination is supported.\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of custom field objects\n- `nextCursor` - Always null\n\n### Custom Field Object\n\nEach custom field includes:\n- `id` - Unique field identifier\n- `label` - Field label displayed to users\n- `type` - Field type (text, number, select, multi-select, checkbox, date)\n- `required` - Whether the field is required\n- `placeholder` - Placeholder text (for text/number fields)\n- `public` - Whether the field value is publicly visible\n- `internal` - Whether the field is for internal use only\n- `options` - Array of options (for select/multi-select fields)\n\n### Field Types\n\n- `text` - Single line text input\n- `number` - Numeric input\n- `select` - Single-choice dropdown\n- `multi-select` - Multiple-choice dropdown\n- `checkbox` - Boolean checkbox\n- `date` - Date picker", "tags": [ "Custom Fields" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomFieldList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/custom_fields/{id}": { "get": { "operationId": "getCustomField", "summary": "Get a custom field by ID", "description": "Retrieves a single custom field by its unique identifier.\n\nReturns the custom field object if found in your organization.\n\n### Response\n\nReturns a custom field object with:\n- `id` - Unique field identifier\n- `label` - Field label displayed to users\n- `type` - Field type (text, number, select, multi-select, checkbox, date)\n- `required` - Whether the field is required\n- `placeholder` - Placeholder text (for text/number fields)\n- `public` - Whether the field value is publicly visible\n- `internal` - Whether the field is for internal use only\n- `options` - Array of options (for select/multi-select fields)\n\n### Errors\n\n- `404` - Custom field not found in your organization", "tags": [ "Custom Fields" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Custom field unique identifier", "example": "65d26304b2e65b1e1278170c" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomField" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The custom field ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `custom_field_not_found`: No custom field exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "custom_field_not_found" ], "description": "Machine-readable error code", "example": "custom_field_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/surveys": { "get": { "operationId": "listSurveys", "summary": "List surveys", "description": "Returns all surveys configured in your Featurebase organization.\n\n### Query Parameters\n\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n- `type` - Filter by survey page type (text, link, rating, multiple-choice)\n- `isActive` - Filter by active status\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of survey objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Survey Object\n\nEach survey includes:\n- `id` - Unique identifier\n- `title` - Survey title\n- `description` - Survey description\n- `isActive` - Whether the survey is active\n- `responseCount` - Number of responses received\n- `targeting` - Targeting configuration (segments, URLs, CSS selectors)\n- `pages` - Array of survey pages/questions\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Surveys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.", "example": "eyJpZCI6IjY3NDM3NTJjYTgxYWU1OWQyNWNmODM0YiJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "text", "link", "rating", "multiple-choice" ], "description": "Filter by survey page type", "example": "rating" }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": [ "boolean", "null" ], "description": "Filter by active status", "example": true }, "required": false, "name": "isActive", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/surveys/{id}": { "get": { "operationId": "getSurvey", "summary": "Get a survey by ID", "description": "Retrieves a single survey by its unique identifier.\n\nReturns the survey object if found in your organization.\n\n### Response\n\nReturns a survey object with:\n- `id` - Unique identifier\n- `title` - Survey title\n- `description` - Survey description\n- `isActive` - Whether the survey is active\n- `responseCount` - Number of responses received\n- `targeting` - Targeting configuration\n- `pages` - Array of survey pages/questions\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Survey Pages\n\nEach page represents a question or screen in the survey:\n- `type` - Page type (text, link, rating, multiple-choice)\n- `title` - Question title\n- `description` - Optional description\n- `logic` - Conditional logic rules\n- `defaultAction` - Default action when no logic matches\n\n### Errors\n\n- `404` - Survey not found in your organization", "tags": [ "Surveys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Survey unique identifier", "example": "6743752ca81ae59d25cf834b" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Survey" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The survey ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `survey_not_found`: No survey exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "survey_not_found" ], "description": "Machine-readable error code", "example": "survey_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/surveys/{id}/responses": { "get": { "operationId": "getSurveyResponses", "summary": "Get survey responses", "description": "Retrieves all user responses for a specific survey.\n\n### Query Parameters\n\n- `pageId` - Filter responses to a specific survey page\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of survey response objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Survey Response Object\n\nEach response includes:\n- `id` - Unique response identifier\n- `user` - User who submitted the response (may be null for anonymous)\n- `responses` - Array of individual answers\n- `createdAt` - ISO 8601 timestamp when submitted\n\n### Individual Response\n\nEach item in the responses array:\n- `pageId` - The survey page this response is for\n- `type` - Response type (text, rating, multiple-choice)\n- `value` - The response value\n\n### Errors\n\n- `404` - Survey not found in your organization", "tags": [ "Surveys" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Survey unique identifier", "example": "6743752ca81ae59d25cf834b" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "Filter by survey page ID", "example": "6743752ca81ae59d25cf834c" }, "required": false, "name": "pageId", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.", "example": "eyJpZCI6IjY3MTJlMmQxNzU5MDRjZTI0YjJmOTYzNyJ9" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SurveyResponseList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The survey ID format is invalid\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `survey_not_found`: No survey exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "survey_not_found" ], "description": "Machine-readable error code", "example": "survey_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/help_centers": { "get": { "operationId": "listHelpCenters", "summary": "List help centers", "description": "Returns all help centers configured in your Featurebase organization.\n\nCurrently, Featurebase only supports one help center per organization, but we plan on supporting multiple help centers in the future.\n\n### Query Parameters\n\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of help center objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Help Center Object\n\nEach help center includes:\n- `id` - Unique identifier\n- `displayName` - Help center display name\n- `title` - Help center title\n- `description` - Help center description\n- `isPublic` - Whether the help center is publicly accessible\n- `defaultLocale` - Default locale for content\n- `availableLocales` - Array of available locales\n- `navItems` - Navigation items configuration\n- `urls` - URL configuration (subpath, custom domain)\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.", "example": "eyJpZCI6IjJ0Z3kwaWc5ODJqNTRxZmwifQ" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpCenterList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/help_centers/{id}": { "get": { "operationId": "getHelpCenter", "summary": "Get a help center by ID", "description": "Retrieves a single help center by its unique identifier.\n\nReturns the help center object if found in your organization.\n\n### Response\n\nReturns a help center object with:\n- `id` - Unique identifier\n- `displayName` - Help center display name\n- `title` - Help center title\n- `description` - Help center description\n- `searchPlaceholder` - Search input placeholder text\n- `isPublic` - Whether the help center is publicly accessible\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `navItems` - Navigation items configuration\n- `urls` - URL configuration (subpath, custom domain)\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `404` - Help center not found in your organization", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Help center unique identifier", "example": "2tgy0ig982j54qfl" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HelpCenter" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The help center ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `help_center_not_found`: No help center exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "help_center_not_found" ], "description": "Machine-readable error code", "example": "help_center_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/collections": { "get": { "operationId": "listCollections", "summary": "List collections", "description": "Returns a paginated list of collections within your organization's help center.\n\nCollections are used to organize articles into logical groups.\n\n### Query Parameters\n\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of collection objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Collection Object\n\nEach collection includes:\n- `id` - Unique identifier\n- `name` - Collection name\n- `description` - Collection description\n- `slug` - URL slug\n- `icon` - Collection icon (emoji or custom)\n- `parentId` - Parent collection ID (null for root collections)\n- `helpCenterId` - ID of the help center this collection belongs to\n- `organization` - Organization ID\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `featurebaseUrl` - Featurebase URL for the collection\n- `externalUrl` - External URL if custom domain is configured\n- `articleCount` - Number of articles in this collection\n- `authorCount` - Number of authors who contributed\n- `order` - Display order\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.", "example": "eyJpZCI6IjY0NzQ2ODQifQ" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Filter collections by help center ID. If omitted, returns collections across all help centers.", "example": "h7l3snparrtl08hn" }, "required": false, "name": "helpCenterId", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createCollection", "summary": "Create a collection", "description": "Creates a new collection in your organization's help center.\n\n### Request Body\n\nRequired attributes:\n- `name` - The name of the collection\n\nOptional attributes:\n- `description` - A description of the collection\n- `icon` - An icon object representing the collection icon (with type and value)\n- `parentId` - The ID of the parent collection, if any\n- `translations` - A dictionary of translations keyed by locale\n\n### Response\n\nReturns the created collection object with:\n- `id` - Unique identifier\n- `name` - Collection name\n- `description` - Collection description\n- `slug` - URL slug\n- `icon` - Collection icon (emoji or custom)\n- `parentId` - Parent collection ID (null for root collections)\n- `helpCenterId` - ID of the help center this collection belongs to\n- `organization` - Organization ID\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `featurebaseUrl` - Featurebase URL for the collection\n- `externalUrl` - External URL if custom domain is configured\n- `articleCount` - Number of articles in this collection\n- `authorCount` - Number of authors who contributed\n- `order` - Display order\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCollectionBody_Nova" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid collection data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/collections/{id}": { "get": { "operationId": "getCollection", "summary": "Get a collection by ID", "description": "Retrieves a specific collection by its unique identifier.\n\nReturns the collection object if found in your organization's help center.\n\n### Response\n\nReturns a collection object with:\n- `id` - Unique identifier\n- `name` - Collection name\n- `description` - Collection description\n- `slug` - URL slug\n- `icon` - Collection icon (emoji or custom)\n- `parentId` - Parent collection ID (null for root collections)\n- `helpCenterId` - ID of the help center this collection belongs to\n- `organization` - Organization ID\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `featurebaseUrl` - Featurebase URL for the collection\n- `externalUrl` - External URL if custom domain is configured\n- `articleCount` - Number of articles in this collection\n- `authorCount` - Number of authors who contributed\n- `order` - Display order\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `404` - Collection not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Collection unique identifier", "example": "6474684" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The collection ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `collection_not_found`: No collection exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "collection_not_found" ], "description": "Machine-readable error code", "example": "collection_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateCollection", "summary": "Update a collection", "description": "Updates an existing collection. Only include the fields you wish to update.\n\n### Path Parameters\n\n- `id` - The unique identifier of the collection to update\n\n### Request Body\n\nAll fields are optional. Only provided fields will be updated:\n- `name` - The new name of the collection\n- `description` - The new description of the collection\n- `icon` - An updated icon object for the collection (with type and value)\n- `parentId` - The new parent collection ID, if applicable (null for root level)\n- `translations` - A dictionary of updated translations keyed by locale code\n\n### Response\n\nReturns the updated collection object with:\n- `id` - Unique identifier\n- `name` - Collection name\n- `description` - Collection description\n- `slug` - URL slug\n- `icon` - Collection icon (emoji or custom)\n- `parentId` - Parent collection ID (null for root collections)\n- `helpCenterId` - ID of the help center this collection belongs to\n- `organization` - Organization ID\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `featurebaseUrl` - Featurebase URL for the collection\n- `externalUrl` - External URL if custom domain is configured\n- `articleCount` - Number of articles in this collection\n- `authorCount` - Number of authors who contributed\n- `order` - Display order\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `404` - Collection not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The collection unique identifier", "example": "3416135" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCollectionBody_Nova" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The collection ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `collection_not_found`: No collection exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "collection_not_found" ], "description": "Machine-readable error code", "example": "collection_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteCollection", "summary": "Delete a collection", "description": "Deletes an existing collection.\n\n### Path Parameters\n\n- `id` - The unique identifier of the collection to delete\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The ID of the deleted collection\n- `object` - Always \"collection\"\n- `deleted` - Always true\n\n### Errors\n\n- `404` - Collection not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The collection unique identifier", "example": "3416135" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedCollection" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The collection ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `collection_not_found`: No collection exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "collection_not_found" ], "description": "Machine-readable error code", "example": "collection_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/articles": { "get": { "operationId": "listArticles", "summary": "List articles", "description": "Returns a paginated list of articles within your organization's help center.\n\nArticles are the main content pieces that contain documentation, guides, and FAQs.\n\n### Query Parameters\n\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n- `state` - Filter by article state: \"live\", \"draft\", or \"all\" (default \"live\")\n- `parentId` - Filter by parent collection ID\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of article objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Article Object\n\nEach article includes:\n- `id` - Unique identifier\n- `title` - Article title\n- `description` - Article description\n- `body` - Article content (HTML)\n- `slug` - URL slug\n- `icon` - Article icon (emoji or custom)\n- `parentId` - Parent collection ID\n- `helpCenterId` - ID of the help center this article belongs to\n- `organization` - Organization ID\n- `state` - Article state (live or draft)\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `publishedLocales` - Array of locales where article is published\n- `featurebaseUrl` - Featurebase URL for the article\n- `externalUrl` - External URL if custom domain is configured\n- `author` - Author information (name, authorId, avatarUrl)\n- `order` - Display order\n- `isPublished` - Whether the article is published\n- `isDraftDiffersFromLive` - Whether draft differs from live version\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n- `liveUpdatedAt` - ISO 8601 timestamp when live version was last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "live", "draft", "all" ], "default": "live", "description": "Filter articles by state. Use \"all\" to get both draft and live articles.", "example": "live" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Filter articles by parent collection ID", "example": "6474684" }, "required": false, "name": "parentId", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Filter articles by help center ID. If omitted, returns articles across all help centers.", "example": "h7l3snparrtl08hn" }, "required": false, "name": "helpCenterId", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArticleList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createArticle", "summary": "Create an article", "description": "Creates a new article in your organization's help center.\n\n### Request Body\n\nRequired attributes:\n- `title` - The title of the article\n\nOptional attributes:\n- `description` - A brief description of the article\n- `body` - The HTML content of the article (supports external image URLs and base64 data URIs)\n- `formatter` - Content formatter: \"default\" or \"ai\" (AI converts markdown/html to Featurebase format)\n- `parentId` - The ID of the parent collection\n- `icon` - Icon object with type and value\n- `state` - \"live\" or \"draft\" (defaults to \"draft\")\n- `translations` - Dictionary of translations keyed by locale\n\n### Response\n\nReturns the created article object with:\n- `id` - Unique identifier\n- `title` - Article title\n- `description` - Article description\n- `body` - Article content (HTML)\n- `slug` - URL slug\n- `icon` - Article icon (emoji or custom)\n- `parentId` - Parent collection ID\n- `helpCenterId` - ID of the help center this article belongs to\n- `organization` - Organization ID\n- `state` - Article state (live or draft)\n- `author` - Author information (name, authorId, avatarUrl)\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateArticleBody_Nova" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid article data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/articles/{id}": { "get": { "operationId": "getArticle", "summary": "Get an article by ID", "description": "Retrieves a specific article by its unique identifier.\n\nReturns the article object if found in your organization's help center.\n\n### Query Parameters\n\n- `state` - Article state to retrieve: \"live\" or \"draft\" (default \"live\")\n\n### Response\n\nReturns an article object with:\n- `id` - Unique identifier\n- `title` - Article title\n- `description` - Article description\n- `body` - Article content (HTML)\n- `slug` - URL slug\n- `icon` - Article icon (emoji or custom)\n- `parentId` - Parent collection ID\n- `helpCenterId` - ID of the help center this article belongs to\n- `organization` - Organization ID\n- `state` - Article state (live or draft)\n- `defaultLocale` - Default locale for content\n- `locale` - Current locale\n- `availableLocales` - Array of available locales\n- `publishedLocales` - Array of locales where article is published\n- `featurebaseUrl` - Featurebase URL for the article\n- `externalUrl` - External URL if custom domain is configured\n- `author` - Author information (name, authorId, avatarUrl)\n- `order` - Display order\n- `isPublished` - Whether the article is published\n- `isDraftDiffersFromLive` - Whether draft differs from live version\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n- `liveUpdatedAt` - ISO 8601 timestamp when live version was last updated\n\n### Errors\n\n- `404` - Article not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Article unique identifier", "example": "1234567" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "enum": [ "live", "draft" ], "default": "live", "description": "Article state to retrieve", "example": "live" }, "required": false, "name": "state", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The article ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `article_not_found`: No article exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "article_not_found" ], "description": "Machine-readable error code", "example": "article_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateArticle", "summary": "Update an article", "description": "Updates an existing article. Only include the fields you wish to update.\n\n### Path Parameters\n\n- `id` - The unique identifier of the article to update\n\n### Request Body\n\nAll fields are optional. Only provided fields will be updated:\n- `title` - The new title of the article\n- `description` - The new description of the article\n- `body` - The new HTML content of the article\n- `formatter` - Content formatter: \"default\" or \"ai\"\n- `icon` - Updated icon object for the article\n- `parentId` - New parent collection ID\n- `authorId` - ID of the new author (must be a member of the organization)\n- `state` - \"live\" or \"draft\" - if \"live\", publishes immediately\n- `translations` - Dictionary of updated translations keyed by locale\n\n### Response\n\nReturns the updated article object with:\n- `id` - Unique identifier\n- `title` - Article title\n- `description` - Article description\n- `body` - Article content (HTML)\n- `slug` - URL slug\n- `icon` - Article icon (emoji or custom)\n- `parentId` - Parent collection ID\n- `helpCenterId` - ID of the help center this article belongs to\n- `organization` - Organization ID\n- `state` - Article state (live or draft)\n- `author` - Author information (name, authorId, avatarUrl)\n- `translations` - Translations for different locales\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `404` - Article not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The article unique identifier", "example": "1234567" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateArticleBody_Nova" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The article ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `article_not_found`: No article exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "article_not_found" ], "description": "Machine-readable error code", "example": "article_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteArticle", "summary": "Delete an article", "description": "Deletes an existing article.\n\n### Path Parameters\n\n- `id` - The unique identifier of the article to delete\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The ID of the deleted article\n- `object` - Always \"article\"\n- `deleted` - Always true\n\n### Errors\n\n- `404` - Article not found in your organization's help center", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "The article unique identifier", "example": "1234567" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedArticle" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The article ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `article_not_found`: No article exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "article_not_found" ], "description": "Machine-readable error code", "example": "article_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/redirect_rules": { "get": { "operationId": "listRedirectRules", "summary": "List redirect rules", "description": "Returns a paginated list of redirect rules within your organization.\n\nRedirect rules map old Help Center URLs to new article or collection destinations, enabling seamless migration from legacy help center systems. Only Help Centers with a custom domain configured support redirect rules.\n\n### Query Parameters\n\n- `limit` - Number of items to return (1-100, default 10)\n- `cursor` - Cursor for pagination\n- `helpCenterId` - Filter by help center ID\n- `locale` - Filter by locale code\n- `targetType` - Filter by target type (\"article\" or \"collection\")\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of redirect rule objects\n- `nextCursor` - Cursor for next page (null if no more results)\n\n### Redirect Rule Object\n\nEach redirect rule includes:\n- `id` - Unique identifier (MongoDB ObjectId)\n- `helpCenterId` - Help center this rule belongs to\n- `locale` - Locale code used to resolve the target translation\n- `fromUrl` - Canonical source URL (query/hash stripped, hostname lowercased)\n- `targetType` - \"article\" or \"collection\"\n- `targetId` - ID of the target article or collection\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Filter redirect rules by help center ID", "example": "ox6qrqprmsuqaunj" }, "required": false, "name": "helpCenterId", "in": "query" }, { "schema": { "type": "string", "enum": [ "bn", "bs", "pt-BR", "bg", "ca", "hr", "cs", "da", "nl", "en", "et", "fi", "fr", "de", "el", "hi", "hu", "id", "it", "ja", "ko", "lv", "lt", "ms", "mn", "nb", "pl", "pt", "ro", "ru", "sr", "zh-CN", "sk", "sl", "es", "sw", "sv", "th", "zh-TW", "tr", "uk", "vi" ], "description": "Filter redirect rules by locale", "example": "en" }, "required": false, "name": "locale", "in": "query" }, { "schema": { "type": "string", "enum": [ "article", "collection" ], "description": "Filter redirect rules by target type", "example": "article" }, "required": false, "name": "targetType", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectRuleList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createRedirectRule", "summary": "Create a redirect rule", "description": "Creates a new redirect rule in your organization.\n\nThe `fromUrl` is normalized on creation: query parameters and hash fragments are stripped, the hostname is lowercased, and trailing slashes are removed. The `fromUrl` hostname must match the Help Center's configured custom domain.\n\nThe target article or collection must exist and have a resolvable URL (i.e., a published translation with a slug).\n\n### Request Body\n\nRequired attributes:\n- `helpCenterId` - The ID of the help center this rule belongs to\n- `locale` - Locale code used to resolve the target translation\n- `fromUrl` - The full absolute URL to redirect from (must match the help center's custom domain)\n- `targetType` - \"article\" or \"collection\"\n- `targetId` - The ID of the target article or collection\n\n### Response\n\nReturns the created redirect rule object.\n\n### Errors\n\n- `400` - Invalid request data, fromUrl does not match custom domain, or target not found", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRedirectRuleBody_Nova" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectRule" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid redirect rule data\n- `business_validation_error`: fromUrl hostname does not match the Help Center custom domain, or a redirect rule already exists for this fromUrl\n- `resource_not_found`: Target article or collection does not exist or has no resolvable URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request", "business_validation_error", "resource_not_found" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/redirect_rules/by-url": { "get": { "operationId": "getRedirectRuleByUrl", "summary": "Get a redirect rule by URL", "description": "Retrieves a specific redirect rule by its source URL.\n\nThe `url` query parameter is normalized before matching: query parameters and hash fragments are stripped, the hostname is lowercased, and trailing slashes are removed. This is the same normalization applied when creating a redirect rule.\n\n### Query Parameters\n\n- `url` (required) - Full absolute URL to look up (http or https)\n\n### Response\n\nReturns a redirect rule object with:\n- `id` - Unique identifier (MongoDB ObjectId)\n- `helpCenterId` - Help center this rule belongs to\n- `locale` - Locale code\n- `fromUrl` - Canonical source URL being redirected from\n- `targetType` - \"article\" or \"collection\"\n- `targetId` - ID of the target article or collection\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `400` - Invalid URL format\n- `404` - No redirect rule exists for the given URL", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "maxLength": 2048, "description": "Full absolute URL to look up. The URL is normalized before matching: query parameters and hash fragments are stripped, the hostname is lowercased, and trailing slashes are removed.", "example": "https://help.example.com/en/old/getting-started" }, "required": true, "name": "url", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectRule" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_parameter`: The URL format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter" ], "description": "Machine-readable error code", "example": "invalid_parameter" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `redirect_rule_not_found`: No redirect rule exists for the given URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "redirect_rule_not_found" ], "description": "Machine-readable error code", "example": "redirect_rule_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/help_center/redirect_rules/{id}": { "get": { "operationId": "getRedirectRule", "summary": "Get a redirect rule by ID", "description": "Retrieves a specific redirect rule by its unique identifier.\n\nReturns the redirect rule object if found in your organization.\n\n### Response\n\nReturns a redirect rule object with:\n- `id` - Unique identifier (MongoDB ObjectId)\n- `helpCenterId` - Help center this rule belongs to\n- `locale` - Locale code\n- `fromUrl` - Canonical source URL being redirected from\n- `targetType` - \"article\" or \"collection\"\n- `targetId` - ID of the target article or collection\n- `createdAt` - ISO 8601 timestamp when created\n- `updatedAt` - ISO 8601 timestamp when last updated\n\n### Errors\n\n- `404` - Redirect rule not found in your organization", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Redirect rule unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectRule" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The redirect rule ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `redirect_rule_not_found`: No redirect rule exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "redirect_rule_not_found" ], "description": "Machine-readable error code", "example": "redirect_rule_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateRedirectRule", "summary": "Update a redirect rule", "description": "Updates an existing redirect rule. Only include the fields you wish to update.\n\nIf `fromUrl` is provided, it will be re-normalized and validated against the Help Center's custom domain. If `targetType` or `targetId` is changed, the new target must exist and have a resolvable URL.\n\n### Path Parameters\n\n- `id` - The unique identifier of the redirect rule to update\n\n### Request Body\n\nAll fields are optional. Only provided fields will be updated:\n- `helpCenterId` - The help center ID\n- `locale` - Locale code\n- `fromUrl` - Updated source URL (will be re-normalized)\n- `targetType` - \"article\" or \"collection\"\n- `targetId` - ID of the new target article or collection\n\n### Response\n\nReturns the updated redirect rule object.\n\n### Errors\n\n- `404` - Redirect rule not found\n- `400` - Invalid data, domain mismatch, duplicate fromUrl, or target not found", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Redirect rule unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRedirectRuleBody_Nova" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedirectRule" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The redirect rule ID format is invalid\n- `business_validation_error`: fromUrl hostname does not match the Help Center custom domain, or a redirect rule already exists for this fromUrl\n- `resource_not_found`: Target article or collection does not exist or has no resolvable URL", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "business_validation_error", "resource_not_found" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `redirect_rule_not_found`: No redirect rule exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "redirect_rule_not_found" ], "description": "Machine-readable error code", "example": "redirect_rule_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteRedirectRule", "summary": "Delete a redirect rule", "description": "Deletes an existing redirect rule. The associated Redis cache entry is also invalidated.\n\n### Path Parameters\n\n- `id` - The unique identifier of the redirect rule to delete\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The ID of the deleted redirect rule\n- `object` - Always \"redirect_rule\"\n- `deleted` - Always true\n\n### Errors\n\n- `404` - Redirect rule not found in your organization", "tags": [ "Help Centers" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Redirect rule unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedRedirectRule" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The redirect rule ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `redirect_rule_not_found`: No redirect rule exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "redirect_rule_not_found" ], "description": "Machine-readable error code", "example": "redirect_rule_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/contacts": { "get": { "operationId": "listContacts", "summary": "List contacts", "description": "Returns a list of contacts (customers and leads) in your organization using cursor-based pagination.\n\n### Query Parameters\n\n- `limit` - Number of contacts to return (1-100, default 10)\n- `cursor` - Cursor from previous response for pagination\n- `contactType` - Filter by contact type: \"customer\" (default), \"lead\", or \"all\"\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of contact objects\n- `nextCursor` - Cursor for the next page, or null if no more results\n\n### Contact Object\n\nEach contact includes:\n- `id` - Unique contact identifier\n- `userId` - External user ID from SSO (if set)\n- `email` - Contact email address\n- `name` - Contact display name\n- `profilePicture` - Profile picture URL\n- `type` - Contact type (\"customer\" or \"lead\")\n- `companies` - Array of companies the contact belongs to\n- `customFields` - Custom field values\n- `postsCreated` - Number of posts created\n- `commentsCreated` - Number of comments created\n- `lastActivity` - Last activity timestamp\n\n### Example\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"contact\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n ...\n }\n ],\n \"nextCursor\": \"eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "customer", "lead", "all" ], "default": "customer", "description": "Filter contacts by type. Defaults to \"customer\".", "example": "customer" }, "required": false, "name": "contactType", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "upsertContact", "summary": "Create or update a contact", "description": "Creates a new contact or updates an existing one.\n\nIf a contact with the given `email` or `userId` already exists, it will be updated.\nOtherwise, a new contact will be created.\n\n**At least one of `email` or `userId` must be provided for identification.**\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `email` | string | One of email/userId | Contact email address |\n| `userId` | string | One of email/userId | External user ID from your system |\n| `name` | string | No | Contact display name |\n| `profilePicture` | string | No | Profile picture URL |\n| `companies` | array | No | Companies the contact belongs to |\n| `customFields` | object | No | Custom field values |\n| `subscribedToChangelog` | boolean | No | Whether subscribed to changelog |\n| `locale` | string | No | Contact locale/language |\n| `phone` | string | No | Contact phone number |\n| `roles` | array | No | Role IDs to assign |\n| `userHash` | string | No | HMAC hash for identity verification |\n| `createdAt` | string | No | When the contact was created (ISO 8601) |\n\n### Company Object\n\nEach company in the `companies` array can have:\n- `id` (required) - External company ID from your system\n- `name` (required) - Company name\n- `monthlySpend` - Monthly spend/revenue\n- `customFields` - Custom field values\n- `industry` - Industry\n- `website` - Company website URL\n- `plan` - Current plan/subscription\n- `companySize` - Number of employees\n- `createdAt` - When the company was created\n\n### Response\n\nReturns the created or updated contact object.\n\n- **201 Created** - A new contact was created\n- **200 OK** - An existing contact was updated\n\n### Example Request\n\n```json\n{\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"userId\": \"usr_12345\",\n \"companies\": [\n {\n \"id\": \"company_123\",\n \"name\": \"Acme Inc\",\n \"monthlySpend\": 500,\n \"plan\": \"enterprise\"\n }\n ],\n \"customFields\": {\n \"plan\": \"pro\",\n \"signupSource\": \"website\"\n },\n \"subscribedToChangelog\": true\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"contact\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"userId\": \"usr_12345\",\n \"type\": \"customer\",\n \"companies\": [...],\n \"customFields\": {...},\n ...\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertContactBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `missing_parameter`: Either email or userId must be provided\n- `invalid_request`: Invalid contact identification parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "missing_parameter", "invalid_request" ], "description": "Machine-readable error code", "example": "missing_parameter" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/contacts/{id}": { "get": { "operationId": "getContactById", "summary": "Get contact by ID", "description": "Retrieves a single contact by their Featurebase ID.\n\nReturns both customers and leads.\n\n### Path Parameters\n\n- `id` - The Featurebase contact ID (24-character ObjectId)\n\n### Response Format\n\nReturns a single contact object with:\n- `object` - Always \"contact\"\n- `id` - Unique contact identifier\n- `userId` - External user ID from SSO (if set)\n- `email` - Contact email address\n- `name` - Contact display name\n- `profilePicture` - Profile picture URL\n- `type` - Contact type (\"customer\" or \"lead\")\n- `companies` - Array of companies the contact belongs to\n- `customFields` - Custom field values\n- `postsCreated` - Number of posts created\n- `commentsCreated` - Number of comments created\n- `lastActivity` - Last activity timestamp\n\n### Example\n\n```json\n{\n \"object\": \"contact\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n ...\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Featurebase contact ID", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The contact ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteContactById", "summary": "Delete contact by ID", "description": "Permanently deletes a contact by their Featurebase ID.\n\nSupports deleting both customers and leads.\n\n### Path Parameters\n\n- `id` - The Featurebase contact ID (24-character ObjectId)\n\n### Deletion Behavior\n\nWhen a contact is deleted:\n- The contact record is permanently removed\n- Associated data cleanup is triggered asynchronously\n- Comments and posts created by the contact are handled according to retention policies\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The ID of the deleted contact\n- `object` - Always \"contact\"\n- `deleted` - Always `true`\n\n### Example Response\n\n```json\n{\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"object\": \"contact\",\n \"deleted\": true\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Featurebase contact ID", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedContact" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The contact ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/contacts/by-user-id/{userId}": { "get": { "operationId": "getContactByUserId", "summary": "Get contact by external user ID", "description": "Retrieves a single contact by their external user ID (from your system via SSO).\n\n**Important:** This endpoint only returns customers (type: \"customer\"). Leads are not returned.\n\n### Path Parameters\n\n- `userId` - The external user ID from your system (matched via SSO integration)\n\n### Response Format\n\nReturns a single contact object with:\n- `object` - Always \"contact\"\n- `id` - Unique contact identifier\n- `userId` - External user ID from SSO\n- `email` - Contact email address\n- `name` - Contact display name\n- `profilePicture` - Profile picture URL\n- `type` - Always \"customer\" for this endpoint\n- `companies` - Array of companies the contact belongs to\n- `customFields` - Custom field values\n- `postsCreated` - Number of posts created\n- `commentsCreated` - Number of comments created\n- `lastActivity` - Last activity timestamp\n\n### Example\n\n```json\n{\n \"object\": \"contact\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"userId\": \"usr_12345\",\n \"email\": \"john@example.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n ...\n}\n```\n\n### Use Case\n\nThis endpoint is useful when you need to look up a contact using your own system's user identifier, \nsuch as when displaying Featurebase data alongside your user's information in your own application.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "maxLength": 255, "description": "External user ID from your system", "example": "usr_12345" }, "required": true, "name": "userId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this user ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteContactByUserId", "summary": "Delete contact by external user ID", "description": "Permanently deletes a contact by their external user ID.\n\n**Important:** This endpoint only deletes customers (type: \"customer\"). Leads cannot be deleted using this endpoint.\n\n### Path Parameters\n\n- `userId` - The external user ID from your system\n\n### Deletion Behavior\n\nWhen a contact is deleted:\n- The contact record is permanently removed\n- Associated data cleanup is triggered asynchronously\n- Comments and posts created by the contact are handled according to retention policies\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The ID of the deleted contact\n- `object` - Always \"contact\"\n- `deleted` - Always `true`\n\n### Example Response\n\n```json\n{\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"object\": \"contact\",\n \"deleted\": true\n}\n```\n\n### Use Case\n\nUse this endpoint when you need to delete a contact using your own system's user identifier,\nsuch as when a user deletes their account in your application.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "maxLength": 255, "description": "External user ID from your system", "example": "usr_12345" }, "required": true, "name": "userId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedContact" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Contact is not a customer", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this user ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/contacts/{id}/block": { "post": { "operationId": "blockContactById", "summary": "Block a contact", "description": "Blocks a contact by their Featurebase ID from the messenger/inbox.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)\n\n### Supported Contact Types\n\nThis endpoint blocks both:\n- **Customers** - Users with registered accounts\n- **Leads** - Anonymous or unregistered visitors\n\n### Blocking Behavior\n\nWhen a contact is blocked:\n- The contact cannot send new messages via messenger\n- Existing conversations are not deleted but no new messages can be added by the blocked user\n- The block can be removed by unblocking the contact\n\n### Response\n\nReturns a block confirmation object:\n- `id` - The ID of the blocked contact\n- `object` - Always \"contact\"\n- `blocked` - Always `true`\n\n### Example Response\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"contact\",\n \"blocked\": true\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Featurebase contact ID", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlockedContact" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The contact ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/contacts/{id}/unblock": { "post": { "operationId": "unblockContactById", "summary": "Unblock a contact", "description": "Unblocks a contact by their Featurebase ID from the messenger/inbox.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the contact (MongoDB ObjectId)\n\n### Supported Contact Types\n\nThis endpoint unblocks both:\n- **Customers** - Users with registered accounts\n- **Leads** - Anonymous or unregistered visitors\n\n### Unblocking Behavior\n\nWhen a contact is unblocked:\n- The contact can resume sending messages via messenger\n- Previously blocked conversations remain intact\n- The contact regains full messenger functionality\n\n### Response\n\nReturns an unblock confirmation object:\n- `id` - The ID of the unblocked contact\n- `object` - Always \"contact\"\n- `unblocked` - Always `true`\n\n### Example Response\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"contact\",\n \"unblocked\": true\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Contacts" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Featurebase contact ID", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnblockedContact" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The contact ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/teams": { "get": { "operationId": "listTeams", "summary": "List all teams", "description": "Returns all teams in your organization.\n\n### Response Structure\n\nThe response includes:\n- `object` - Always \"list\"\n- `data` - Array of team objects\n\n### Team Object\n\nEach team includes:\n- `id` - Unique team identifier\n- `name` - Team display name\n- `color` - Team color in hex format\n- `icon` - Team icon (emoji, predefined, or external URL)\n- `members` - Array of admin IDs who are members of this team\n\n### Example Response\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"team\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Support Team\",\n \"color\": \"#3B82F6\",\n \"icon\": {\n \"value\": \"👥\",\n \"type\": \"emoji\"\n },\n \"members\": [\"5fef50c5e9458a0012f82456\", \"5fef50c5e9458a0012f82457\"]\n }\n ]\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Teams" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamList" } } } }, "400": { "description": "Bad Request - Validation error or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "404": { "description": "Not Found - Resource does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerError" } } } } } } }, "/v2/teams/{id}": { "get": { "operationId": "getTeamById", "summary": "Get team by ID", "description": "Retrieves a single team by its Featurebase ID.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the team (MongoDB ObjectId)\n\n### Response\n\nReturns a team object with:\n- `id` - Unique team identifier\n- `name` - Team display name\n- `color` - Team color in hex format\n- `icon` - Team icon (emoji, predefined, or external URL)\n- `members` - Array of admin IDs who are members of this team\n\n### Example Response\n\n```json\n{\n \"object\": \"team\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Support Team\",\n \"color\": \"#3B82F6\",\n \"icon\": {\n \"value\": \"👥\",\n \"type\": \"emoji\"\n },\n \"members\": [\"5fef50c5e9458a0012f82456\", \"5fef50c5e9458a0012f82457\"]\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Team with the specified ID does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Teams" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the team (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The team ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `team_not_found`: No team exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "team_not_found" ], "description": "Machine-readable error code", "example": "team_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/companies": { "get": { "operationId": "listCompanies", "summary": "List all companies", "description": "Returns all companies in your organization with cursor-based pagination.\n\n### Query Parameters\n\n- `limit` - Number of companies to return (1-100, default: 10)\n- `cursor` - Opaque cursor from a previous response for pagination\n\n### Response Structure\n\nThe response includes:\n- `object` - Always \"list\"\n- `data` - Array of company objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Company Object\n\nEach company includes:\n- `id` - Featurebase internal ID (MongoDB ObjectId)\n- `companyId` - External company ID from your system\n- `name` - Company name\n- `monthlySpend` - Monthly spend/revenue\n- `industry` - Industry\n- `website` - Company website URL\n- `plan` - Plan/tier name\n- `linkedUsers` - Number of users linked to this company\n- `companySize` - Employee headcount\n- `lastActivity` - Last activity timestamp\n- `customFields` - Custom field values\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Example Response\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"company\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"companyId\": \"comp_12345\",\n \"name\": \"Acme Inc\",\n \"monthlySpend\": 5000,\n \"industry\": \"Technology\",\n \"website\": \"https://acme.com\",\n \"plan\": \"enterprise\",\n \"linkedUsers\": 15,\n \"companySize\": 250,\n \"lastActivity\": \"2025-01-15T00:00:00.000Z\",\n \"customFields\": { \"location\": \"Europe\" },\n \"createdAt\": \"2025-01-01T12:00:00.000Z\",\n \"updatedAt\": \"2025-01-10T15:30:00.000Z\"\n }\n ],\n \"nextCursor\": \"eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of companies to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "upsertCompany", "summary": "Create or update a company", "description": "Creates a new company or updates an existing one.\n\nUses the external `companyId` as the unique identifier for upsert matching.\nIf a company with the given `companyId` already exists, it will be updated.\nOtherwise, a new company will be created.\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `companyId` | string | Yes | External company ID from your system (unique identifier) |\n| `name` | string | Yes | Company name |\n| `monthlySpend` | number | No | Monthly spend/revenue from this company |\n| `industry` | string | No | Industry the company operates in |\n| `website` | string | No | Company website URL |\n| `plan` | string | No | Current plan/subscription name |\n| `companySize` | number | No | Number of employees |\n| `createdAt` | string | No | When the company was created (ISO 8601) |\n| `customFields` | object | No | Custom field values |\n\n### Example Request\n\n```json\n{\n \"companyId\": \"comp_12345\",\n \"name\": \"Acme Inc\",\n \"monthlySpend\": 5000,\n \"industry\": \"Technology\",\n \"website\": \"https://acme.com\",\n \"plan\": \"enterprise\",\n \"companySize\": 250,\n \"customFields\": {\n \"region\": \"EMEA\",\n \"tier\": \"gold\"\n }\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"company\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"companyId\": \"comp_12345\",\n \"name\": \"Acme Inc\",\n \"monthlySpend\": 5000,\n \"industry\": \"Technology\",\n \"website\": \"https://acme.com\",\n \"plan\": \"enterprise\",\n \"linkedUsers\": 1,\n \"companySize\": 250,\n \"lastActivity\": \"2025-01-15T00:00:00.000Z\",\n \"customFields\": { \"region\": \"EMEA\", \"tier\": \"gold\" },\n \"createdAt\": \"2025-01-01T12:00:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n}\n```\n\n### Error Responses\n\n- **400 Bad Request** - Invalid company data\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCompanyBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid company data", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/companies/{id}": { "get": { "operationId": "getCompanyById", "summary": "Get company by ID", "description": "Retrieves a single company by its Featurebase ID.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the company (MongoDB ObjectId)\n\n### Response\n\nReturns a company object with:\n- `id` - Featurebase internal ID\n- `companyId` - External company ID from your system\n- `name` - Company name\n- `monthlySpend` - Monthly spend/revenue\n- `industry` - Industry\n- `website` - Company website URL\n- `plan` - Plan/tier name\n- `linkedUsers` - Number of users linked to this company\n- `companySize` - Employee headcount\n- `lastActivity` - Last activity timestamp\n- `customFields` - Custom field values\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Example Response\n\n```json\n{\n \"object\": \"company\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"companyId\": \"comp_12345\",\n \"name\": \"Acme Inc\",\n \"monthlySpend\": 5000,\n \"industry\": \"Technology\",\n \"website\": \"https://acme.com\",\n \"plan\": \"enterprise\",\n \"linkedUsers\": 15,\n \"companySize\": 250,\n \"lastActivity\": \"2025-01-15T00:00:00.000Z\",\n \"customFields\": { \"location\": \"Europe\" },\n \"createdAt\": \"2025-01-01T12:00:00.000Z\",\n \"updatedAt\": \"2025-01-10T15:30:00.000Z\"\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Company with the specified ID does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the company (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The company ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteCompanyById", "summary": "Delete a company", "description": "Deletes a company by its Featurebase ID.\n\nThis will also remove the company from all linked users' associations.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the company (MongoDB ObjectId)\n\n### Response\n\nReturns a deletion confirmation object:\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"company\",\n \"deleted\": true\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Company with the specified ID does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the company (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedCompany" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The company ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/companies/by-company-id/{companyId}": { "delete": { "operationId": "deleteCompanyByCompanyId", "summary": "Delete a company by external company ID", "description": "Permanently deletes a company by its external company ID (the `companyId` from your system).\n\nThis will also remove the company from all linked users' associations.\n\n### Path Parameters\n\n- `companyId` - The external company ID from your system\n\n### Deletion Behavior\n\nWhen a company is deleted:\n- The company record is permanently removed\n- The company is removed from all linked users' `companyIds` and `companies` arrays\n\n### Response\n\nReturns a deletion confirmation object:\n- `id` - The Featurebase internal ID of the deleted company\n- `object` - Always \"company\"\n- `deleted` - Always `true`\n\n### Example Response\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"company\",\n \"deleted\": true\n}\n```\n\n### Use Case\n\nUse this endpoint when you need to delete a company using your own system's company identifier,\nsuch as when a company is removed from your application.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255, "description": "The external company ID from your system", "example": "comp_12345" }, "required": true, "name": "companyId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedCompany" } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this external company ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/companies/{id}/contacts": { "get": { "operationId": "listCompanyContacts", "summary": "List contacts attached to a company", "description": "Returns all contacts (customers) attached to a specific company.\n\nOnly returns contacts with type \"customer\" that have the company in their `companyIds` array.\nUses cursor-based pagination.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the company (MongoDB ObjectId)\n\n### Query Parameters\n\n- `limit` - Number of contacts to return (1-100, default: 10)\n- `cursor` - Opaque cursor from a previous response for pagination\n\n### Response Structure\n\nThe response includes:\n- `object` - Always \"list\"\n- `data` - Array of contact objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Example Response\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"contact\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"userId\": \"usr_12345\",\n \"email\": \"john@acme.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n \"companies\": [...],\n \"createdAt\": \"2025-01-01T12:00:00.000Z\"\n }\n ],\n \"nextCursor\": \"eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9\"\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Company with the specified ID does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the company (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of contacts to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The company ID format is invalid\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "attachContactToCompany", "summary": "Attach a contact to a company", "description": "Attaches a contact (customer) to a company.\n\nAdds the company to the contact's `companyIds` array and embedded `companies` array.\nThis operation is **additive** - existing company associations are preserved.\nAlso increments the `linkedUsers` count on the company.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the company (MongoDB ObjectId)\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `contactId` | string | Yes | The Featurebase internal ID of the contact to attach (MongoDB ObjectId) |\n\n### Example Request\n\n```json\n{\n \"contactId\": \"507f1f77bcf86cd799439012\"\n}\n```\n\n### Response\n\nReturns the updated contact object with the new company association.\n\n### Example Response\n\n```json\n{\n \"object\": \"contact\",\n \"id\": \"507f1f77bcf86cd799439012\",\n \"userId\": \"usr_12345\",\n \"email\": \"john@acme.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n \"companies\": [\n {\n \"object\": \"company\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"companyId\": \"comp_12345\",\n \"name\": \"Acme Inc\"\n }\n ]\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Company or contact does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the company (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachContactToCompanyBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The company or contact ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this ID\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found", "contact_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/companies/{id}/contacts/{contactId}": { "delete": { "operationId": "removeContactFromCompany", "summary": "Remove a contact from a company", "description": "Removes a contact (customer) from a company.\n\nRemoves the company from the contact's `companyIds` array and embedded `companies` array.\nAlso decrements the `linkedUsers` count on the company.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the company (MongoDB ObjectId)\n- `contactId` - The Featurebase internal ID of the contact to remove (MongoDB ObjectId)\n\n### Response\n\nReturns the updated contact object with the company removed.\n\n### Example Response\n\n```json\n{\n \"object\": \"contact\",\n \"id\": \"507f1f77bcf86cd799439012\",\n \"userId\": \"usr_12345\",\n \"email\": \"john@acme.com\",\n \"name\": \"John Doe\",\n \"type\": \"customer\",\n \"companies\": []\n}\n```\n\n### Error Responses\n\n- **400 Bad Request** - Contact is not attached to this company\n- **404 Not Found** - Company or contact does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Companies" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the company (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the contact to remove (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439012" }, "required": true, "name": "contactId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object" } ] } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The company or contact ID format is invalid\n- `contact_not_attached`: Contact is not attached to this company", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id", "contact_not_attached" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `company_not_found`: No company exists with this ID\n- `contact_not_found`: No contact exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "company_not_found", "contact_not_found" ], "description": "Machine-readable error code", "example": "company_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/brands": { "get": { "operationId": "listBrands", "summary": "List all brands", "description": "Returns all brands in your organization with cursor-based pagination.\n\n### Query Parameters\n\n- `limit` - Number of brands to return (1-100, default: 10)\n- `cursor` - Opaque cursor from a previous response for pagination\n\n### Response Structure\n\nThe response includes:\n- `object` - Always \"list\"\n- `data` - Array of brand objects\n- `nextCursor` - Cursor for the next page (null if no more results)\n\n### Brand Object\n\nEach brand includes:\n- `id` - Featurebase internal ID (MongoDB ObjectId)\n- `name` - Brand display name\n- `isDefault` - Whether this is the default brand\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n- `helpCenterId` - Associated help center ID\n- `senderEmailAddressId` - Default sender email address ID\n\n### Example Response\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"brand\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Default Brand\",\n \"isDefault\": true,\n \"createdAt\": \"2025-01-01T12:00:00.000Z\",\n \"updatedAt\": \"2025-01-10T15:30:00.000Z\",\n \"helpCenterId\": \"11\",\n \"senderEmailAddressId\": \"507f1f77bcf86cd799439012\"\n }\n ],\n \"nextCursor\": null\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Brands" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of brands to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/brands/{id}": { "get": { "operationId": "getBrandById", "summary": "Get brand by ID", "description": "Retrieves a single brand by its Featurebase ID.\n\n### Path Parameters\n\n- `id` - The Featurebase internal ID of the brand (MongoDB ObjectId)\n\n### Response\n\nReturns a brand object with:\n- `id` - Featurebase internal ID\n- `name` - Brand display name\n- `isDefault` - Whether this is the default brand\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n- `helpCenterId` - Associated help center ID\n- `senderEmailAddressId` - Default sender email address ID\n\n### Example Response\n\n```json\n{\n \"object\": \"brand\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Default Brand\",\n \"isDefault\": true,\n \"createdAt\": \"2025-01-01T12:00:00.000Z\",\n \"updatedAt\": \"2025-01-10T15:30:00.000Z\",\n \"helpCenterId\": \"11\",\n \"senderEmailAddressId\": \"507f1f77bcf86cd799439012\"\n}\n```\n\n### Error Responses\n\n- **404 Not Found** - Brand with the specified ID does not exist\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Brands" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "The Featurebase internal ID of the brand (MongoDB ObjectId)", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Brand" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The brand ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `brand_not_found`: No brand exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "brand_not_found" ], "description": "Machine-readable error code", "example": "brand_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/conversations": { "get": { "operationId": "listConversations", "summary": "List conversations", "description": "Returns a list of conversations in your organization using cursor-based pagination.\n\n### Query Parameters\n\n- `limit` - Number of conversations to return (1-100, default 10)\n- `cursor` - Cursor from previous response for pagination\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of conversation objects\n- `nextCursor` - Cursor for the next page, or null if no more results\n\n### Conversation Object\n\nEach conversation includes:\n- `id` - Unique conversation identifier (short ID)\n- `title` - Conversation title\n- `state` - Current state (\"open\", \"closed\", or \"snoozed\")\n- `priority` - Whether the conversation is marked as priority\n- `adminAssigneeId` - ID of assigned admin (if any)\n- `teamAssigneeId` - ID of assigned team (if any)\n- `participants` - Array of participants\n- `source` - Information about the first message\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Example\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"title\": \"Question about pricing\",\n \"state\": \"open\",\n \"priority\": false,\n \"adminAssigneeId\": null,\n \"participants\": [\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f88\" }\n ],\n ...\n }\n ],\n \"nextCursor\": \"eyJpZCI6IjEyMzQ1In0=\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjEyMzQ1In0=" }, "required": false, "name": "cursor", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createConversation", "summary": "Create a conversation", "description": "Creates a new conversation. Supports both contact-initiated (customer/lead) and admin-initiated (outreach) conversations.\n\n## Contact-Initiated Conversation\n\nFor conversations started by a customer or lead:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `from.type` | string | Yes | Must be \"contact\" |\n| `from.id` | string | Yes | The Featurebase contact ID (24-character ObjectId) |\n| `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |\n| `channel` | string | No | The channel: \"desktop\" (default) or \"email\" |\n| `createdAt` | string | No | ISO timestamp for migrations |\n\n### Example Contact-Initiated Request\n\n```json\n{\n \"from\": {\n \"type\": \"contact\",\n \"id\": \"676f0f6765bdaa7d7d760f88\"\n },\n \"bodyMarkdown\": \"Hello, I have a question about your product.\",\n \"channel\": \"desktop\"\n}\n```\n\n## Admin-Initiated Outreach\n\nFor outreach conversations started by an admin:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `from.type` | string | Yes | Must be \"admin\" |\n| `from.id` | string | Yes | The Featurebase admin ID (24-character ObjectId) |\n| `bodyMarkdown` | string | Yes | The initial message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |\n| `channel` | string | No | The channel: \"desktop\" (default) or \"email\" |\n| `recipients` | object | Yes | Recipients for the outreach |\n| `recipients.to` | object | Yes | Primary recipients |\n| `recipients.to.emails` | string[] | No* | Email addresses |\n| `recipients.to.ids` | string[] | No* | Featurebase contact IDs |\n| `recipients.cc` | object | No | CC recipients (same structure as \"to\") |\n| `recipients.bcc` | object | No | BCC recipients (same structure as \"to\") |\n| `subject` | string | No** | Email subject line |\n| `createdAt` | string | No | ISO timestamp for migrations |\n\n*At least one email or ID is required in `recipients.to`\n**Required when channel is \"email\"\n\n### Example Admin Outreach (In-App)\n\n```json\n{\n \"from\": {\n \"type\": \"admin\",\n \"id\": \"507f1f77bcf86cd799439011\"\n },\n \"bodyMarkdown\": \"Hi! Just following up on your inquiry.\",\n \"channel\": \"desktop\",\n \"recipients\": {\n \"to\": {\n \"ids\": [\"676f0f6765bdaa7d7d760f88\"]\n }\n }\n}\n```\n\n### Example Admin Outreach (Email)\n\n```json\n{\n \"from\": {\n \"type\": \"admin\",\n \"id\": \"507f1f77bcf86cd799439011\"\n },\n \"bodyMarkdown\": \"Hi! Just following up on your inquiry.\",\n \"channel\": \"email\",\n \"subject\": \"Following up on your inquiry\",\n \"recipients\": {\n \"to\": {\n \"emails\": [\"john@example.com\"]\n },\n \"cc\": {\n \"emails\": [\"manager@example.com\"]\n }\n }\n}\n```\n\n### Response\n\nReturns the created conversation object with a **201 Created** status.\n\n### Example Response\n\n```json\n{\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"state\": \"open\",\n \"priority\": false,\n \"adminAssigneeId\": null,\n \"participants\": [\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f88\" }\n ],\n \"source\": {\n \"channel\": \"desktop\",\n \"deliveredAs\": \"customer_initiated\",\n \"bodyHtml\": \"

Hello, I have a question about your product.

\",\n \"bodyMarkdown\": \"Hello, I have a question about your product.\",\n \"author\": { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f88\" }\n },\n \"createdAt\": \"2025-01-15T10:30:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConversationBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_content`: Invalid message content format\n- `missing_parameter`: Required field is missing\n- `invalid_parameter`: Invalid channel parameter\n- `business_validation_error`: At least one recipient is required for admin outreach", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_content", "missing_parameter", "invalid_parameter", "business_validation_error" ], "description": "Machine-readable error code", "example": "invalid_content" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `forbidden`: Admin is not a member of this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "forbidden" ], "description": "Machine-readable error code", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `contact_not_found`: The contact initiating the conversation was not found\n- `admin_not_found`: The admin initiating the outreach was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "contact_not_found", "admin_not_found" ], "description": "Machine-readable error code", "example": "contact_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/conversations/{id}": { "get": { "operationId": "getConversationById", "summary": "Get conversation by ID", "description": "Retrieves a single conversation by its ID, including conversation parts (messages).\n\n### Path Parameters\n\n- `id` - The conversation ID (short ID)\n\n### Hard Limit of 500 Parts\n\nThe maximum number of conversation parts that can be returned via the API is **500**.\nIf a conversation has more than 500 parts, only the **500 most recent** conversation parts will be returned.\n\n### Response Format\n\nReturns a single conversation object with:\n- `object` - Always \"conversation\"\n- `id` - Unique conversation identifier (short ID)\n- `title` - Conversation title\n- `state` - Current state (\"open\", \"closed\", or \"snoozed\")\n- `priority` - Whether the conversation is marked as priority\n- `adminAssigneeId` - ID of assigned admin (if any)\n- `teamAssigneeId` - ID of assigned team (if any)\n- `participants` - Array of participants\n- `source` - Information about the first message\n- `conversationParts` - Array of conversation parts (messages, max 500)\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Conversation Parts\n\nEach conversation part includes:\n- `object` - Always \"conversation_part\"\n- `id` - Unique part identifier\n- `partType` - Type of part (e.g., \"user_msg\", \"admin_msg\", \"bot_msg\")\n- `body` - Message body (HTML content)\n- `author` - Author information with name, email, and profile picture\n- `channel` - Channel through which the message was sent\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Example\n\n```json\n{\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"title\": \"Question about pricing\",\n \"state\": \"open\",\n \"priority\": false,\n \"adminAssigneeId\": \"507f1f77bcf86cd799439011\",\n \"participants\": [\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f88\" }\n ],\n \"conversationParts\": [\n {\n \"object\": \"conversation_part\",\n \"id\": \"1\",\n \"partType\": \"user_msg\",\n \"bodyHtml\": \"

Hello, I have a question about your pricing plans.

\",\n \"bodyMarkdown\": \"Hello, I have a question about your pricing plans.\",\n \"author\": {\n \"type\": \"customer\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\"\n },\n \"channel\": \"desktop\",\n \"createdAt\": \"2025-01-15T10:30:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n },\n {\n \"object\": \"conversation_part\",\n \"id\": \"2\",\n \"partType\": \"admin_msg\",\n \"bodyHtml\": \"

Hi John! I'd be happy to help you with pricing information.

\",\n \"bodyMarkdown\": \"Hi John! I'd be happy to help you with pricing information.\",\n \"author\": {\n \"type\": \"admin\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Support Agent\"\n },\n \"channel\": \"desktop\",\n \"createdAt\": \"2025-01-15T10:35:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:35:00.000Z\"\n }\n ],\n \"createdAt\": \"2025-01-15T10:30:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:35:00.000Z\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteConversation", "summary": "Delete a conversation", "description": "Permanently deletes a conversation by its short ID.\n\n### Path Parameters\n\n- `id` - The conversation short ID (numeric)\n\n### Response\n\nReturns a deletion confirmation object:\n\n```json\n{\n \"id\": \"12345\",\n \"object\": \"conversation\",\n \"deleted\": true\n}\n```\n\n### Caution\n\nThis operation is **irreversible**. The conversation and all its messages will be permanently deleted.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedConversation" } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateConversation", "summary": "Update a conversation", "description": "Updates a conversation's properties. Supports partial updates - only provided fields will be updated.\n\n### Path Parameters\n\n- `id` - The conversation ID (short ID)\n\n### Request Body\n\nAll fields are optional. Only provided fields will be updated.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `actingAdminId` | string | Admin ID performing the action (for attribution). If not provided, uses bot service user. Must be a member of the organization. |\n| `state` | string | Conversation state: \"open\", \"closed\", or \"snoozed\" |\n| `snoozedUntil` | string | ISO datetime when to unsnooze (required when state is \"snoozed\") |\n| `adminAssigneeId` | string/null | Admin ID to assign, or null to unassign |\n| `teamAssigneeId` | string/null | Team ID to assign, or null to unassign |\n| `title` | string | Conversation title |\n| `customAttributes` | object | Custom attributes to set on the conversation |\n| `markAsRead` | object | Mark conversation as read for specific users |\n\n### markAsRead Object\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `allAdmins` | boolean | If true, marks all admins with existing readReceipts as read |\n| `adminIds` | string[] | Array of specific admin IDs to mark as read |\n| `allContacts` | boolean | If true, marks all contacts with existing readReceipts as read |\n| `contactIds` | string[] | Array of specific contact IDs to mark as read |\n\nNote: Only users with existing read receipts will be updated. Use `allAdmins`/`allContacts` OR `adminIds`/`contactIds` - the \"all\" flags take precedence.\n\n### Response\n\nReturns the updated conversation object.\n\n### Example: Close a Conversation (with attribution)\n\n```json\n{\n \"actingAdminId\": \"507f1f77bcf86cd799439011\",\n \"state\": \"closed\"\n}\n```\n\n### Example: Close a Conversation (bot user)\n\n```json\n{\n \"state\": \"closed\"\n}\n```\n\n### Example: Snooze a Conversation\n\n```json\n{\n \"state\": \"snoozed\",\n \"snoozedUntil\": \"2025-01-20T10:00:00.000Z\"\n}\n```\n\n### Example: Assign to an Admin\n\n```json\n{\n \"adminAssigneeId\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n### Example: Update Title and Custom Attributes\n\n```json\n{\n \"title\": \"Billing Issue - Priority\",\n \"customAttributes\": {\n \"priority_level\": \"high\",\n \"category\": \"billing\"\n }\n}\n```\n\n### Example: Mark as Read (All Admins)\n\n```json\n{\n \"markAsRead\": {\n \"allAdmins\": true\n }\n}\n```\n\n### Example: Mark as Read (All Contacts)\n\n```json\n{\n \"markAsRead\": {\n \"allContacts\": true\n }\n}\n```\n\n### Example: Mark as Read (Specific IDs)\n\n```json\n{\n \"markAsRead\": {\n \"adminIds\": [\"507f1f77bcf86cd799439011\"],\n \"contactIds\": [\"676f0f6765bdaa7d7d760f88\"]\n }\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConversationBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Invalid update parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `forbidden`: Acting admin is not a member of this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "forbidden" ], "description": "Machine-readable error code", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID\n- `admin_not_found`: The acting admin was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found", "admin_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/conversations/{id}/reply": { "post": { "operationId": "replyToConversation", "summary": "Reply to a conversation", "description": "Adds a reply to an existing conversation. Supports both contact (customer/lead) and admin replies.\n\n### Path Parameters\n\n- `id` - The conversation ID (short ID)\n\n### Request Body\n\nThe request body varies based on who is sending the reply:\n\n#### Contact Reply (customer/lead)\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | string | Yes | Must be \"contact\" |\n| `userId` | string | No* | External user ID from your system |\n| `id` | string | No* | Featurebase contact ID (24-character ObjectId) |\n| `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |\n| `messageType` | string | Yes | Must be \"reply\" |\n\n*At least one of `userId` or `id` is required.\n\n#### Admin Reply\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | string | Yes | Must be \"admin\" |\n| `id` | string | Yes | Featurebase admin ID (24-character ObjectId) |\n| `bodyMarkdown` | string | Yes | The message content in markdown format. Images referenced by URL or as base64 data URIs will be automatically uploaded and stored. |\n| `messageType` | string | Yes | \"reply\" for customer-visible reply, \"note\" for internal note |\n\n### Response\n\nReturns the created conversation part object with a **201 Created** status. The response includes both `bodyHtml` (with signed image URLs) and `bodyMarkdown` fields.\n\n### Example Contact Reply\n\n```json\n{\n \"type\": \"contact\",\n \"userId\": \"user_123\",\n \"bodyMarkdown\": \"Thank you for your help!\",\n \"messageType\": \"reply\"\n}\n```\n\n### Example Admin Reply\n\n```json\n{\n \"type\": \"admin\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"bodyMarkdown\": \"I'm happy to help! Here's what you need to do...\",\n \"messageType\": \"reply\"\n}\n```\n\n### Example Admin Note (Internal)\n\n```json\n{\n \"type\": \"admin\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"bodyMarkdown\": \"Customer seems frustrated, escalating to tier 2.\",\n \"messageType\": \"note\"\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"conversation_part\",\n \"id\": \"3\",\n \"partType\": \"user_msg\",\n \"bodyHtml\": \"

Thank you for your help!

\",\n \"bodyMarkdown\": \"Thank you for your help!\",\n \"author\": {\n \"type\": \"customer\",\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"name\": \"John Doe\",\n \"email\": \"john@example.com\"\n },\n \"channel\": \"desktop\",\n \"createdAt\": \"2025-01-15T10:40:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:40:00.000Z\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplyToConversationBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationPart" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_content`: Invalid message content format\n- `missing_parameter`: Required field is missing (userId or id)\n- `invalid_parameter`: Invalid channel parameter\n- `invalid_request`: Invalid reply type", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_content", "missing_parameter", "invalid_parameter", "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_content" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID\n- `contact_not_found`: The contact sending the reply was not found\n- `admin_not_found`: The admin sending the reply was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found", "contact_not_found", "admin_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/conversations/{id}/participants": { "post": { "operationId": "addParticipantToConversation", "summary": "Add a contact to a conversation", "description": "Adds a contact (customer or lead) as a participant to an existing conversation.\n\n### Path Parameters\n\n- `id` - The conversation ID (short ID)\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `participant` | object | Yes | The contact to add (see below) |\n| `participant.id` | string | No* | The Featurebase ID (24-character ObjectId) - matches customer or lead |\n| `participant.userId` | string | No* | External user ID from your system - matches customer only |\n| `participant.email` | string | No* | Email address - matches customer only |\n| `actingAdminId` | string | No | Admin ID performing the action (for attribution) |\n\n*At least one of `id`, `userId`, or `email` is required in the participant object.\n\n### Lookup Priority\n\n1. If `id` is provided, looks up by Featurebase ID (matches both customer and lead types)\n2. If `userId` is provided, looks up by external user ID (matches customer type only)\n3. If `email` is provided, looks up by email address (matches customer type only)\n\n### Response\n\nReturns the updated conversation object.\n\n### Example Request (by Featurebase ID)\n\n```json\n{\n \"participant\": {\n \"id\": \"676f0f6765bdaa7d7d760f88\"\n },\n \"actingAdminId\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n### Example Request (by external userId)\n\n```json\n{\n \"participant\": {\n \"userId\": \"user_123\"\n }\n}\n```\n\n### Example Request (by email)\n\n```json\n{\n \"participant\": {\n \"email\": \"john@example.com\"\n }\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"participants\": [\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f88\" },\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f89\" }\n ],\n ...\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddParticipantBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `forbidden`: Acting admin is not a member of this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "forbidden" ], "description": "Machine-readable error code", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID\n- `contact_not_found`: The contact to add was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found", "contact_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "removeParticipantFromConversation", "summary": "Remove a contact from a conversation", "description": "Removes a contact (customer or lead) from an existing conversation.\n\n**Note:** You cannot remove the last participant from a conversation.\n\n### Path Parameters\n\n- `id` - The conversation ID (short ID)\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `id` | string | Yes | The Featurebase ID of the contact to remove (24-character ObjectId) |\n| `actingAdminId` | string | No | Admin ID performing the action (for attribution) |\n\n### Response\n\nReturns the updated conversation object.\n\n### Example Request\n\n```json\n{\n \"id\": \"676f0f6765bdaa7d7d760f88\",\n \"actingAdminId\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"participants\": [\n { \"type\": \"customer\", \"id\": \"676f0f6765bdaa7d7d760f89\" }\n ],\n ...\n}\n```\n\n### Error Cases\n\n- **400 Bad Request** - Cannot remove the last participant from a conversation\n- **404 Not Found** - Conversation or contact not found in participants\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 16, "pattern": "^[a-zA-Z0-9]+$", "description": "Conversation ID (short ID)", "example": "12345" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RemoveParticipantBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Cannot remove the last participant from a conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `forbidden`: Acting admin is not a member of this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "forbidden" ], "description": "Machine-readable error code", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID\n- `participant_not_found`: The contact is not a participant in this conversation", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found", "participant_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/conversations/redact": { "post": { "operationId": "redactConversationPart", "summary": "Redact a conversation part", "description": "Redacts a conversation part (message) from a conversation. Redaction permanently removes the message content while preserving the conversation structure.\n\nOnly human message types can be redacted:\n- `user_msg` - Messages from customers/leads\n- `admin_msg` - Messages from admins\n- `email_msg` - Email messages\n- `bot_msg` - Bot messages\n\nSystem-generated conversation parts (assignments, status changes, etc.) cannot be redacted.\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `type` | string | Yes | The type of item to redact. Currently only `\"conversation_part\"` is supported. |\n| `conversationId` | string | Yes | The conversation short ID containing the part to redact |\n| `conversationPartId` | string | Yes | The conversation part short ID to redact |\n| `actingAdminId` | string | No | Admin ID performing the action (for attribution) |\n\n### Response\n\nReturns the updated conversation object.\n\n### Example Request\n\n```json\n{\n \"type\": \"conversation_part\",\n \"conversationId\": \"12345\",\n \"conversationPartId\": \"67890\",\n \"actingAdminId\": \"507f1f77bcf86cd799439011\"\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"conversation\",\n \"id\": \"12345\",\n \"conversationParts\": [\n {\n \"object\": \"conversation_part\",\n \"id\": \"67890\",\n \"partType\": \"user_msg\",\n \"bodyHtml\": \"\",\n \"bodyMarkdown\": \"\",\n \"redacted\": true,\n ...\n }\n ],\n ...\n}\n```\n\n### Error Cases\n\n- **400 Bad Request** - Only human messages can be redacted\n- **404 Not Found** - Conversation or conversation part not found\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Conversations" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedactConversationPartBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_request`: Only human messages can be redacted", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_request" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "403": { "description": "Forbidden\n\nPossible error codes:\n- `forbidden`: Acting admin is not a member of this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "authorization_error" ], "description": "The type of error returned", "example": "authorization_error" }, "code": { "type": "string", "enum": [ "forbidden" ], "description": "Machine-readable error code", "example": "forbidden" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 403 ], "description": "HTTP status code", "example": 403 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `conversation_not_found`: No conversation exists with this ID\n- `conversation_part_not_found`: The conversation part was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "conversation_not_found", "conversation_part_not_found" ], "description": "Machine-readable error code", "example": "conversation_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/webhooks": { "get": { "operationId": "listWebhooks", "summary": "List webhooks", "description": "Returns a list of webhooks in your organization using cursor-based pagination.\n\n### Query Parameters\n\n- `limit` - Number of webhooks to return (1-100, default 10)\n- `cursor` - Cursor from previous response for pagination\n- `status` - Filter by status: \"active\", \"paused\", or \"suspended\"\n\n### Response Format\n\nReturns a list object with:\n- `object` - Always \"list\"\n- `data` - Array of webhook objects\n- `nextCursor` - Cursor for the next page, or null if no more results\n\n### Webhook Object\n\nEach webhook includes:\n- `id` - Unique webhook identifier\n- `name` - Human-readable webhook name\n- `url` - Webhook endpoint URL\n- `topics` - Array of subscribed event topics\n- `status` - Current status (\"active\", \"paused\", \"suspended\")\n- `health` - Health metrics (response times, error counts)\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\n### Example\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"object\": \"webhook\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Production Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"topics\": [\"post.created\", \"post.updated\"],\n \"status\": \"active\",\n ...\n }\n ],\n \"nextCursor\": \"eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10, "description": "A limit on the number of objects to be returned, between 1 and 100.", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 512, "description": "An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.", "example": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9" }, "required": false, "name": "cursor", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "paused", "suspended" ], "description": "Filter webhooks by status", "example": "active" }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookList" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_cursor`: The pagination cursor is malformed or expired", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_cursor" ], "description": "Machine-readable error code", "example": "invalid_cursor" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "createWebhook", "summary": "Create a webhook", "description": "Creates a new webhook to receive event notifications.\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | Yes | Human-readable name (max 100 chars) |\n| `url` | string | Yes | Webhook endpoint URL (must be HTTPS) |\n| `description` | string | No | Optional description (max 500 chars) |\n| `topics` | string[] | Yes | Event topics to subscribe to |\n| `requestConfig` | object | No | Request configuration |\n| `requestConfig.headers` | object | No | Custom headers to send (max 10) |\n\n### Available Topics\n\n- `post.created` - When a new post is created\n- `post.updated` - When a post is updated\n- `post.deleted` - When a post is deleted\n- `post.voted` - When a post receives a vote\n- `changelog.published` - When a changelog is published\n- `comment.created` - When a comment is created\n- `comment.updated` - When a comment is updated\n- `comment.deleted` - When a comment is deleted\n\n### Response\n\nReturns the created webhook object including the signing secret.\n\n### Example Request\n\n```json\n{\n \"name\": \"Production Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"description\": \"Handles all production events\",\n \"topics\": [\"post.created\", \"post.updated\", \"comment.created\"],\n \"requestConfig\": {\n \"timeoutMs\": 10000,\n \"headers\": {\n \"X-Custom-Header\": \"value\"\n }\n }\n}\n```\n\n### Example Response\n\n```json\n{\n \"object\": \"webhook\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Production Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"secret\": \"whsec_abc123def456ghi789\",\n \"topics\": [\"post.created\", \"post.updated\", \"comment.created\"],\n \"status\": \"active\",\n ...\n}\n```\n\n### Limits\n\nEach organization has a maximum number of webhooks (default: 10). Creating a webhook when the limit is reached will return a 400 error.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookBody" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_parameter`: Invalid request parameters\n- `invalid_request`: Maximum number of webhooks reached for this organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter", "invalid_request" ], "description": "Machine-readable error code", "example": "invalid_parameter" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/webhooks/{id}": { "get": { "operationId": "getWebhookById", "summary": "Get webhook by ID", "description": "Retrieves a single webhook by its unique identifier.\n\n### Path Parameters\n\n- `id` - The webhook ID (24-character ObjectId)\n\n### Response Format\n\nReturns a webhook object with:\n- `object` - Always \"webhook\"\n- `id` - Unique webhook identifier\n- `name` - Human-readable webhook name\n- `url` - Webhook endpoint URL\n- `description` - Optional description\n- `topics` - Array of subscribed event topics\n- `status` - Current status (\"active\", \"paused\", \"suspended\")\n- `requestConfig` - Request configuration (timeout, headers)\n- `lastStatus` - Last delivery attempt status\n- `health` - Health metrics\n- `createdAt` - Creation timestamp\n- `updatedAt` - Last update timestamp\n\nThe response includes the webhook signing secret for payload verification.\n\n### Example\n\n```json\n{\n \"object\": \"webhook\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Production Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"description\": \"Handles all production events\",\n \"topics\": [\"post.created\", \"post.updated\"],\n \"status\": \"active\",\n \"requestConfig\": {\n \"timeoutMs\": 5000,\n \"headers\": {}\n },\n \"lastStatus\": {\n \"code\": 200,\n \"message\": \"Success\",\n \"timestamp\": \"2025-01-15T10:30:00.000Z\"\n },\n \"health\": {\n \"lastResponseTime\": 150,\n \"avgResponseTime\": 200,\n \"lastSuccessAt\": \"2025-01-15T10:30:00.000Z\",\n \"errorsSinceLastSuccess\": 0,\n \"consecutiveFailures\": 0\n },\n \"createdAt\": \"2025-01-01T00:00:00.000Z\",\n \"updatedAt\": \"2025-01-15T10:30:00.000Z\"\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Webhook unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The webhook ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `webhook_not_found`: No webhook exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "webhook_not_found" ], "description": "Machine-readable error code", "example": "webhook_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "patch": { "operationId": "updateWebhook", "summary": "Update a webhook", "description": "Updates a webhook's properties. Supports partial updates - only provided fields will be updated.\n\n### Path Parameters\n\n- `id` - The webhook ID (24-character ObjectId)\n\n### Request Body\n\nAll fields are optional. Only provided fields will be updated.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Human-readable name (max 100 chars) |\n| `url` | string | Webhook endpoint URL (must be HTTPS) |\n| `description` | string/null | Description (null to clear) |\n| `topics` | string[] | Event topics to subscribe to |\n| `status` | string | \"active\" to reactivate, \"paused\" to pause delivery |\n| `requestConfig` | object | Request configuration |\n| `requestConfig.headers` | object | Custom headers to send (max 10) |\n\n### Pausing and Reactivating Webhooks\n\nYou can pause a webhook to temporarily stop receiving events:\n\n```json\n{\n \"status\": \"paused\"\n}\n```\n\nWebhooks may also be automatically paused or suspended due to delivery failures. To reactivate:\n\n```json\n{\n \"status\": \"active\"\n}\n```\n\nReactivating a webhook resets the health metrics and allows it to receive events again.\n\n### Example: Update Topics\n\n```json\n{\n \"topics\": [\"post.created\", \"post.updated\", \"post.deleted\"]\n}\n```\n\n### Example: Update Request Config\n\n```json\n{\n \"requestConfig\": {\n \"headers\": {\n \"X-Custom-Header\": \"new-value\"\n }\n }\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Webhook unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookBody" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_parameter`: Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_parameter" ], "description": "Machine-readable error code", "example": "invalid_parameter" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `webhook_not_found`: No webhook exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "webhook_not_found" ], "description": "Machine-readable error code", "example": "webhook_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "deleteWebhook", "summary": "Delete a webhook", "description": "Permanently deletes a webhook.\n\n### Path Parameters\n\n- `id` - The webhook ID (24-character ObjectId)\n\n### Response\n\nReturns a deletion confirmation object:\n\n```json\n{\n \"id\": \"507f1f77bcf86cd799439011\",\n \"object\": \"webhook\",\n \"deleted\": true\n}\n```\n\n### Caution\n\nThis operation is **irreversible**. The webhook and its configuration will be permanently deleted.\nAfter deletion, no events will be sent to the webhook endpoint.\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Webhook unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhook" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The webhook ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `webhook_not_found`: No webhook exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "webhook_not_found" ], "description": "Machine-readable error code", "example": "webhook_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } }, "/v2/webhooks/{id}/secret": { "post": { "operationId": "refreshWebhookSecret", "summary": "Refresh webhook signing secret", "description": "Generates a new signing secret for a webhook. The previous secret is immediately invalidated.\n\n### Path Parameters\n\n- `id` - The webhook ID (24-character ObjectId)\n\n### Response\n\nReturns the updated webhook object, including the new signing secret.\n\n### Important\n\nAfter refreshing the secret, any integrations that verify webhook signatures using the old secret will stop working until they are updated with the new secret.\n\n### Example Response\n\n```json\n{\n \"object\": \"webhook\",\n \"id\": \"507f1f77bcf86cd799439011\",\n \"name\": \"Production Webhook\",\n \"url\": \"https://example.com/webhooks\",\n \"secret\": \"whsec_newSecret123abc456def\",\n \"topics\": [\"post.created\", \"post.updated\"],\n \"status\": \"active\",\n ...\n}\n```\n\n### Version Availability\n\nThis endpoint is only available in API version 2026-01-01.nova and newer.", "tags": [ "Webhooks" ], "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/FeaturebaseVersion" }, { "schema": { "type": "string", "description": "Webhook unique identifier", "example": "507f1f77bcf86cd799439011" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Bad Request\n\nPossible error codes:\n- `invalid_id`: The webhook ID format is invalid", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "invalid_id" ], "description": "Machine-readable error code", "example": "invalid_id" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 400 ], "description": "HTTP status code", "example": 400 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } }, "404": { "description": "Not Found\n\nPossible error codes:\n- `webhook_not_found`: No webhook exists with this ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error" ], "description": "The type of error returned", "example": "invalid_request_error" }, "code": { "type": "string", "enum": [ "webhook_not_found" ], "description": "Machine-readable error code", "example": "webhook_not_found" }, "message": { "type": "string", "description": "Human-readable error message", "example": "An error occurred" }, "param": { "type": "string", "description": "The parameter that caused the error (if applicable)", "example": "id" }, "status": { "type": "number", "enum": [ 404 ], "description": "HTTP status code", "example": 404 } }, "required": [ "type", "code", "message", "status" ] } }, "required": [ "error" ] } } } } } } } }, "webhooks": {}, "x-tagGroups": [ { "name": "Getting Started", "tags": [ "API Versioning", "Authentication", "Error Handling" ] }, { "name": "Feedback", "tags": [ "Boards", "Posts", "Post Statuses", "Comments", "Custom Fields" ] }, { "name": "Changelog", "tags": [ "Changelogs" ] }, { "name": "Organization", "tags": [ "Admins", "Teams", "Brands" ] }, { "name": "Users", "tags": [ "Contacts", "Companies" ] }, { "name": "Products", "tags": [ "Surveys", "Help Centers", "Conversations" ] }, { "name": "Integrations", "tags": [ "Webhooks" ] } ] }