{ "openapi": "3.0.1", "info": { "title": "Bloomfire API V2", "version": "v2", "description": "The Bloomfire platform has an ever-growing API for externally interacting with the content and information in your Bloomfire communities. This site provides information about the Bloomfire platform, documents the available API calls, and provides usage examples to allow developers like you to develop Bloomfire integrations. The documentation is written for a developer that has some experience working with REST-based APIs.\n\n**Note:** The API is being expanded to support greater functionality. We hope you enjoy the upgrades and welcome your feedback. Bookmark this API documentation for up-to-date support.\n\n# Terminology\n\nThe following table provides a description of Bloomfire terminology used throughout the documentation.\n| Term | Description |\n| --- | --- |\n| Community | A single Bloomfire community. A community is implicitly accessed by specifying a subdomain. If you have multiple communities, you will use different subdomains to access them via the API. |\n| Group | A group within a Community. This subset of Users and Contributions is only accessible by group members. Groups may be open to anyone to join, require approval to join, or require invitation to join. Group members may have different roles and notification settings than in the Community but must be active in the Community. |\n| Organization | The generic term for either a Community or a Group. |\n| User | A Bloomfire user account is tied to an email address, which uniquely identifies that user across all related organizations. However, users may have different levels of access within each organization and are assigned separate member IDs for each organization, which are the IDs returned by the API. |\n| Role | The set of user permissions for accessing Bloomfire. |\n| Contribution | A top-level piece of content created by members in Bloomfire with the intention of sharing it with the community. This includes posts, questions, series. |\n| Post | A contribution type created by a member or a group of members (co-authors) containing either text or media to be shared with the community. |\n| Series | A contribution type created by a member containing an ordered list of posts. |\n| Question | A contribution type created by a member that contains a question to the community. |\n| Answer | A sub-contribution created by a member in response to a specific question. An answer contains either text or media data. |\n| Comment | A sub-contribution containing text that is created by a member in response to an existing post, question, answer, or comment. |\n| Keyword | A keyword or tag is a user-specified label that improves the organization and searching of content. There is no restriction to what keywords can be applied to a contribution. |\n| Category | A category is one of a limited set of values that can be associated with a contribution that improves the organization and searching of content. Categories can only be defined by an admin or owner. |\n| Featured | A piece of content (post, question, series) promoted to the Featured section of the homepage. |\n\n# Public vs. Private\nBy default, content within Bloomfire is accessible only to members of the community. To access this private data via the API, you must use a session token.\nHowever, you can choose to make all content publicly searchable by changing the Public Access settings under Gear > Communities > Settings (Admins/Owners only). Individual pieces of content can then be set public or private.\n\n# User Roles\nIn order to simplify the administration of Bloomfire permissions, a set of functionality is rolled up under a user role. A given user can have a \"membership\" in each community or group within the user's account, and that membership will have an associated role. It is possible that a member can have the **Learner** role in one organization and the **Author** role in another.\nThe user role grid provides a list of API functionalities and the role that can execute each functionality. If public content is enabled for the organization, a non-member has read access to a subset of the content provided in an organization, but has no permissions to contribute content.\n\n| Bloomfire Roles | Learner | Author | Admin | Owner |\n| --- | ---| --- | --- | --- |\n| View content and member profiles | Yes | Yes | Yes | Yes |\n| Search contributions and profiles | Yes | Yes | Yes | Yes |\n| Update personal profile | Yes | Yes | Yes | Yes |\n| Ask a question (if Q&A enabled) | Yes | Yes | Yes | Yes |\n| Contribute a comment | Yes | Yes | Yes | Yes |\n| Like content | Yes | Yes | Yes | Yes |\n| Answer a question (if Q&A enabled) | | Yes | Yes | Yes |\n| Contribute a post | | Yes | Yes | Yes |\n| Manage public content (if public enabled) | | Yes | Yes | Yes |\n| Publish a post to multiple organizations | | Yes | Yes | Yes |\n| Contribute a series | | | Yes | Yes |\n| Manage featured content (if featured enabled) | | | Yes | Yes |\n| Manage categories | | | Yes | Yes |\n| Manage members | | | Yes | Yes |\n| Edit or delete any contribution or user profile | | | Yes | Yes |\n\n# Data Types\nThe response for each API request is returned in JSON format. The data types used in the response are described in the chart below.\n\n| Type | Description |\n| --- | --- |\n| String | Character string in UTF-8 |\n| Integer | 32-bit signed integer |\n| Boolean | True or False |\n| Timestamp | ISO datetime (e.g. YYYY-MM-DD-HH-MM-SS_TIMEZONE) |\n\n# Data Structures\nThe following table describes the Bloomfire data structures accessible through this API.\n| Content Type | API Route |\n| --- | --- |\n| Organization | /api/v2/organizations[/id] |\n| User | /api/v2/users[/id] |\n| Login | /api/v2/logins[/id] |\n| Post | /api/v2/posts[/id] |\n| Series | /api/v2/series[/id] |\n| Question | /api/v2/questions[[/id] |\n| Answer | /api/v2/answers[/id] |\n| Comment | /api/v2/comments[/id] |\n| Keyword | /api/v2/keywords[/id] |\n| Category | /api/v2/categories[/id] |\n| Featured | /api/v2/featured |\n| CustomField | /api/v2/custom_fields[/id] |\n| Group | /api/v2/groups[/id] |\n\n# Communities and Groups\nBloomfire allows a Community to have multiple groups. The groups accessible can be listed with an [API call to /api/v2/groups](#tag/Groups/paths/~1groups/get). From there, the group ID is used to qualify various endpoints. A user must have an active membership in the community to access a group, as the groups are nested within communities. API calls for groups add the Group ID as a qualifier after the \"/api/v2\" path fragment: \"/api/v2/groups/ID\". For example, to add someone to group 5:\n\n`[POST] /api/v2/groups/5/users`\n\nPayload:\n\n``` json\n{\n \"email\": \"user@email.org\",\n \"role\": \"author\",\n \"active\": true\n}\n```\n\n# Authorization Request Header\n\nUsed to pass the API session token retrieved using the methods described in\nthe Authentication section. Pass via the header instead of specifying\n`session_token` in a query parameter or post body.\n\ne.g. `Authorization: Bloomfire-Session-Token SESSION_TOKEN`\n\n# Bloomfire-Requested-Fields\n\nEach model accessible via the application API has a \"Presenter\" which controls\naccess to the available fields.\n\nThese fields can be specified in the `bloomfire-requested-fields` (or\n`x-bloomfire-requested-fields`) header as a comma separated list\n\n_Note that the string can not contain whitespace_.\n\nIf the field name refers to another model, inclusion of the field returns the\n`id` of the model (or array of models). Specific fields can be returned by\nspecifying them inside parentheses.\n\n**Examples**\n\nThe following examples are for the `Post` model and its children.\n\n**`id,title,author`**\n\n```json\n{\n \"id\": 1,\n \"title\": \"Test\",\n \"author\": {\n \"id\": 1\n }\n}\n```\n\n**id,title,author(email)**\n\n```json\n{\n \"id\": 1,\n \"title\": \"Test\",\n \"author\": {\n \"email\": \"admin@bloomfire.com\"\n }\n}\n```\n\n**`id,title,contents(id,title,original_content_type,original_file_name)`**\n\n```json\n{\n \"id\": 1,\n \"title\": \"Test\",\n \"contents\": [\n {\n \"id\": 6,\n \"title\": \"Typescript Cheat Sheet\",\n \"original_content_type\": \"application/pdf\",\n \"original_file_name\": \"TypeScript_Cheat_Sheet.pdf\"\n }\n ]\n}\n```\n" }, "servers": [ { "url": "/api/v2" } ], "components": { "schemas": { "accept_answer_object": { "type": "object", "properties": { "accepted": { "type": "boolean", "description": "accepted answer" } } }, "answer_object": { "type": "object", "properties": { "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "published": { "type": "boolean" }, "likes_count": { "type": "integer" }, "liked": { "type": "boolean" }, "likes": { "type": "array", "items": { "type": "integer" } }, "body": { "type": "string" }, "accepted": { "type": "boolean" }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } }, "contents": { "type": "array", "items": { "type": "integer" } }, "pending_approval": { "type": "boolean" } } }, "article_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the article" }, "guid": { "type": "string", "description": "Globally unique identifier for the article" }, "title": { "type": "string", "description": "Title of the article" }, "url": { "type": "string", "description": "URL of the article" }, "description": { "type": "string", "description": "Description or summary of the article" }, "published_at": { "type": "string", "format": "date-time", "description": "Publication date of the article" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "article_source_id": { "type": "integer", "description": "ID of the article source this article belongs to" }, "thumbnail_url": { "type": "string", "description": "URL of the article thumbnail image" }, "thumbnail_width": { "type": "integer", "description": "Width of the thumbnail image" }, "thumbnail_height": { "type": "integer", "description": "Height of the thumbnail image" }, "content_ids": { "type": "array", "items": { "type": "integer" }, "description": "Array of content IDs associated with the article" }, "shared_with_bloomfire": { "type": "boolean", "description": "Whether the article has been shared with Bloomfire" }, "oembed": { "type": "object", "description": "Open Graph Embed Data (oEmbed) for the article", "properties": { "url": { "type": "string", "description": "URL of the article" }, "type": { "type": "string", "description": "Type of content (e.g., 'link')" }, "title": { "type": "string", "description": "Title of the article" }, "description": { "type": "string", "description": "Description of the article" }, "provider_name": { "type": "string", "description": "Name of the content provider" }, "provider_url": { "type": "string", "description": "URL of the content provider" }, "thumbnail_url": { "type": "string", "description": "URL of the thumbnail image" }, "thumbnail_width": { "type": "integer", "description": "Width of the thumbnail" }, "thumbnail_height": { "type": "integer", "description": "Height of the thumbnail" }, "version": { "type": "string", "description": "oEmbed version" } } } }, "required": [ "id", "guid", "title", "published_at", "created_at", "updated_at", "article_source_id" ] }, "article_source_object": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier for the article source" }, "name": { "type": "string", "description": "Name of the article source" }, "consumer_type": { "type": "string", "enum": [ "rss", "api" ], "description": "Type of consumer used to fetch articles" }, "config": { "type": "object", "description": "Configuration settings for the article source", "properties": { "url": { "type": "string", "description": "URL for RSS feed or API endpoint" }, "frequency": { "type": "string", "description": "Consumption frequency (e.g., '1h', 'daily', 'weekly')" } } }, "searchable_in": { "type": "array", "items": { "type": "integer" }, "description": "Array of organization IDs where articles are searchable" }, "included_in_feed_in": { "type": "array", "items": { "type": "integer" }, "description": "Array of organization IDs where articles appear in feeds" }, "status": { "type": "string", "enum": [ "healthy", "unhealthy", "broken", "consuming" ], "description": "Current status of the article source" }, "last_consumed_at": { "type": "string", "format": "date-time", "description": "Timestamp of the last successful consumption" }, "last_error_message": { "type": "string", "description": "Last error message if any" }, "retries": { "type": "integer", "description": "Number of retry attempts" }, "created_at": { "type": "string", "format": "date-time", "description": "Creation timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "Last update timestamp" }, "logo_url": { "type": "string", "description": "URL of the article source logo" }, "authorization_header": { "type": "string", "description": "Authorization header for API access" } }, "required": [ "id", "name", "consumer_type", "config", "status", "created_at", "updated_at" ] }, "bulk_delete_contributions_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished deleting contributions.", "percent": 100, "type": "BulkDeleteContributions", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_delete_contributions_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkDeleteContributions" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkDeleteContributions", "args": { "contributions": [ 5, 8, 22 ], "send_email": false } } }, "bulk_member_export_job_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2017-03-27T11:44:49-05:00", "status": "completed", "message": "Completed at 2017-03-27 11:45:40 -0500", "percent": 100, "type": "BulkMemberExportJob", "organization_id": 1, "user_id": 1, "result": { "csv": "https://example.com/exports/6123.csv" } } }, "bulk_member_export_job_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkMemberExportJob" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for export. Optional if organization_ids is provided.", "items": { "type": "integer" } }, "organization_ids": { "type": "array", "description": "Organizations from which to export users. Optional if user_ids is provided.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkMemberExportJob", "args": { "user_ids": [ 5, 8, 22 ], "organization_ids": [ 1, 2, 3 ], "send_email": false } } }, "bulk_member_import_job_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "24805945d56d4ce3b95925fe186ec930", "submitted_at": "2017-03-27T09:44:39-05:00", "status": "completed", "message": "Completed at 2017-03-27 9:45:40 -0500", "percent": 100, "type": "BulkMemberImportJob", "organization_id": 1, "user_id": 1, "result": { "unchanged": 18, "updated": 2 } } }, "bulk_member_import_job_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkMemberImportJob" }, "args": { "type": "object", "properties": { "s3_uploads": { "type": "array", "items": { "type": "object", "description": "Files can be uploaded to S3 for processing via the S3 Tempfile API", "properties": { "bucket": { "type": "string", "description": "An AWS S3 bucket in which to find the upload file." }, "key": { "type": "string", "description": "An AWS S3 key in which to find the upload file (e.g. uploads/a06064cc-2da9-4c30-b690-389f7f84213b/users.csv)." } } } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkMemberImportJob", "args": { "s3_uploads": [ { "bucket": "", "key": "uploads/a06064cc-2da9-4c30-b690-389f7f84213b/users.csv" } ], "send_email": false } } }, "bulk_resend_invitation_email_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished resending invitation email for 3 user(s).", "percent": 100, "type": "BulkResendInvitationEmail", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_resend_invitation_email_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkResendInvitationEmail" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for bulk action.", "items": { "type": "integer" } }, "organization_ids": { "type": "array", "description": "Organization ids from which users will receive invitation emails. This field is optional - if omitted the invitation email defaults to the current community.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkResendInvitationEmail", "args": { "user_ids": [ 5, 8, 22 ], "organization_ids": [ 1, 2, 3 ], "send_email": false } } }, "bulk_reset_password_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished resetting password for 3 user(s).", "percent": 100, "type": "BulkResetPassword", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_reset_password_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkResetPassword" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for bulk action.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkResetPassword", "args": { "user_ids": [ 5, 8, 22 ], "send_email": false } } }, "bulk_send_message_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished sending message for 3 user(s).", "percent": 100, "type": "BulkSendMessage", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_send_message_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkSendMessage" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for bulk action.", "items": { "type": "integer" } }, "subject": { "type": "string", "description": "Email subject." }, "body": { "type": "string", "description": "Email body." }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkSendMessage", "args": { "user_ids": [ 5, 8, 22 ], "subject": "This is the email subject", "body": "This is the email body.", "send_email": false } } }, "bulk_update_authors_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating authors for 3 contribution(s).", "percent": 100, "type": "BulkUpdateAuthors", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_authors_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateAuthors" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "add": { "type": "array", "description": "User_ids for authors to add to selected contributions.", "items": { "type": "integer" } }, "remove": { "type": "array", "description": "User_ids for authors to remove from selected contributions.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateAuthors", "args": { "contributions": [ 5, 8, 22 ], "add": [ 3, 7 ], "remove": [ 5 ], "send_email": false } } }, "bulk_update_contribution_thumbnail_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating contribution thumbnail for 3 contribution(s).", "percent": 100, "type": "BulkUpdateContributionThumbnail", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_contribution_thumbnail_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateContributionThumbnail" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "add": { "type": "object", "properties": { "key": { "type": "integer", "description": "S3 Key returned from Filestack." }, "bucket": { "type": "string", "description": "S3 Bucket where the image has been uploaded." } } }, "remove": { "type": "boolean", "description": "Setting this to true will remove explicitly added thumbnails from all selected contributions. Please note that contributions with content items will still have implicitly assigned thumbnails." }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateContributionThumbnail", "args": { "contributions": [ 5, 8, 22 ], "add": { "key": "your-directory/uploads/BmdD67rXQN2Bl5wzGMSw_12 seasons of texas.jpg", "bucket": "s3-bucket" }, "remove": false, "send_email": false } } }, "bulk_update_profile_picture_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating profile picture for 3 user(s).", "percent": 100, "type": "BulkUpdateProfilePicture", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_profile_picture_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateProfilePicture" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for bulk action.", "items": { "type": "integer" } }, "add": { "type": "object", "properties": { "key": { "type": "integer", "description": "S3 Key returned from Filestack." }, "bucket": { "type": "string", "description": "S3 Bucket where the image has been uploaded." } } }, "remove": { "type": "boolean", "description": "Remove profile picture from selected users." }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateProfilePicture", "args": { "user_ids": [ 5, 8, 22 ], "add": { "key": "your-directory/uploads/profile-picture.jpg", "bucket": "s3-bucket" }, "remove": false, "send_email": false } } }, "bulk_update_publish_status_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating publish status for 3 contribution(s).", "percent": 100, "type": "BulkUpdatePublishStatus", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_publish_status_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdatePublishStatus" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "publish": { "type": "array", "description": "Organization ids to which the selected contributions should be published.", "items": { "type": "integer" } }, "unpublish": { "type": "array", "description": "Organization ids from which the selected contributions should be unpublished.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdatePublishStatus", "args": { "contributions": [ 5, 8, 22 ], "publish": [ 3, 7 ], "unpublish": [ 5 ], "send_email": false } } }, "bulk_update_roles_and_access_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating roles and access for 3 contribution(s).", "percent": 100, "type": "BulkUpdateRolesAndAccess", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_roles_and_access_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateRolesAndAccess" }, "args": { "type": "object", "properties": { "user_ids": { "type": "array", "description": "User ids for bulk action.", "items": { "type": "integer" } }, "owner": { "type": "array", "description": "Organization ids where specified users should be assigned an owner role. Please note that only owners have permission to assign others to an owner role.", "items": { "type": "integer" } }, "admin": { "type": "array", "description": "Organization ids where specified users should be assigned an admin role.", "items": { "type": "integer" } }, "moderator": { "type": "array", "description": "Organization ids where specified users should be assigned an moderator role.", "items": { "type": "integer" } }, "author": { "type": "array", "description": "Organization ids where specified users should be assigned an author role.", "items": { "type": "integer" } }, "learner": { "type": "array", "description": "Organization ids where specified users should be assigned an learner role.", "items": { "type": "integer" } }, "remove": { "type": "array", "description": "Organization ids to remove access for specified users.", "items": { "type": "integer" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateRolesAndAccess", "args": { "user_ids": [ 5, 8, 22 ], "owner": [ 4 ], "admin": [ 5 ], "moderator": [ 1, 2 ], "author": [ 13, 9 ], "learner": [ 6 ], "remove": [ 19 ], "send_email": false } } }, "bulk_update_tags_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating tags for 3 contribution(s).", "percent": 100, "type": "BulkUpdateTags", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_tags_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateTags" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "add": { "type": "array", "description": "Tags to add to selected contributions.", "items": { "type": "string" } }, "remove": { "type": "array", "description": "Tags to remove from selected contributions.", "items": { "type": "string" } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateTags", "args": { "contributions": [ 5, 8, 22 ], "add": [ "avocado", "apple" ], "remove": [ "banana" ], "send_email": false } } }, "bulk_update_taxa_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "3ec7ca5c01ca0c492e67418cd12fc1e6", "submitted_at": "2019-09-13T11:44:49-05:00", "status": "completed", "message": "Finished updating taxa for 3 contribution(s).", "percent": 100, "type": "BulkUpdateTaxa", "organization_id": 1, "user_id": 1, "result": null } }, "bulk_update_taxa_request_object": { "type": "object", "properties": { "type": { "type": "string", "pattern": "BulkUpdateTaxa" }, "args": { "type": "object", "properties": { "contributions": { "type": "array", "description": "Contribution ids for bulk action.", "items": { "type": "integer" } }, "add": { "type": "array", "description": "Taxa to add to selected contributions.", "items": { "type": "object", "properties": { "taxonomy_id": { "type": "integer", "description": "Taxonomy id corresponding to the taxon to be added." }, "taxon_id": { "type": "string", "description": "Taxon uuid." } } } }, "remove": { "type": "array", "description": "Taxa to remove from selected contributions.", "items": { "type": "object", "properties": { "taxonomy_id": { "type": "integer", "description": "Taxonomy id corresponding to the taxon to be removed." }, "taxon_id": { "type": "string", "description": "Taxon uuid." } } } }, "send_email": { "type": "boolean", "description": "Set to true if an email should be sent to the admin creating the job when the job completes. Otherwise, status can be checked via the Jobs API." } } } }, "required": [ "type", "args" ], "example": { "type": "BulkUpdateTags", "args": { "contributions": [ 5, 8, 22 ], "add": [ { "taxonomy_id": 1, "taxon_id": "1cd53a83-8be6-43be-8c43-76af154e9d91" } ], "remove": [ { "taxonomy_id": 1, "taxon_id": "23f53r76-3fd2-25np-1s32-56wq098x9o70" } ], "send_email": false } } }, "category_object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "comment_object": { "type": "object", "properties": { "likes_count": { "type": "integer" }, "liked": { "type": "boolean" }, "likes": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "comment": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" }, "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } } } }, "count_response": { "type": "object", "properties": { "count": { "type": "integer" } } }, "create_answer_object": { "type": "object", "required": [ "answer" ], "properties": { "answer": { "type": "string", "description": "The text of the answer" } } }, "create_post_response_object": { "description": "Results with the pre-filled `bloomfire-requested-fields`", "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "post_body": { "type": "string" }, "author": { "type": "object", "properties": { "email": { "type": "string" } } }, "contents": { "type": "array", "items": { "type": "object", "description": "The attachments", "properties": { "id": { "type": "integer" }, "original_file_name": { "type": "string" }, "source": { "type": "string" }, "failure_message": { "type": "string", "description": "null if no error" } } } } }, "example": { "id": 999, "title": "Attachment test", "description": "The attachment will be added to the body as [contents|{id}|]", "post_body": "[content|42|]", "author": { "email": "admin@bloomfire.com" }, "keywords": [ "external" ], "contents": [ { "id": 42, "original_file_name": "attachment.jpg", "source": "/tmp/attachment.jpg", "failure_message": null } ] } }, "custom_field_object": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "internal_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "text", "single-select", "multi-select" ] }, "label": { "type": "string" }, "active": { "type": "boolean" }, "user_editable": { "type": "boolean" }, "sort_order": { "type": "integer" }, "values": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "auxiliary_values": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "type" ] }, "draft_object": { "type": "object", "description": "Default response object if no fields specified", "properties": { "id": { "type": "string" }, "name": { "type": "string", "description": "Contribution title" }, "description": { "type": "string" }, "preview_url": { "type": "string", "description": "Link to view draft version in web browser" }, "fingerprint": { "type": "string", "description": "Content digest. Used to identify updates" }, "updated_at": { "type": "string", "format": "date-time" }, "approver": { "type": "object", "description": "Approver of the draft", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" } } }, "contributor": { "type": "object", "description": "Author of the draft", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" } } }, "publish_note": { "type": "object", "properties": { "body": { "type": "string" } } }, "post_body": { "type": "string" }, "contents": { "type": "array", "description": "List of attachemnts", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "original_content_type": { "type": "string", "description": "Mime type" }, "original_file_name": { "type": "string" }, "download": { "type": "object", "description": "Link to download original file", "properties": { "original": { "type": "string", "format": "uri" } } }, "ephermeral_urls": { "type": "object", "description": "Time-limited links to download processed pdf, image, etc.", "properties": { "hd": { "type": "string", "format": "uri" } } } } } } }, "example": { "id": "456", "name": "My Draft Post", "description": "A description of the draft", "preview_url": "https://example.bloomfire.com/posts/123?version=456", "fingerprint": "abc123def456", "updated_at": "2024-01-15T12:00:00Z", "approver": { "first_name": "Jane", "last_name": "Approver", "email": "j.approver@example.com" }, "contributor": { "first_name": "John", "last_name": "Author", "email": "j.author@example.com" }, "publish_note": { "body": "Ready for review" }, "post_body": "

The post content

[content|789|]

with inline attachment

", "contents": [ { "id": 789, "original_content_type": "application/pdf", "original_file_name": "document.pdf", "download": { "original": "https://example.bloomfire.com/api/v2/contents/789/download/original" } } ] } }, "error": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string" } } }, "featured_series_object": { "type": "object", "properties": { "featured": { "type": "boolean" } } }, "follow_object": { "type": "object", "properties": { "id": { "type": "integer" } } }, "group_object": { "type": "object", "properties": { "active": { "type": "boolean" }, "active_custom_fields_limit": { "type": "boolean" }, "available_languages": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "integer" }, "name": { "type": "string" }, "show_assessments_settings": { "type": "boolean" }, "synapse_default_mode": { "type": "string" }, "synapse_panel_open_by_default": { "type": "boolean" }, "updated_at": { "type": "string", "format": "date-time" } } }, "job_object": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "object" }, "metadata": { "type": "object" } }, "example": { "uuid": "d35343ee107a4d54a566c71cfafe62f4", "submitted_at": "2017-02-17T10:44:49-05:00", "status": "completed", "message": "Completed at 2017-02-17 10:45:40 -0500", "percent": 100, "type": "BulkMemberExportJob", "organization_id": 1, "user_id": 1, "result": { "csv": "https://example.com/exports/6123.csv" } } }, "job_request_object": { "type": "object", "properties": { "type": { "type": "string" }, "args": { "type": "object" } }, "required": [ "type" ] }, "keyword_object": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "killed_job_object": { "type": "object", "properties": { "uuid": { "type": "string" }, "submitted_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "message": { "type": "string" }, "percent": { "type": "integer" }, "type": { "type": "string" }, "organization_id": { "type": "integer" }, "user_id": { "type": "integer" }, "result": { "type": "string" }, "metadata": { "type": "object" } }, "example": { "uuid": "7919000922e2b42bd323903e97f5a859", "submitted_at": "2017-03-27T11:52:40-05:00", "status": "killed", "message": "Killed at 2017-03-27 11:53:01 -0500", "percent": 30, "type": "BulkMemberImportJob", "organization_id": 1, "user_id": 1, "result": null } }, "mcp_article_result": { "type": "object", "description": "An article (external/enterprise search) result returned by the MCP context endpoint.", "properties": { "type": { "type": "string", "enum": [ "article" ] }, "id": { "type": "integer" }, "url": { "type": "string", "format": "uri", "description": "The full URL to view this article." }, "name": { "type": "string" }, "connection_type": { "type": "string", "description": "The integration type, e.g. `sharepoint`. Null for standard file uploads.", "example": "sharepoint" }, "description": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "original_url": { "type": "string", "format": "uri", "description": "The source URL of the article." }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/mcp_content_fields" } } } }, "mcp_board_result": { "type": "object", "description": "A board result returned by the MCP context endpoint.", "properties": { "type": { "type": "string", "enum": [ "board" ] }, "id": { "type": "integer" }, "url": { "type": "string", "format": "uri", "description": "The full URL to view this board." }, "owner": { "type": "object", "description": "The user who owns this board.", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } }, "contributors": { "type": "array", "description": "Users who have editor access to this board.", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } } } }, "editable_draft": { "type": "object", "description": "The current unpublished draft of the board.", "properties": { "name": { "type": "string" }, "description": { "type": "string" } } }, "widgets": { "type": "array", "description": "Board widgets whose content matched the search query. Only present when a widget reference was matched.", "optional": true, "items": { "oneOf": [ { "type": "object", "description": "A RichTextWidget whose body or embedded content matched the query.", "properties": { "widget_type": { "type": "string", "enum": [ "RichTextWidget" ] }, "id": { "type": "integer" }, "post_body": { "type": "string", "description": "Sanitized HTML body of the widget." }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/mcp_content_fields" } } } }, { "type": "object", "description": "A DocumentWidget — a single file attachment embedded directly in the board.", "properties": { "widget_type": { "type": "string", "enum": [ "DocumentWidget" ] }, "content": { "$ref": "#/components/schemas/mcp_content_fields" } } } ] } } } }, "mcp_content_fields": { "type": "object", "description": "A file attachment associated with a content item.", "properties": { "id": { "type": "integer" }, "original_content_type": { "type": "string", "example": "application/pdf" }, "original_file_name": { "type": "string", "example": "guide.pdf" }, "content_url": { "type": "string", "format": "uri" }, "download": { "type": "string", "format": "uri", "description": "Direct download URL. Null if downloads are blocked or content has no original file." } } }, "mcp_content_response_object": { "type": "array", "description": "Up to 10 heterogeneous enriched content results for AI context consumption.", "maxItems": 10, "items": { "oneOf": [ { "$ref": "#/components/schemas/mcp_post_result" }, { "$ref": "#/components/schemas/mcp_question_result" }, { "$ref": "#/components/schemas/mcp_article_result" }, { "$ref": "#/components/schemas/mcp_board_result" }, { "$ref": "#/components/schemas/mcp_series_result" } ] }, "example": [ { "type": "post", "id": 42, "name": "Employee Benefits Overview", "description": "A summary of available employee benefits.", "fingerprint": "abc123def456", "updated_at": "2025-06-01T12:00:00.000Z", "approver": null, "contributor": { "first_name": "John", "last_name": "Doe", "email": "john@example.com" }, "post_body": "

Details about employee benefits...

", "keywords": [ "benefits", "hr" ], "contents": [ { "id": 101, "original_content_type": "application/pdf", "original_file_name": "benefits-guide.pdf", "content_url": "https://cdn.example.com/benefits-guide.pdf", "download": "https://app.example.com/api/v2/contents/101/download/original" } ] }, { "type": "question", "id": 7, "name": "What are the dental benefits?", "description": "", "fingerprint": "xyz789", "updated_at": "2025-05-20T09:30:00.000Z", "approver": null, "contributor": { "first_name": "Alice", "last_name": "Brown", "email": "alice@example.com" }, "post_body": "

Please explain the dental plan options.

", "keywords": [ "dental", "benefits" ], "contents": [], "answers": [ { "id": 3, "body": "We offer two dental plan tiers...", "accepted": true, "author": { "first_name": "Bob", "last_name": "Lee", "email": "bob@example.com" }, "updated_at": "2025-05-21T10:00:00.000Z" } ] } ] }, "mcp_post_result": { "type": "object", "description": "A post result returned by the MCP context endpoint.", "properties": { "type": { "type": "string", "enum": [ "post" ] }, "id": { "type": "integer" }, "group_id": { "description": "The group this post is namespaced to, or null when it lives at the community root.", "type": [ "integer", "null" ] }, "url": { "type": "string", "format": "uri", "description": "The full URL to view this post." }, "name": { "type": "string" }, "description": { "type": "string" }, "fingerprint": { "type": "string", "description": "SHA-256 digest of the current draft's versionable attributes." }, "updated_at": { "type": "string", "format": "date-time" }, "contributor": { "description": "The primary author of this content.", "oneOf": [ { "$ref": "#/components/schemas/mcp_user_fields" }, { "type": "null" } ] }, "post_body": { "type": "string", "description": "Sanitized HTML body of the post." }, "keywords": { "type": "array", "items": { "type": "string" } }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/mcp_content_fields" } }, "comments": { "type": "array", "description": "Comments whose text matched the search query. Only present when a comment reference was matched.", "optional": true, "items": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "author": { "oneOf": [ { "$ref": "#/components/schemas/mcp_user_fields" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "mcp_question_result": { "type": "object", "description": "A question result returned by the MCP context endpoint.", "properties": { "type": { "type": "string", "enum": [ "question" ] }, "id": { "type": "integer" }, "group_id": { "description": "The group this question is namespaced to, or null when it lives at the community root.", "type": [ "integer", "null" ] }, "url": { "type": "string", "format": "uri", "description": "The full URL to view this question." }, "name": { "type": "string" }, "description": { "type": "string" }, "fingerprint": { "type": "string", "description": "SHA-256 digest of the current draft's versionable attributes." }, "updated_at": { "type": "string", "format": "date-time" }, "contributor": { "description": "The primary author of this question.", "oneOf": [ { "$ref": "#/components/schemas/mcp_user_fields" }, { "type": "null" } ] }, "post_body": { "type": "string", "description": "Sanitized HTML body of the question." }, "keywords": { "type": "array", "items": { "type": "string" } }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/mcp_content_fields" } }, "answers": { "type": "array", "description": "Answers whose text matched the search query, always including the accepted answer when one exists. Only present when an answer reference was matched.", "optional": true, "items": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "accepted": { "type": "boolean" }, "author": { "oneOf": [ { "$ref": "#/components/schemas/mcp_user_fields" }, { "type": "null" } ] }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "mcp_series_result": { "type": "object", "description": "A series result returned by the MCP context endpoint.", "properties": { "type": { "type": "string", "enum": [ "series" ] }, "id": { "type": "integer" }, "group_id": { "description": "The group this series is namespaced to, or null when it lives at the community root.", "type": [ "integer", "null" ] }, "url": { "type": "string", "format": "uri", "description": "The full URL to view this series." }, "name": { "type": "string" }, "description": { "type": "string" }, "fingerprint": { "type": "string", "description": "SHA-256 digest of the current draft's versionable attributes." }, "updated_at": { "type": "string", "format": "date-time" }, "contributor": { "description": "The primary author of this series.", "oneOf": [ { "$ref": "#/components/schemas/mcp_user_fields" }, { "type": "null" } ] }, "post_body": { "type": "string", "description": "Sanitized HTML body of the series." }, "keywords": { "type": "array", "items": { "type": "string" } }, "contents": { "type": "array", "items": { "$ref": "#/components/schemas/mcp_content_fields" } }, "contributions": { "type": "array", "description": "Published contributions (posts and questions) contained in this series.", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "post", "question" ] }, "id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "name": { "type": "string" } } } } } }, "mcp_user_fields": { "type": "object", "description": "Minimal user identity fields returned in MCP responses.", "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "notification_object": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "url": { "type": "string" }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } }, "message": { "type": "string" }, "notes": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "read_state": { "type": "string", "enum": [ "unviewed", "unread", "viewed", "clicked" ] }, "reason": { "type": "string" }, "description": { "type": "string" }, "metadata": { "type": "object" } } }, "organization_object": { "type": "object", "properties": { "id": { "type": "integer" }, "subdomain": { "type": "string" }, "support_email": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "name": { "type": "string" }, "active": { "type": "boolean" }, "active_custom_fields_limit": { "type": "boolean" }, "available_languages": { "type": "array", "items": { "type": "string" } }, "authenticators_count": { "type": "integer" }, "authenticators": { "type": "string" }, "posts_count": { "type": "integer" }, "series_count": { "type": "integer" }, "show_assessments_settings": { "type": "boolean" }, "synapse_default_mode": { "type": "string" }, "synapse_panel_open_by_default": { "type": "boolean" }, "questions_count": { "type": "integer" }, "free_trial": { "type": "boolean" }, "ask_a_question": { "type": "boolean" }, "has_featured": { "type": "boolean" }, "organizations_count": { "type": "integer" }, "organizations": { "type": { "$ref": "#/components/schemas/organization_object" } } } }, "post_object": { "type": "object", "description": "Default response object if no fields specified", "properties": { "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "public": { "type": "boolean" }, "read_only": { "type": "boolean" }, "origin_url": { "type": "string", "description": "Upstream source url for readonly posts" }, "source": { "type": "string", "description": "Upstream source for readonly posts. (e.g.,`google-drive`, `confluence`)" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "published": { "type": "boolean" }, "followers_count": { "type": "integer" }, "followed": { "type": "boolean" }, "likes_count": { "type": "integer" }, "categories_count": { "type": "integer" }, "keywords_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "integer" } }, "followers": { "type": "array", "items": { "type": "users" } }, "liked": { "type": "boolean" }, "likes": { "type": "array", "items": { "type": "Likes" } }, "series": { "type": "array", "items": { "type": "posts" } }, "keywords": { "type": "array", "items": { "type": "integer" } }, "popularity": { "type": "integer" }, "views_count": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "contents_count": { "type": "integer" }, "series_count": { "type": "integer" }, "featured": { "type": "boolean" }, "contents": { "type": "array", "items": { "type": "integer" } }, "author": { "type": "array", "items": { "type": "integer" } }, "highlighted_matches": { "type": "array", "items": { "type": "string" } }, "workflow_events": { "type": "array", "description": "Moderation workflow events created during publish", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "event_id": { "type": "integer" }, "publish_location_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "post_series_object": { "type": "object", "properties": { "contributions": { "type": "array", "items": { "type": "integer" } }, "description": { "type": "string" }, "name": { "type": "string" } } }, "public_series_object": { "type": "object", "properties": { "public": { "type": "boolean" } } }, "question_object": { "type": "object", "properties": { "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "public": { "type": "boolean" }, "published": { "type": "boolean" }, "keywords_count": { "type": "integer" }, "keywords": { "type": "array", "items": { "type": "integer" } }, "likes": { "type": "array", "items": { "type": "Likes" } }, "likes_count": { "type": "integer" }, "liked": { "type": "boolean" }, "followed": { "type": "boolean" }, "followers_count": { "type": "integer" }, "followers": { "type": "array", "items": { "type": "users" } }, "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "views_count": { "type": "integer" }, "popularity": { "type": "integer" }, "question": { "type": "string" }, "explanation": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "answers_count": { "type": "integer" }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } }, "answers": { "type": "array", "items": { "type": "integer" } }, "accepted": { "type": "boolean" }, "workflow_events": { "type": "array", "description": "Moderation workflow events created during publish", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "event_id": { "type": "integer" }, "publish_location_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "s3_post_object": { "type": "object", "properties": { "form_data": { "type": "object", "properties": { "AWSAccessKeyId": { "type": "string" }, "key": { "type": "string" }, "policy": { "type": "string" }, "signature": { "type": "string" }, "Secure": { "type": "string" }, "acl": { "type": "string" }, "success_action_status": { "type": "string" }, "x-amz-server-side-encryption": { "type": "string" } } }, "url": { "type": "string" }, "bucket": { "type": "string" } }, "example": { "form_data": { "AWSAccessKeyId": "", "key": "uploads/50de8870-f206-4728-af17-97c150f5ffb3/082204-phone.jpg", "policy": "", "signature": "", "Secure": "true", "acl": "authenticated-read", "success_action_status": "201", "x-amz-server-side-encryption": "AES256" }, "url": "https://.s3.amazonaws.com/", "bucket": "" } }, "s3_tempfile_object": { "type": "object", "properties": { "form_data": { "type": "object", "properties": { "acl": { "type": "string" }, "key": { "type": "string" }, "success_action_status": { "type": "string" }, "policy": { "type": "string" }, "x-amz-credential": { "type": "string" }, "x-amz-algorithm": { "type": "string" }, "x-amz-date": { "type": "string" }, "x-amz-security-token": { "type": "string" }, "x-amz-signature": { "type": "string" } } }, "url": { "type": "string" }, "bucket": { "type": "string" }, "key": { "type": "string" }, "policy": { "type": "string" }, "signature": { "type": "string" } }, "example": { "form_data": { "acl": "private", "key": "uploads/cad7b47b-1a58-422f-bf50-9c23e9bcfd25/users.csv", "success_action_status": "201", "policy": "", "x-amz-credential": "/20171109/us-east-1/s3/aws4_request", "x-amz-algorithm": "AWS4-HMAC-SHA256", "x-amz-date": "20171109T213035Z", "x-amz-security-token": "", "x-amz-signature": "" }, "url": "https://.s3.amazonaws.com", "bucket": "", "key": "", "access_key_id": "", "policy": "", "signature": "" } }, "search_object": { "type": "object", "properties": { "highlight": { "type": "array", "items": { "name": "strings" } }, "type": { "type": "string" }, "instance": { "type": "array", "items": { "type": "integer" } } }, "example": { "highlight": { "name": [ "Our Great Products Help Increase Efficiency" ] }, "type": "post", "instance": { "id": 2 } } }, "series_object": { "type": "object", "properties": { "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "public": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "published": { "type": "boolean" }, "posts": { "type": "array", "items": { "type": "posts" } }, "questions": { "type": "array", "items": { "type": "questions" } }, "followers_count": { "type": "integer" }, "followed": { "type": "boolean" }, "followers": { "type": "array", "items": { "type": "integer" } }, "likes_count": { "type": "integer" }, "categories_count": { "type": "integer" }, "keywords_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "integer" } }, "keywords": { "type": "array", "items": { "type": "integer" } }, "liked": { "type": "boolean" }, "likes": { "type": "array", "items": { "type": "Likes" } }, "popularity": { "type": "integer" }, "views_count": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "posts_count": { "type": "integer" }, "featured": { "type": "boolean" }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } }, "series": { "type": "array", "items": { "type": "posts" } }, "series_count": { "type": "integer" }, "workflow_events": { "type": "array", "description": "Moderation workflow events created during publish", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "event_id": { "type": "integer" }, "publish_location_ids": { "type": "array", "items": { "type": "integer" } } } } } } }, "updated_answer_object": { "type": "object", "properties": { "short": { "type": "string" } } }, "updated_comment_object": { "type": "object", "properties": { "comment": { "type": "string" }, "publish_state": { "type": "string" } } }, "updated_post_object": { "type": "object", "properties": { "title": { "type": "string" }, "post_body": { "type": "string" }, "public": { "type": "boolean" }, "published": { "type": "boolean" }, "description": { "type": "string" }, "contents": { "type": "array", "description": "If this key is included all current content ids *must* be referenced or they will be deleted", "items": { "anyOf": [ { "type": "object", "description": "A currently included attachment to be kept or updated", "required": [ "id" ], "properties": { "id": { "type": "integer" }, "description": { "type": "string" }, "original_file_name_override": { "type": "string" }, "source": { "type": "string" } } }, { "$ref": "#/components/schemas/upload_post_object/properties/contents/items" } ] } } }, "example": { "description": "Added new attachment", "contents": [ { "id": 42, "description": "Adding optional description to the previous upload" }, { "source": "/tmp/new-attachment.pdf", "file": { "policy": "eyJleXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "signature": "7dXXXXXXXXXXXXXXXXXXXXXXXXX=", "key": "uploads/00000000-0000-0000-0000-000000000002/new-attachment.pdf", "access_key_id": "AKIXXXXXXXXXXXXXXXXXX", "bucket": "" } } ] } }, "updated_question_object": { "type": "object", "properties": { "public": { "type": "boolean" }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } }, "explanation": { "type": "string" }, "question": { "type": "string" }, "published": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "integer" } }, "categories": { "type": "array", "items": { "type": "integer" } } } }, "updated_user_object": { "type": "object", "properties": { "email": { "type": "string" }, "role": { "type": "string" }, "active": { "type": "boolean" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "bio": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" } } }, "upload_post_object": { "type": "object", "description": "Either `post_body` or `contents` (with at least one item) must be provided.", "required": [ "title" ], "properties": { "title": { "type": "string" }, "post_body": { "type": "string", "description": "HTML content for the contribution" }, "public": { "type": "boolean" }, "published": { "type": "boolean" }, "read_only": { "type": "boolean" }, "keyword_list": { "type": "array", "description": "Tags", "items": "string" }, "origin_url": { "type": "string", "description": "Upstream source url for readonly posts" }, "source": { "type": "string", "description": "Upstream source for readonly posts. (e.g.,`google-drive`, `confluence`)" }, "author": { "type": "string", "description": "User email address. Defaults to current user" }, "description": { "type": "string" }, "contents": { "type": "array", "items": { "type": "object", "description": "An S3 Tempfile to attach to the post", "required": [ "file" ], "properties": { "source": { "type": "string", "description": "Original url of uploaded file" }, "description": { "type": "string", "description": "Centered caption to place below content" }, "file": { "type": "object", "required": [ "policy", "signature", "key", "access_key_id", "bucket" ], "properties": { "policy": { "type": "string" }, "signature": { "type": "string", "description": "The `x-amz-signature`" }, "key": { "type": "string" }, "access_key_id": { "type": "string", "description": "The first segment of the `x-amz-credential` path" }, "bucket": { "type": "string" } }, "description": "Response data from [S3 Tempfile](/api/documentation/doc/app/post-/s3/tempfile-filename--filename-)" } } } } }, "example": { "post_body": "", "public": false, "published": true, "title": "Attachment test", "description": "The attachment will be added to the body as [content||]", "read_only": true, "keyword_list": [ "external" ], "origin_url": "https://example.com/documents/attachment.jpg", "source": "example-service", "contents": [ { "source": "/tmp/attachment.jpg", "file": { "policy": "eyJleXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "signature": "7dXXXXXXXXXXXXXXXXXXXXXXXXX=", "key": "uploads/00000000-0000-0000-0000-000000000001/attachment.jpg", "access_key_id": "AKIXXXXXXXXXXXXXXXXXX", "bucket": "" } } ] } }, "user_object": { "type": "object", "properties": { "likes_count": { "type": "integer", "readOnly": "true" }, "followers_count": { "type": "integer", "readOnly": "true" }, "followed": { "type": "boolean", "readOnly": "true" }, "following_count": { "type": "integer", "readOnly": "true" }, "comments_count": { "type": "integer", "readOnly": "true" }, "community_external_id": { "type": "string", "format": "uuid" }, "views_count": { "type": "integer", "readOnly": "true" }, "email": { "type": "string" }, "preferred_language": { "type": "string" }, "role": { "type": "string" }, "active": { "type": "boolean" }, "first_login": { "type": "boolean" }, "id": { "type": "integer", "readOnly": "true" }, "posts_count": { "type": "integer", "readOnly": "true" }, "series_count": { "type": "integer", "readOnly": "true" }, "questions_count": { "type": "integer", "readOnly": "true" }, "answers_count": { "type": "integer", "readOnly": "true" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "bio": { "type": "string" }, "title": { "type": "string" }, "company": { "type": "string" }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "Keys are uuid identifiers as determined by the CustomField api. Values are arrays with one or more values; however, only custom fields with type 'multi-select' are allowed to have more than one value. For 'single-select' and 'multi-select' custom fields the values must be one of the allowed values as defined by the CustomField api.", "optional": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": "true" }, "updated_at": { "type": "string", "format": "date-time", "readOnly": "true" } }, "example": { "likes_count": 30, "followers_count": 2, "followed": true, "following_count": 4, "comments_count": 77, "views_count": 195, "email": "b.fiere@nowhere.com", "role": "author", "active": true, "id": 8123, "posts_count": 2, "series_count": 1, "questions_count": 7, "answers_count": 3, "first_name": "B", "last_name": "Fiere", "bio": "Founder", "title": "CEO", "company": "Fiere, Inc", "custom_fields": { "68ABCE4C-22E9-4B1F-8F00-C49D07CBD72E": [ "Executive Leadership" ], "4E7867CE-B8AE-43C0-8306-CD659085D990": [ "NE", "SW", "C" ] }, "roles_and_organizations": { "moderator": [ 1, 2, 3 ], "author": [ 4, 5 ] }, "created_at": "2018-11-19T17:45:33Z", "updated_at": "2018-11-19T17:45:33Z" } }, "user_post_object": { "type": "object", "properties": { "comments_count": { "type": "integer" }, "comments": { "type": "array", "items": { "type": "integer" } }, "organization_id": { "type": "integer" }, "id": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "public": { "type": "boolean" }, "published_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "followers": { "type": "array", "items": { "type": "users" } }, "liked": { "type": "boolean" }, "likes": { "type": "array", "items": { "type": "Likes" } }, "series": { "type": "array", "items": { "type": "posts" } }, "published": { "type": "boolean" }, "followers_count": { "type": "integer" }, "followed": { "type": "boolean" }, "likes_count": { "type": "integer" }, "categories_count": { "type": "integer" }, "keywords_count": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "integer" } }, "keywords": { "type": "array", "items": { "type": "integer" } }, "popularity": { "type": "integer" }, "views_count": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "contents_count": { "type": "integer" }, "series_count": { "type": "integer" }, "contents": { "type": "array", "items": { "type": "integer" } }, "author": { "type": "object", "properties": { "id": { "type": "integer" } } } } } }, "securitySchemes": { "session_auth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "This is a Bloomfire session token. See\n **[Authentication](/api/documentation)** on the Intro page for instructions\n on how to generate it.\n\n _When using the documentation portal, if you are logged into the application,\n `GET` requests will work but others will not without a session token._
\n _You can generate a session token on the Subscription Service **[Fetch session\n token](/api/documentation/doc/gatekeeper/get-/gatekeeper/session-token)** page.
\n Follow the instructions on that page to return here and set the header._\n\n To use the session token, enter it as `bloomfire-session-token\n SESSION_TOKEN`.
\n To use a bearer token, enter it as `Bearer BEARER_TOKEN`.\n

" } } }, "security": [ { "session_auth": [] } ], "tags": [ { "name": "Posts" }, { "name": "Semantic Search" }, { "name": "Drafts" }, { "name": "Users" }, { "name": "Organizations" }, { "name": "Groups" }, { "name": "Questions" }, { "name": "Answers" }, { "name": "Series" }, { "name": "Custom Fields" }, { "name": "Follow" }, { "name": "Comments" }, { "name": "Notifications" }, { "name": "Jobs" } ], "paths": { "/questions/{id}/answers": { "get": { "summary": "All Answers for a Question", "tags": [ "Answers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The ID for the question", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Successfully access an answer object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } } }, "post": { "summary": "Create an Answer to a Question", "tags": [ "Answers" ], "parameters": [ { "name": "id", "in": "path", "description": "ID of the question to be answered", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully posted an answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_answer_object" } } }, "required": true } } }, "/questions/{question_id}/answers/{answer_id}": { "get": { "summary": "A Single Answer for a Question", "tags": [ "Answers" ], "description": "To access a single answer for a question", "parameters": [ { "name": "question_id", "in": "path", "required": true, "description": "The ID for the question", "schema": { "type": "integer" } }, { "name": "answer_id", "in": "path", "description": "The ID for the answer", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully access an answer object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } } } }, "/answers/{answer_id}": { "get": { "summary": "A Single Answer", "tags": [ "Answers" ], "description": "To access a single answer for a question", "parameters": [ { "name": "answer_id", "in": "path", "required": true, "description": "The ID for the answer", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully access an answer object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } } }, "put": { "summary": "Accepting an Answer", "tags": [ "Answers" ], "description": "To accept an answer, use the PUT request for the appropriate answer id to change the accepted parameter.", "parameters": [ { "name": "answer_id", "in": "path", "required": true, "description": "The ID for the answer to be accepted", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully accept an answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/accept_answer_object" } } }, "description": "A boolean field to update an answer to be accepted" } } }, "/answers/{answer_id_to_update}": { "put": { "summary": "Updating Answers", "tags": [ "Answers" ], "description": "To update an answer, use the PUT method and pass the new answer text to the answer parameter \"short\".\n If the request is successful, the updated answer object will be returned.", "parameters": [ { "name": "answer_id_to_update", "in": "path", "required": true, "description": "The ID for the answer to be updated", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully updates an answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updated_answer_object" } } } } } }, "/{type}/{id}/comments": { "get": { "summary": "All Comments for a Contribution", "tags": [ "Comments" ], "description": "To access all comments on a post, question, or series", "parameters": [ { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "posts", "questions", "series" ] }, "required": true }, { "name": "id", "in": "path", "description": "The contribution id", "required": true, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Successfully access all comments on a particular question" } } }, "post": { "summary": "Create a Comment on a Contribution", "tags": [ "Comments" ], "description": "To create a comment on a post, question, or series", "parameters": [ { "name": "post_id", "in": "path", "description": "The post id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully create a new comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/comment_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "comment" ], "properties": { "comment": { "type": "string", "description": "The comment text" } } } } }, "required": true } } }, "/comments/{comment_id}": { "get": { "summary": "A Single Comment", "tags": [ "Comments" ], "description": "Access a single comment by appending the comment id to the path", "parameters": [ { "name": "comment_id", "in": "path", "description": "The comment id for the comment to be accessed", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully access a particular comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/comment_object" } } } } } }, "put": { "summary": "Update a Comment", "tags": [ "Comments" ], "description": "To update a comment, use the PUT request to pass the new comment parameter for the appropriate comment id.", "parameters": [ { "name": "comment_id", "in": "path", "description": "The comment id for the comment to be updated", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully update a comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/comment_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updated_comment_object" } } }, "description": "The updated comment text" } }, "delete": { "summary": "Delete a Comment", "tags": [ "Comments" ], "parameters": [ { "name": "id", "in": "path", "description": "The comment id for the comment to be deleted", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully delete a comment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/comment_object" } } } } } } }, "/custom_fields/{id}": { "get": { "summary": "Accessing a Custom Field", "tags": [ "Custom Fields" ], "description": "To access data for a Custom Field, insert the Custom Field id into the API request.", "parameters": [ { "name": "id", "in": "path", "format": "uuid", "required": true, "description": "Custom field id appended to the url", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accessing a Custom Field by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom_field_object" } } } } } }, "put": { "summary": "Create/Update a Custom Field", "tags": [ "Custom Fields" ], "description": "To create or update a Custom Field, insert the Custom Field id into the API request, and use a PUT.", "parameters": [ { "name": "id", "in": "path", "format": "uuid", "required": true, "description": "Custom Field id appended to the url. For new Custom Fields, provide a new UUID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Update Custom Field", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom_field_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom_field_object" } } } } }, "delete": { "summary": "Delete a Custom Field", "tags": [ "Custom Fields" ], "description": "To delete a Custom Field, insert the Custom Field id into the API request.", "parameters": [ { "name": "id", "in": "path", "format": "uuid", "required": true, "description": "Custom Field id appended to the url", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Delete a Custom Field by ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom_field_object" } } } } } } }, "/custom_fields": { "get": { "summary": "Accessing All Custom Fields", "tags": [ "Custom Fields" ], "description": "Custom fields allow administrators to provide additional profile fields to users in their account. Custom fields can be one of three types: text, single select, or multi select.", "responses": { "200": { "description": "Accessing active Custom Fields", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/custom_field_object" } } } } } } }, "/posts/{post_id}/drafts": { "get": { "summary": "Drafts", "tags": [ "Drafts" ], "description": "Returns a list drafts (versions) for a given post.\n\n**Note: This endpoint only returns published versions**\n\n### Using the list endpoint\n\nThere are two use cases for the draft list endpoint. \n\n1. Fetching all drafts — first example for `bloomfire-requested-fields`\n2. Checking for updates — second example \n\nWhen initially fetching draft information, the first example provides what\nshould be a reasonable set of data for audit and or content backup.\n\nAssuming that the initial export is store in a retrievable format, it can by\nupdated efficiently through the use of the `fingerprint` field. If the\n`fingerprint` is unchanged, the draft has not been modified.\n\nTherefore, to efficiently update exported drafts\n\n1. Fetch the list of draft ids and fingerprints\n2. Compare the fingerprint to your current export data.\n3. If the draft does not exist, or the fingerprint has changed, use the\n [\"A Draft\"](drafts/-id-) endpoint to fetch the updated contribution.\n### Requested Fields\n\nSome of the fields defined in the default (example) requested headers are\ncommunity dependent. Specifically, the following fields are affected by the\ncontent community settings (*Settings* -> *Settings* -> *Content*)\n\n#### Approver\n\nIf *Moderation* is not enabled, the `approver` will the same user as returned\nin the `contributor`.\n\n\n#### Content (attachment) fields\n\nThe `download` field returns a link to retrieve the original document uploaded\nas an attachment to a contribution.\n\nIf downloads are not enabled for a community the `download` field will return\nand empty hash. Additionally, if `Allow download prevention` is enabled, then\nattachment downloading may be disabled on individual contributions.\n\nMany attachment types are \"Previewable\" (e.g., PDF files) or are\npost-processed to create previewable documents. These are always\naccessible. For instance, *Microsoft Word* documents are converted to\nPDF. These documents can be retrieved through the `content_url`.\n\nIn either case, the URLs return will point to the file on S3.\n", "parameters": [ { "name": "post_id", "in": "path", "required": true, "description": "The id of the post whose drafts to retrieve", "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,description,preview_url,fingerprint,updated_at,approver(first_name,last_name,email),contributor(first_name,last_name,email),publish_note(body),post_body,contents(id,original_content_type,original_file_name,content_url,download(original))", "id,name,fingerprint,updated_at" ] }, "description": "" } ], "responses": { "200": { "description": "All drafts for a post", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/draft_object" } } } } } } } }, "/posts/{post_id}/drafts/{id}": { "get": { "summary": "A Draft", "tags": [ "Drafts" ], "description": "Returns a specific draft (version) for a given post.\n\n**Note: This endpoint only returns published versions**\n### Requested Fields\n\nSome of the fields defined in the default (example) requested headers are\ncommunity dependent. Specifically, the following fields are affected by the\ncontent community settings (*Settings* -> *Settings* -> *Content*)\n\n#### Approver\n\nIf *Moderation* is not enabled, the `approver` will the same user as returned\nin the `contributor`.\n\n\n#### Content (attachment) fields\n\nThe `download` field returns a link to retrieve the original document uploaded\nas an attachment to a contribution.\n\nIf downloads are not enabled for a community the `download` field will return\nand empty hash. Additionally, if `Allow download prevention` is enabled, then\nattachment downloading may be disabled on individual contributions.\n\nMany attachment types are \"Previewable\" (e.g., PDF files) or are\npost-processed to create previewable documents. These are always\naccessible. For instance, *Microsoft Word* documents are converted to\nPDF. These documents can be retrieved through the `content_url`.\n\nIn either case, the URLs return will point to the file on S3.\n", "parameters": [ { "name": "post_id", "in": "path", "required": true, "description": "The id of the post", "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "description": "The id of the draft", "schema": { "type": "string" } }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,description,preview_url,fingerprint,updated_at,approver(first_name,last_name,email),contributor(first_name,last_name,email),publish_note(body),post_body,contents(id,original_content_type,original_file_name,content_url,download(original))" ] }, "description": "" } ], "responses": { "200": { "description": "The current editable draft using `me`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/draft_object" } } } } } } }, "/groups": { "get": { "summary": "List Accessible Groups", "tags": [ "Groups" ], "description": "An group is a logical segment of Bloomfire community accessible by a subset of community users. See Communities and Groups for more details.", "responses": { "200": { "description": "Returns a JSON response of the list of groups data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/group_object" } } } } } } }, "/jobs": { "post": { "summary": "Creates a new BulkMemberExportJob", "tags": [ "Users" ], "description": "To create a new job, specify the job type and any arguments. Example job types\ninclude:\n\n* `BulkUpdateTags`\n* `BulkUpdateAuthors`\n* `BulkUpdateTaxa`\n* `BulkUpdatePublishStatus`\n* `BulkDeleteContribtions`\n* `BulkUpdateContributionThumbnail`\n* `BulkUpdateRolesAndAccess`\n* `BulkUpdateProfilePicture`\n* `BulkSendMessage`\n* `BulkResetPassword`\n* `BulkResendInvitationEmail`\n", "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_member_export_job_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_member_export_job_request_object" } } } } }, "get": { "summary": "Returns an array of jobs", "tags": [ "Jobs" ], "description": "Show all jobs for the current organization.", "responses": { "200": { "description": "Successfully returns an array of jobs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/job_object" } } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkMemberImportJob", "tags": [ "Users" ], "description": "Importing users via a BulkMemberImportJob requires a CSV file containing\none or more user records to update. The easiest way to get started is to do an\nexport of existing records, modify it, and then re-import it. However, the\nexport only contains a limited set of default columns:\n* `Email Address`\n* `First Name`\n* `Last Name`\n* `Title`\n* `Company`\n\nThe import allows for additional columns to be specified:\n\n* `Bio`\n* `Phone Number`\n* `Updated Email Address`\n* `Avatar URL`\n\nTo set custom fields add a column for each field with names that are prefixed\nwith 'CF: ', e.g.:\n\n* `CF: Department`\n* `CF: Region Manager`\n\nTo set multiple values for a multi-select custom field separate values with\ncommas, e.g. `Dept A,Dept B,Dept C`.\n\nIn addition to these columns there can be a column for each community/group for\nwhich the user has a membership; these columns can be used to change the role\nand/or deactivate a membership in that community/group. A few notes to\nconsider:\n\n* Any empty value in a cell is ignored rather than setting the value to empty.\n In this way you can selectively choose which values you wish to import.\n* To intentionally make a field empty/blank set the value to `\"\"` rather than\n leaving it empty.\n* The `Email Address` column is used to identify the user and thus can not be\n modified. In order to change a user's email set the `Updated Email Address`\n column.\n* Roles for a given community/group should be one of `learner`, `author`,\n `admin`, or `account_owner`. However, setting the value to `inactive` will\n deactivate that user's membership in the corresponding community or group.\n", "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_member_import_job_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_member_import_job_request_object" } } } } } }, "/jobs/{uuid}": { "delete": { "summary": "Kills a job", "tags": [ "Jobs" ], "description": "Stops a job using the UUID in the path. This will only work if the job has not been completed.", "parameters": [ { "name": "uuid", "in": "path", "type": "integer", "schema": { "$ref": "#/components/schemas/job_request_object" }, "description": "The uuid of the job to be killed", "required": true } ], "responses": { "200": { "description": "Successfully stops a job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/killed_job_object" } } } } } }, "get": { "summary": "Returns a specific job", "tags": [ "Jobs" ], "description": "Returns information on a single job.", "parameters": [ { "name": "uuid", "in": "path", "type": "integer", "schema": { "$ref": "#/components/schemas/job_request_object" }, "description": "The uuid of the active job to be retrieved", "required": true } ], "responses": { "200": { "description": "Successfully returns a specific job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/job_object" } } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateTags job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_tags_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_tags_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateAuthors job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_authors_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_authors_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateTaxa job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_taxa_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_taxa_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdatePublishStatus job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_publish_status_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_publish_status_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkDeleteContributions job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_delete_contributions_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_delete_contributions_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateContributionThumbnail job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_contribution_thumbnail_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_contribution_thumbnail_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateRolesAndAccess job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_roles_and_access_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_roles_and_access_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkUpdateProfilePicture job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_profile_picture_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_update_profile_picture_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkSendMessage job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_send_message_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_send_message_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkResetPassword job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_reset_password_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_reset_password_request_object" } } } } } }, "/jobs ": { "post": { "summary": "Creates a new BulkResendInvitationEmail job", "tags": [ "Jobs" ], "parameters": [], "responses": { "200": { "description": "Successfully creates a new job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_resend_invitation_email_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk_resend_invitation_email_request_object" } } } } } }, "/organization": { "get": { "summary": "Receiving Private Details", "tags": [ "Organizations" ], "description": "An organization is a single Bloomfire community. If you have a multiple communities, each will be treated as an organization.\n Each organization has public and private details.\n Public details are available to anyone who accesses the organization.\n Private details are available only to registered, logged-in users as appropriate to their user roles.", "parameters": [ { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "premium_settings,allow_public_content,authors_can_create_groups,available_languages,community_name,custom_terms_of_use,default_language,default_public_content,description,featured,groups_enabled,headline,hide_left_navigation_for_unathenticated,homepage_facet_communities_default,id,name,new_member_author,personal_feed_enabled,place_promo_above_featured_content,privacy_setting,show_headline_logged_in,support_email,time_zone" ] }, "description": "Example is fields requested by UI" } ], "responses": { "200": { "description": "Returns a JSON response of private organization data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/organization_object" } } } } } } }, "/posts": { "get": { "summary": "Posts", "tags": [ "Posts" ], "description": "A post is a contribution type created by a member or a group\n of members (co-authors) containing either text or media to be shared with\n the community. Media content can be a video, document, image, web\n resource (link), or virtually any other file type.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "All posts", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/post_object" } } } } } } }, "post": { "summary": "Create New Post", "tags": [ "Posts" ], "description": "Creating a post requires at minimum, a `title` and a `post_body` or `contents`.\n\n### Adding Attachments\n\nA post can contain an HTML body (`post_body`) and/or a set of attachments\n(`contents`) which will be displayed inline in the post. To display the\ncontents placeholders are appended to the post body in the form\n`[content||]` and the attachment are displayed inline at the\nlocation of the placeholder.\n\nWhen creating a post with new content (attachments), the placeholders\nwill be automatically appended to body of the post.\n\nTo position the attachment inline in a different location in the post body, the\npost will need to be [updated](/api/documentation/doc/app/put-/posts/-id-) so\nthat the content placeholder created on the initial upload can be repositioned\nwithin the `post_body`.\n\nTo add an attachment when creating or updating a post the following steps are\nrequired:\n\n1. Create an [S3\nTempfile](/api/documentation/doc/app/post-/s3/tempfile-filename--filename-)\nand upload the document to S3.\n2. Add a `contents[{file:}]` entry (as specified in the schema below) containing\nthe credentials returned from the temporary file upload data. When you post\nthe document, a content reference will be appended to the `post_body` and the\ncontent id will be returned in the results.\n\n**Note:** The `contents[{file:}]` credentials returned from the\n[S3 Tempfile](/api/documentation/doc/app/post-/s3/tempfile-filename--filename-)\nupload can only be referenced one time, as the tempfile is moved to the\ncorrect location by the back-end server when the post is created.\n\n### Preparing to Update\n\nTo update a document, you need the `id` of the document. If you are going to\nupdate the `post body`, it is helpful to have the content `id`s and an\nidentifying field such as the `original_file_name` or `source` for mapping\npreviously uploaded content to the original document.\n\nSee [Update Post](/api/documentation/doc/app/put-/posts/-id-) for additional\ndocumentation.\n\n### Tags\n\nTags are referenced through the `keyword` field on a post. Keywords can be\nadded or removed from a post by updating the `keyword_list` field in the post\nbody. They are case insensitive and normalized to lowercase. So adding a\nkeyword \"External\" or \"external\" will refer to the same `id`.\n", "parameters": [ { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "Example with pre-filled `bloomfire-requested-fields`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_post_response_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upload_post_object" } } }, "required": true, "description": "The data for the new post." } } }, "/posts/{id}": { "get": { "summary": "A Post", "tags": [ "Posts" ], "description": "To access data for a single post, insert the post id into the API request.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Specific post id appended to the url", "schema": { "type": "integer" } }, { "name": "format_for", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mcp" ] }, "description": "Optional rendering mode. When set to `mcp`, each content's `text_body` is replaced with the coalesced extracted text (audio transcript, document body, or raw text) used for semantic-search / MCP context, truncated to fit an LLM context window." }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "A Specific Post by Post ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } } }, "put": { "summary": "Update Post", "tags": [ "Posts" ], "description": "**NOTE:** All and only the fields passed in the JSON body are updated. Any\nblank fields sent will be blanked in the database. Fields that are not sent\nare not affected.'\n\n### Managing Attachments\n\nAppending new attachments to a post are the same as defined in the Adding\nAttachments section of the [Create New\nPost](/api/documentation/doc/app/post-/posts) endpoint.\n\nAs well as adding new content you can also update the caption (`description`)\nfor current content by id, for example:\n\n```json\n{\n \"contents\": [\n {\n \"id\": 42,\n \"description\": \"Life, the universe and everything\"\n }\n ]\n}\n```\n\nAs mentioned in [Create New Post](/api/documentation/doc/app/post-/posts),\nadding new attachments and positioning them inline is a two step process.\n\n1. Add new attachment. The placeholder will be appended to the `post body` and\nthe list of current attachments will be returned in the `contents` of the reply.\n2. Update the `post_body` with placeholders for the previous and new\nattachments inserted in appropriate locations.\n\nNote the following:\n\n- When the `contents[]` field is specified in the post body, any attachments\n not referenced by placeholder in the `post_body` field or by id in the\n `contents[]` field will be removed from the post.\n- Multiple new attachments can be added in a single update. \n- Inline content is wrapped in centered, relatively positioned spans, so\nwrapping text and content placeholders in paragraphs (`

`) or divs\n(`
`) is necessary to anchor them in the document.\n- Attachments are not deleted from the database if you remove them from the\n post body, so they can be re-added later as long as you know the content id.\n\n#### Best Practices\n\nThis section describes three use-cases for appending new attachments to a post\nin order of complexity.\n\n**A simple list of attachments**\n\nThis can be done with or without captions and only requires a single PUT.\nGiven the post body `

A list of images

\\n[content|1|]`, sending the\nfollowing payload:\n\n\n```json\n{\n \"contents\": [\n {\n \"description\": \"a new image\",\n \"source\": \"/tmp/new-image.jpg\",\n \"file\": {\n \"policy\": \"eyJleXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"signature\": \"7dXXXXXXXXXXXXXXXXXXXXXXXXX=\",\n \"key\": \"uploads/00000000-0000-0000-0000-000000000002/new-image.jpg\",\n \"access_key_id\": \"AKIXXXXXXXXXXXXXXXXXX\",\n \"bucket\": \"\"\n }\n }\n ]\n}\n```\n\nWill result in the post body `

A list of images

\\n[content|1|][content|2|]`.\nNote that not sending `{\"id\": 1}` in the payload would remove that content\nfrom the post body, resulting in `

A list of images

\\n[content|2|]`\n\n**A list of attachments with preamble text**\n\nGiven the post body `

An image

\\n[content|1|]`, sending the following\npayload:\n\n\n```json\n{\n \"post_body\": \"

An image

\\n[content|1|]

Another Image

\"\n \"contents\": [\n {\n \"description\": \"a new image\",\n \"source\": \"/tmp/new-image.jpg\",\n \"file\": {\n \"policy\": \"eyJleXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"signature\": \"7dXXXXXXXXXXXXXXXXXXXXXXXXX=\",\n \"key\": \"uploads/00000000-0000-0000-0000-000000000002/new-image.jpg\",\n \"access_key_id\": \"AKIXXXXXXXXXXXXXXXXXX\",\n \"bucket\": \"\"\n }\n }\n ]\n}\n```\nWill result in the post body\n `

An Image

\\n[content|1|]

Another Image

[content|2|]`\n\nHere, `{\"id\": 1}` is not needed in the content array because it is referenced\nby placeholder in the updated `post_body`.\n\n\n**Embedding images inline with surrounding text**\n\nIn this case you will need to first attach the content and then update the\npost body in a second update. Note that you will always want to include _all_\nthe content ids in the initial update to prevent the current placeholders from\nbeing removed from the post body before the following update.\n\nGiven the post body\n\n```html\n

A document

\n
\n

The following document

\n [content|1|]\n

should be read in its entirety

\n
\n```\n\nYou would do a two-step update to add more content with a similar structure.\n\n1. Add new content\n```json\n{\n \"contents\": [\n {\n \"id\": 1\n },\n {\n \"source\": \"/tmp/new-document.pdf\",\n \"file\": {\n \"policy\": \"eyJleXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"signature\": \"7dXXXXXXXXXXXXXXXXXXXXXXXXX=\",\n \"key\": \"uploads/00000000-0000-0000-0000-000000000002/new-document.pdf\",\n \"access_key_id\": \"AKIXXXXXXXXXXXXXXXXXX\",\n \"bucket\": \"\"\n }\n }\n ]\n}\n```\n2. Update the post body\n\n```json\n{\n \"post_body\": \"

A document

\\n
\\n

The following document

\\n[content|1|]\\n

should be read in its entirety

\\n
\\n

A document

\\n
\\n

This document

\\n[content|2|]\\n

can be skimmed at your leisure

\\n
\\n\"\n}\n```\n", "parameters": [ { "name": "id", "in": "path", "description": "The id of the post to update", "required": true, "schema": { "type": "integer" } }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "Feature a Post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updated_post_object" } } }, "required": true, "description": "All current attachments *must* be referenced in either the `post_body` or `contents` field provided or they will be removed from the post." } }, "delete": { "summary": "Delete a Post", "tags": [ "Posts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully delete a post", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } }, "404": { "description": "Post not found" } } } }, "/groups/{group_id}/posts": { "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The id of the group to scope the post to", "schema": { "type": "integer" } } ], "get": { "summary": "Group Posts", "tags": [ "Posts" ], "description": "Identical to `GET /posts`, but scoped to a group context.", "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" }, { "name": "format_for", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mcp" ] }, "description": "Optional rendering mode. When set to `mcp`, each content's `text_body` is replaced with the coalesced extracted text (audio transcript, document body, or raw text) used for semantic-search / MCP context, truncated to fit an LLM context window." }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "All posts within a Group", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/post_object" } } } } } } }, "post": { "summary": "Create New Group Post", "tags": [ "Posts" ], "description": "Identical to `POST /posts`, but scoped to a group context.", "parameters": [ { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "Example with pre-filled `bloomfire-requested-fields`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_post_response_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/upload_post_object" } } }, "required": true, "description": "The data for the new post." } } }, "/groups/{group_id}/posts/{id}": { "parameters": [ { "name": "group_id", "in": "path", "required": true, "description": "The id of the group to scope the post to", "schema": { "type": "integer" } }, { "name": "id", "in": "path", "required": true, "description": "Specific post id appended to the url", "schema": { "type": "integer" } }, { "name": "format_for", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "mcp" ] }, "description": "Optional rendering mode. When set to `mcp`, each content's `text_body` is replaced with the coalesced extracted text (audio transcript, document body, or raw text) used for semantic-search / MCP context, truncated to fit an LLM context window." }, { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "get": { "summary": "A Group Post", "tags": [ "Posts" ], "description": "Identical to `GET /posts/{id}`, but scoped to a group context.", "responses": { "200": { "description": "A Specific Post by Post ID within a Group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } } }, "put": { "summary": "Update Group Post", "tags": [ "Posts" ], "description": "Identical to `PUT /posts/{id}`, but scoped to a group context.", "parameters": [ { "name": "bloomfire-requested-fields", "in": "header", "schema": { "type": "string", "example": [ "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_file_name,source,job_progress,failure_message)", "id,name,url,description,published_at,updated_at,author(first_name,last_name,email),pending_approval,keywords(name),post_body,contents(id,original_content_type,original_file_name,content_url,type,source,text_body)" ] }, "description": "The second example should be used with `format_for=\"mcp\"`and will retrieve the extracted text of each attachment" } ], "responses": { "200": { "description": "Make a Post Public within a Group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/updated_post_object" } } }, "required": true, "description": "All current attachments *must* be referenced in either the `post_body` or `contents` field provided or they will be removed from the post." } }, "delete": { "summary": "Delete a Group Post", "tags": [ "Posts" ], "description": "Identical to `DELETE /posts/{id}`, but scoped to a group context.", "responses": { "200": { "description": "Successfully delete a post within a Group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } } } }, "/questions": { "get": { "summary": "All Questions", "tags": [ "Questions" ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Accessing a list of all questions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/question_object" } } } } } }, "post": { "summary": "Create a Question", "tags": [ "Questions" ], "description": "**NOTE**: The author id parameter is assigned\n automatically based on the session token.", "parameters": [], "responses": { "200": { "description": "Create a New Question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/question_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "The title of the question" } } } } }, "required": true } } }, "/questions/{id}": { "get": { "summary": "A Question", "tags": [ "Questions" ], "parameters": [ { "name": "id", "in": "path", "description": "Question id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Access to a single question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/question_object" } } } } } }, "put": { "summary": "Update a Question", "tags": [ "Questions" ], "description": "Fields to update should be submitted as JSON in the post body.\n\n **NOTE:** All and only the fields passed in the JSON body are updated.\n Any blank fields sent will be blanked in the database.\n Fields that are not sent are not affected.", "parameters": [ { "name": "id", "in": "path", "description": "The id of the question to update", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Setting a question to public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/question_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "question" ], "properties": { "question": { "type": "string", "description": "The title of the question" } } } } }, "required": true, "description": "Fields to update" } }, "delete": { "summary": "Delete a Question", "tags": [ "Questions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully delete a question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/question_object" } } } }, "404": { "description": "Question not found" } } } }, "/s3/tempfile?filename={filename}": { "post": { "summary": "Upload File to S3", "tags": [ "Posts" ], "description": "Bloomfire uploads are stored securely in Amazon S3. Direct-to-S3 uploads are\naccomplished via CORS (cross-origin-resource-sharing) POST requests to S3.\nThis process can be used wherever a large resource needs to be sent (post\ncontent, answer media, profile avatar, etc.). This step is used whenever a\nnew file needs to be uploaded.\n\nThe purpose of this request is to ask our web-server to create a new temporary\nfile and return the necessary **Pre-signed POST Request** so that you can\nmodify this tempfile directly in S3.\n\nThe newly created tempfile can be used to upload user avatars, post\nthumbnails, post main-content, etc. Tempfiles that are not used in a\nsubsequent API call are automatically deleted after 30 days.\n\nAfter receiving the S3 credentials, you should upload the file directly to\nS3. This document describes the form-fields required that correspond directly\nwith the credentials response received in the previous step. This is a\nstandard multi-part POST to Amazon’s S3 servers; this process is not\ncontrolled by Bloomfire.\n\n When creating your POST request for Amazon, send all the keys/values returned\nin the previous response’s `form_data` array followed by the file you are\nsending as a multi-part form post.\n\n### Resources\n- [Amazon\n Readme](https://github.com/aws/aws-sdk-js-v3/tree/main/packages/s3-presigned-post#readme)\n about presigned posts\n- Node.js typescript for uploading file to s3 and generating post `contents[]` entry\n ```javascript\n import { openAsBlob } from 'node:fs';\n\n export type S3Tempfile = {\n form_data: {\n acl: string;\n key: string;\n success_action_status: string;\n policy: string;\n 'x-amz-credential': string;\n 'x-amz-algorithm': string;\n 'x-amz-date': string;\n 'x-amz-security-token': string;\n 'x-amz-signature': string;\n };\n url: string;\n bucket: string;\n key: string;\n access_key_id: string;\n policy: string;\n signature: string;\n };\n\n /** Upload file to S3 using Presigned Post\n * @param file full path to `filename`\n * @param data S3Tempfile (parsed form_data response)\n * @returns 201 and xml response if successful\n */\n export async function upload(data: S3Tempfile, file: string) {\n const body = new FormData();\n\n Object.entries(data.form_data).forEach(([field, value]) => {\n body.append(field, value);\n });\n const blob = await openAsBlob(file);\n body.append('file', blob);\n\n const resp = await fetch(data.url, {\n method: 'POST',\n body,\n });\n\n if (resp.status !== +data.form_data.success_action_status) {\n const message = await resp.text();\n throw new Error(`status: ${resp.status}, message: ${message}`);\n }\n }\n\n export type ContentEntry = {\n source?: string;\n file: {\n policy: string;\n signature: string;\n key: string;\n access_key_id: string;\n bucket: string;\n };\n };\n\n /** Generate `file` entry for contents from tempfile data\n * @param data S3Tempfile (parsed form_data response)\n * @param source url for uploaded `file`\n * @returns post `file` entry for post create or update\n */\n export function contentEntry(\n data: S3Tempfile,\n source: string = '',\n ): ContentEntry {\n const { bucket, policy, key, signature, access_key_id } = data;\n\n return {\n source,\n file: {\n policy,\n signature,\n key,\n access_key_id,\n bucket,\n },\n };\n }\n```\n", "parameters": [ { "name": "filename", "in": "path", "description": "**Warning:** This filename _must_ end with the correct extension for its mime-type", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Create a tempfile with the file name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/s3_tempfile_object" } } } } } } }, "/semantic-search": { "get": { "summary": "UI Search Results", "tags": [ "Semantic Search" ], "description": "Full-featured semantic (vector + BM25 hybrid) search. Returns a paginated envelope including results, facets, totals, and query metadata. Each result contains a `type` and a lightweight `instance` object sourced from the search index. Thumbnails and author avatars are resolved from the database before the response is returned.", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" }, "required": true, "description": "The search query string." }, { "name": "types", "in": "query", "schema": { "type": "string", "enum": [ "post", "question", "article", "board", "series" ] }, "required": false, "description": "Limit by content type." }, { "name": "keywords", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Limit by tag. Comma separated list, *all values must match*." }, { "name": "order_by", "in": "query", "schema": { "type": "string", "enum": [ "relevant", "recent", "oldest", "recent_updated", "oldest_updated", "name" ] }, "required": true, "example": "relevant", "description": "Sort order. " }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": true, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": true, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Returns empty envelope when no results match", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_object" } } } } } } }, "/semantic-search/content": { "get": { "summary": "Content Search Results", "tags": [ "Semantic Search" ], "description": "Returns up to **10** enriched content results suitable for use as context by an AI assistant or MCP (Model Context Protocol) tool. Unlike the standard semantic search endpoint, this endpoint:\n\n- **Does not support pagination** — it always returns a fixed window of the top 10 highest-scoring results.\n- **Returns full content** — post bodies, file attachment metadata, and download URLs are included directly in the response rather than requiring a follow-up fetch.\n- **Inlines related matches** — when the search engine matched text inside a comment, answer, or board widget rather than the top-level content item, that nested content is included in the result alongside the parent item.\n\n### Result types\n\nEach entry in `results` has a `type` field indicating its shape:\n\n| `type` | Description |\n|------------|-------------|\n| `post` | A post contribution. Matched comments are inlined under `comments`. |\n| `question` | A question contribution. Matched answers are inlined under `answers`. The accepted answer is always included when any answer was matched. |\n| `article` | An external or enterprise-search article (e.g. SharePoint). |\n| `board` | A curated content board. Matched widgets are inlined under `widgets`. |\n| `series` | A curated series of posts and/or questions. Its published contributions are always inlined under `contributions`. |\n\n### Nested match fields\n\nThese fields only appear on a result when the search engine matched text inside a nested object (comment, answer, or widget) rather than — or in addition to — the top-level content:\n\n- `comments` — on `post` results\n- `answers` — on `question` results; always includes the accepted answer when one exists\n- `widgets` — on `board` results; either a `RichTextWidget` (with `post_body` and `contents`) or a `DocumentWidget` (with a single `content` object)\n\n`contributions` on `series` results is not a nested-match field — it always lists the series' published posts and questions (`type`, `id`, `url`, `name`), regardless of whether the query matched the series itself or one of its contributions.\n\n### Authentication\n\nThis endpoint requires an authenticated session. Public (unauthenticated) requests will receive results scoped to publicly visible content only.\n\n### Query parameters\n\nAccepts the same query parameters as `GET /semantic-search`:\n\n| Parameter | Type | Description |\n|-------------|---------|-------------|\n| `query` | string | **Required.** The search query string. |\n| `types` | string | Comma-separated content types to filter by: `post`, `question`, `article`, `board`, `series`. |\n| `keywords` | string | Comma-separated keyword names to filter by. |\n| `authors_ids` | string | Comma-separated membership IDs to filter by author. |\n| `order_by` | string | Sort order. One of `relevant` (default), `recent`, `oldest`, `recent_updated`, `oldest_updated`, `name`. |\n", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" }, "required": true, "description": "The search query string." }, { "name": "types", "in": "query", "schema": { "type": "string", "enum": [ "post", "question", "article", "board", "series" ] }, "required": false, "description": "Limit by content type." }, { "name": "keywords", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Limit by tag. Comma separated list, *all values must match*." }, { "name": "order_by", "in": "query", "schema": { "type": "string", "enum": [ "relevant", "recent", "oldest", "recent_updated", "oldest_updated", "name" ] }, "required": false, "example": "", "description": "Sort order. Defaults to `relevant`." } ], "responses": { "200": { "description": "Returns an empty array when the search index returns no matches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/mcp_content_response_object" } } } } } } }, "/semantic-search/cross-community": { "get": { "summary": "Cross-Community Search", "tags": [ "Semantic Search" ], "description": "Returns a count of matching results per community that the authenticated user has access to (excluding the current community). Useful for surfacing content from linked communities without fetching full results. Requires an authenticated session.", "parameters": [ { "name": "query", "in": "query", "schema": { "type": "string" }, "required": true, "description": "The search query string." }, { "name": "types", "in": "query", "schema": { "type": "string", "enum": [ "post", "question", "article", "board", "series" ] }, "required": false, "description": "Limit by content type." }, { "name": "keywords", "in": "query", "schema": { "type": "string" }, "required": false, "description": "Limit by tag. Comma separated list, *all values must match*." }, { "name": "order_by", "in": "query", "schema": { "type": "string", "enum": [ "relevant", "recent", "oldest", "recent_updated", "oldest_updated", "name" ] }, "required": true, "example": "relevant", "description": "Sort order. " } ], "responses": { "200": { "description": "Returns a facets envelope with per-community match counts", "content": { "application/json": { "schema": { "type": "object", "properties": { "facets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "display_name": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "count": { "type": "integer" }, "organization": { "type": "object", "properties": { "organization_url": { "type": "string" }, "logo_square_url": { "type": "string" } } } } } } } } } } } } } }, "401": { "description": "Requires authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/series": { "get": { "summary": "All Series", "tags": [ "Series" ], "parameters": [ { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Successfully returns an array of series objects for an organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/series_object" } } } } } }, "post": { "summary": "Create a Series", "tags": [ "Series" ], "description": "To create a series, use the contributions field to supply an array of composite ids of posts and questions, as well as the name field.\n Ex: [\"post_54\", \"question_13\", \"post_12\"]", "parameters": [], "responses": { "200": { "description": "Successfully create a new series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/series_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_series_object" } } }, "required": true, "description": "The name of the series" } } }, "/series/{id}": { "get": { "summary": "A Single Series", "tags": [ "Series" ], "description": "To access data for a single series, append the series id onto the API request.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The id for a series", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully returns a series object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/series_object" } } } } } }, "delete": { "summary": "Delete a Series", "tags": [ "Series" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully delete a series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/series_object" } } } }, "404": { "description": "Series not found" } } }, "put": { "summary": "Make a Series Public", "tags": [ "Series" ], "description": "To make a series public, use the PUT method to pass the public parameter for the appropriate series id.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the series to be made public", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successfully makes a series public", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/series_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "pubilc" ], "properties": { "public": { "type": "boolean" } } } } }, "required": true } } }, "/users": { "post": { "summary": "Creates or Updates a User Using Email Address", "tags": [ "Users" ], "description": "When a new user is created in Bloomfire, only the email field is required, but\n other parameters may optionally be supplied. By default, users created via the\n API are not sent a welcome email from the Bloomfire system. If you would like a\n welcome email to be sent, please include a send_welcome_email field and set it\n true. The email field is private for users and is not returned in public requests.\n Other fields are considered public if the Allow Public Content setting is turned on\n in Bloomfire > Configure > Settings > Public Content. If a user already exists in\n any of your communities, you can use the same request to update the user. When a\n user is updated in Bloomfire, only the email field is required, but other parameters\n may optionally be supplied. If your user exists, but isn’t yet a member of the\n subcommunity you are currently accessing the API as, making this request will\n automatically link the user to this community.
\n Please be cautious when using this method to update. It updates the user\n with the fields you send in your request. Any blank fields sent will be blanked\n in the user object. Fields that are not sent are not affected.\n Only send the fields you intend to update along with the email field used to\n identify the user object.", "parameters": [], "responses": { "201": { "description": "Create a user by sending the user email and the (optional) role parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_object" } } } }, "400": { "description": "Does not create a user when the email is not provided." } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_object" } } }, "required": true, "description": "A user is a person that has access to a master organization and all related subcommunity organizations. The list of accessible fields is shown in the example value, as well as the model view." } } }, "/users/{membership_id}": { "get": { "summary": "User Information", "tags": [ "Users" ], "description": "Retrieve Information about Bloomfire users.\n\n*Note that the `id` returned in all user results is the `membership_id` for the current community, not the `user_id` (which is also returned.)*", "parameters": [ { "name": "membership_id", "in": "path", "description": "Optional, limit results to a single user. *Do not set offset!*", "required": true, "schema": { "type": "integer" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Accessing all users", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_object" } } } } } }, "put": { "summary": "Update User Data", "tags": [ "Users" ], "description": "Fields to update should be submitted as JSON in the post body.\n\n **NOTE:** All and only the fields passed in the JSON body are updated.\n Any blank fields sent will be blanked in the database.\n Fields that are not sent are not affected.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Update a user's email, title, company and role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_object" } } } }, "401": { "description": "Cannot update a user's role without administrative privileges." } }, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user_object" } } } } } }, "/users/{membership_id}/{type}": { "get": { "summary": "User generated content", "tags": [ "Users" ], "description": "Retrieve a specific user's generated content", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "following", "followers", "posts", "questions", "answers", "comments", "series" ] }, "description": "Optional, limit results to `type`", "required": true }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "example": "0", "required": false, "description": "Pagination parameter, number of records to skip" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1 }, "example": 20, "required": false, "description": "Pagination parameter, maximum number of records to return" } ], "responses": { "200": { "description": "Access to a single user's posts by appending the /posts field to request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } } } }, "/users/{membership_id}/following/{type}": { "post": { "summary": "Follow", "tags": [ "Follow" ], "description": "Add a user to the followers of an object. Returns the object.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "posts", "questions", "series", "boards", "users" ] }, "description": "Object type to follow", "required": true } ], "responses": { "200": { "description": "Successful update to followed posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "membership_id" ], "properties": { "membership_id": { "type": "integer", "description": "object_id" } } } } }, "required": true, "description": "The id of the object" } } }, "/users/{membership_id}/following/{type}/{id}": { "delete": { "summary": "Unfollow", "tags": [ "Follow" ], "description": "Remove user from the followers of an object. Returns the object.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "type", "in": "path", "schema": { "type": "string", "enum": [ "posts", "questions", "series", "boards", "users" ] }, "description": "Object type to unfollow", "required": true }, { "name": "id", "in": "path", "required": true, "description": "The id of the object to unfollow", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful update to followed posts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/post_object" } } } } } } }, "/users/{membership_id}/notifications": { "get": { "summary": "Get User Notifications", "tags": [ "Notifications" ], "description": "Get all (non-feed) in-app notifications for the given user.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "read_state_equals", "in": "query", "schema": { "type": "string", "enum": [ "unviewed", "unread", "viewed", "clicked" ] }, "description": "Only display notifications in give state." } ], "responses": { "200": { "description": "Accessing all notifications", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification_object" } } } } } } }, "/users/{membership_id}/notifications/{id}": { "put": { "summary": "Mark Notification as Viewed", "tags": [ "Notifications" ], "description": "Mark a given user notification as viewed.", "parameters": [ { "name": "membership_id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "id", "in": "path", "description": "The notification id", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Notification viewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification_object" } } } } }, "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "read_state": { "type": "string", "enum": [ "viewed" ] } } } } }, "required": true } } } } }