What Can GraphQL Mutations do for AnnounceKit?

GraphQL Queries are special commands for you to run in our IDE.

These special commands are used to change information and settings for your projects.

While all of the options for mutations can be enabled through our dashboard, GraphQL is mainly used by developers for API development at a fast pace.

How to use these mutations?

Below is a documentation for all of the mutations that can be run in our GraphQL IDE, along with their descriptions, arguments, what the mutation will return, fields within the mutations, and a code example.

Arguments are purple fields below the mutations, and while some of them are optional, the most important ones are required arguments. Without them, the mutation will not work.

Return Type is an explanation of what the mutation will return in the code, a.k.a. what it will change in a project.

Fields in mutations are yellow fields to be filled with information you want to change for that mutation. For example;

saveLabel is a mutation for creating and saving a label in your project.

project_id: ID!

label_id: ID

name: String!

color: String! are arguments you will provide to start the mutation. While some are optional, important fields like “project_id” are required so that the mutation can know which project it will save the label for.

Label is the field with information and details about the label you want to create for your project. As you can see, an ID, name, and color is required for your label to be created.Arguments are subfields for queries, and while some arguments among queries are optional, make sure to complete the required arguments, as without them, you cannot run the queries.

Each of these mutations below is used by going into our IDE located here.

Project and Integrations

saveProject Mutation

Description: Saves or updates a project.

Arguments:

project_id: ID of the project (optional).
name: Name of the project.
website: Website URL of the project.
image_id: ID of the project image.
favicon_id: ID of the project favicon.
is_authors_listed: Boolean indicating whether authors are listed.
is_whitelabel: Boolean indicating whether the project is whitelabeled.
is_subscribable: Boolean indicating whether the project is subscribable.
is_slack_subscribable: Boolean indicating whether Slack subscription is enabled.
is_feedback_enabled: Boolean indicating whether feedback is enabled.
ga_property: Google Analytics property ID.
privacy_policy_url: URL of the privacy policy.
locale: Locale of the project.
company_role: Role of the company.
company_size: Size of the company.
hear_about_us: Source of how the project was heard about.

Return Type: Returns the saved/updated project information.

Project Fields:

id: ID of the project.
encodedId: Encoded ID of the project.
name: Name of the project.
slug: Slug of the project.
website: Website URL of the project.
is_authors_listed: Boolean indicating whether authors are listed.
is_whitelabel: Boolean indicating whether the project is whitelabeled.
is_subscribable: Boolean indicating whether the project is subscribable.
is_slack_subscribable: Boolean indicating whether Slack subscription is enabled.
is_feedback_enabled: Boolean indicating whether feedback is enabled.
is_demo: Boolean indicating whether the project is a demo.
is_readonly: Boolean indicating whether the project is read-only.
image_id: ID of the project image.
favicon_id: ID of the project favicon.
image: Image associated with the project.
created_at: Date when the project was created.
ga_property: Google Analytics property ID.
privacy_policy_url: URL of the privacy policy.
members: List of project members.
invites: List of project invites.
labels: List of project labels.
statuses: List of project statuses.
billing_info: Billing information of the project.
subscription: Subscription information of the project.
avatar: Avatar associated with the project.
favicon: Favicon associated with the project.
plan: Plan associated with the project.
locale: Locale of the project.
locales: List of project locales.
feeds: List of project feeds.
integrations: List of project integrations.
analytics: Analytics information for the project.
usesNewFeedHostname: Boolean indicating whether the project uses a new feed hostname.
payment_gateway: Payment gateway used by the project.
trial_until: Date until which the project is on trial.
metadata: Additional metadata associated with the project as a JSON object.
widget: Widget associated with the project.

mutation

{

saveProject
"variables": {
"project_id": "12345",
"name": "Project Name",
"website": "https://www.example.com",
"image_id": "imageId",
"favicon_id": "faviconId",
"is_authors_listed": true,
"is_whitelabel": false,
"is_subscribable": true,
"is_slack_subscribable": true,
"is_feedback_enabled": true,
"ga_property": "GA-123456",
"privacy_policy_url": "https://www.example.com/privacy-policy",
"locale": "en",
"company_role": "Developer",
"company_size": "Small",
"hear_about_us": "Social Media"
}

deleteProject

Description: Deletes a project.

Arguments:

project_id (required): ID of the project to be deleted.

Return Type: Returns the result of the deletion operation.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

Example:

{
"mutation": "deleteProject",
"variables": {
"project_id": "12345"
}
}

addProjectLocale

Description: Adds a locale to a specific project.

Arguments:

project_id (required): ID of the project to which the locale is being added.
locale_id (required): ID of the locale to be added.

Return Type: Returns the updated project.

{
"mutation": "addProjectLocale",
"variables": {
"project_id": "12345",
"locale_id": "54321"
}
}

removeProjectLocale

Description: Removes a locale from a specific project.

Arguments:

project_id (required): ID of the project from which the locale is being removed.
locale_id (required): ID of the locale to be removed.

Return Type: Returns the updated project.

{
"mutation": "removeProjectLocale",
"variables": {
"project_id": "12345",
"locale_id": "54321"
}
}

saveProjectLocale

Description: Saves locale overrides for a specific project and locale.

Arguments:

project_id (required): ID of the project for which the locale overrides are being saved.
locale_id (required): ID of the locale for which the overrides are being saved.
overrides (required): Array of locale entry inputs representing the overrides.

Return Type: Returns the saved project locale.

ProjectLocale Fields:

id: ID of the project locale.
project_id: ID of the associated project.
locale_id: ID of the associated locale.
overrides: Array of locale entries representing the overrides.
project: Associated project.
locale: Associated locale.

{
"mutation": "saveProjectLocale",
"variables": {
"project_id": "12345",
"locale_id": "54321",
"overrides": [
{
"key": "welcome_message",
"value": "Hello!"
},
{
"key": "error_message",
"value": "An error occurred."
}
]
}
}

createDemoProject

Description: Creates a demo project.

Arguments:

project_id (required): ID of the project to be created as a demo project.

Return Type: Returns a boolean indicating the success of creating the demo project.

Example:

{
"mutation": "createDemoProject",
"variables": {
"project_id": "12345"
}
}

generateProductDetails

Description: Creates the product details of a project .

Arguments:

project_id (required): ID of the project to generate the project details w,th.
url (required): URL of the project to be used to create a user persona and project details

Return Type: Returns the user persona and product description based on the project URL.

Example:

mutation

{

generateProductDetails(project_id:1234,url:"https://www.google.com/") {

user_persona

url

}

saveProjectDetails

Description: Saves the product details of a project.

Arguments:

project_id (required): ID of the project to generate the project details w,th.
url (required): URL of the project to be used to create a user persona and project details
description (required): Description of the project used to save project details.
user_persona (required): Description of the user persona of the project details

Return Type: Saves the user persona and the descrpition as a project detail.

Example:

mutation {

saveProjectDetails(project_id: "123456", user_persona: "PERSONA", description: "DESCRIPTION") {

}

importHeadway

Description: Imports data from Headway into a project.

Arguments:

project_id (required): ID of the project to import data into.
url (required): URL of the Headway data to import.
draft (optional): Boolean indicating whether to import the data as a draft.

Return Type: Returns a Result object.

Example:

{
"mutation": "importHeadway",
"variables": {
"project_id": "project123",
"url": "https://example.com/headway-data",
"draft": true
}
}

importBeamer

Description: Imports data from Beamer into a project.

Arguments:

project_id (required): ID of the project to import data into.
token (required): Beamer token for authentication.
draft (optional): Boolean indicating whether to import the data as a draft.

Return Type: Returns a Result object.

Example:

{
"mutation": "importBeamer",
"variables": {
"project_id": "project123",
"token": "beamer-token-123",
"draft": true
}
}

importGitHub

Description: Imports data from GitHub into a project.

Arguments:

project_id (required): ID of the project to import data into.
url (required): URL of the GitHub data to import.
continuous (optional): Boolean indicating whether to enable continuous import.
draft (optional): Boolean indicating whether to import the data as a draft.

Return Type: Returns a Result object.

Example:

{
"mutation": "importGitHub",
"variables": {
"project_id": "project123",
"url": "https://github.com/example/repository",
"continuous": true,
"draft": true
}
}

importReleaseNotes

Description: Imports release notes into a project.

Arguments:

project_id (required): ID of the project to import release notes into.
url (required): URL of the release notes to import.
draft (optional): Boolean indicating whether to import the release notes as a draft.

Return Type: Returns a Result object.

Example:

{
"mutation": "importReleaseNotes",
"variables": {
"project_id": "project123",
"url": "https://example.com/release-notes",
"draft": true
}
}

importNoticeable

Description: Imports data from Noticeable into a project.

Arguments:

project_id (required): ID of the project to import data into.
url (required): URL of the Noticeable data to import.
draft (optional): Boolean indicating whether to import the data as a draft.

Return Type: Returns a Result object.

Example:

{
"mutation": "importNoticeable",
"variables": {
"project_id": "project123",
"url": "https://example.com/noticeable-data",
"draft": true
}
}

stopImport

Description: Stops an ongoing import process.

Arguments:

project_id (required): ID of the project associated with the import process.
import_id (required): ID of the import process to stop.

Return Type: Returns an Import object representing the stopped import process.

Import Fields

Fields:

id (required): ID of the import process.
project_id (required): ID of the project associated with the import process.
user_id (required): ID of the user who initiated the import process.
status (required): Current status of the import process.
source (required): Source of the imported data.
created_at (required): Date and time when the import process was initiated.
is_continuous (required): Indicates whether the import process is continuous.
message (required): Message providing additional information about the import process.

Example:

{
"mutation": "stopImport",
"variables": {
"project_id": "project123",
"import_id": "import456"
}
}

saveSamlConfig

Description: Saves the SAML configuration for a project.

Arguments:

project_id (required): ID of the project to save the SAML configuration for.
login_url (optional): SAML login URL for the project.
certificate (optional): SAML certificate for the project.

Return Type: Returns a SAMLConfig object representing the saved SAML configuration.

SAMLConfig Fields

Fields:

id (required): ID of the SAML configuration.
project_id (required): ID of the project associated with the SAML configuration.
route (required): SAML route for the project.
login_url (optional): SAML login URL for the project.
certificate (optional): SAML certificate for the project.
domain (required): SAML domain for the project.
is_domain_verified (required): Indicates whether the SAML domain has been verified.
verify_token (required): Verification token for the SAML domain.

Example:

{
"mutation": "saveSamlConfig",
"variables": {
"project_id": "project123",
"login_url": "https://example.com/saml/login",
"certificate": "saml-certificate-123"
}
}

verifySamlDomain

Description: Verifies the SAML domain for a project.

Arguments:

project_id (required): ID of the project to verify the SAML domain for.
domain (required): SAML domain to be verified.

Return Type: Returns a SAMLConfig object representing the SAML configuration with the verified domain.

Example:

{
"mutation": "verifySamlDomain",
"variables": {
"project_id": "project123",
"domain": "example.com"
}
}

updateIntegration

Description: Updates an integration with new options.

Arguments:

integration_id (required): ID of the integration to be updated.
options (required): JSON object representing the new options for the integration.

Return Type: Returns a boolean indicating the success of updating the integration.

Example:

{
"mutation": "updateIntegration",
"variables": {
"integration_id": "12345",
"options": {}
}
}

uninstallIntegration

Description: Uninstalls an integration.

Arguments:

integration_id (required): ID of the integration to be uninstalled.

Return Type: Returns a result indicating the success of uninstalling the integration.

Example:

{
"mutation": "uninstallIntegration",
"variables": {
"integration_id": "12345"
}
}

getJiraConfigurations

Description: Retrieves Jira configurations based on the provided query.

Arguments:

integration_id (required): ID of the integration.
query (required): Query string to search for Jira configurations.

Return Type: Returns a JiraConfiguration object.

Example:

{
"mutation": "getJiraConfigurations",
"variables": {
"integration_id": "12345",
"query": "example"
}
}

searchForReporter

Description: Searches for a reporter in the integration based on the provided query.

Arguments:

integration_id (required): ID of the integration.
query (required): Query string to search for reporters.

Return Type: Returns an array of ReportersResponse objects.

Example:

{
"mutation": "searchForReporter",
"variables": {
"integration_id": "12345",
"query": "John Doe"
}
}

sendJiraTicket

Description: Sends a Jira ticket for a feature request.

Arguments:

feature_request_id (required): ID of the feature request to create a Jira ticket for.

Return Type: Returns a boolean indicating the success of sending the Jira ticket.

Example:

{
"mutation": "sendJiraTicket",
"variables": {
"feature_request_id": "feature123"
}
}

getJiraTicket

Description: Retrieves the Jira ticket information for a feature request.

Arguments:

feature_request_id (required): ID of the feature request to retrieve the Jira ticket information for.

Return Type: Returns a GetJiraTicketResponse object with the ticket field.

Example:

{
"mutation": "getJiraTicket",
"variables": {
"feature_request_id": "feature123"
}
}

Billing and Subscriptions

saveBillingInfo

Description: Saves billing information for a project.

Arguments:

project_id (required): ID of the project for which billing information is being saved.
name: Name associated with the billing information.
email: Email address associated with the billing information.
address: Address associated with the billing information.
country: Country associated with the billing information.
state: State associated with the billing information.
card_token: Token representing the payment card.
zip_code: Zip code associated with the billing information.

Return Type: Returns the saved billing information.

BillingInfo Fields:

id: ID of the billing information.
project_id: ID of the associated project.
name: Name associated with the billing information.
email: Email address associated with the billing information.
address: Address associated with the billing information.
country: Country associated with the billing information.
state: State associated with the billing information.
card_summary: Summary of the payment card.

Example:

{
"mutation": "saveBillingInfo",
"variables": {
"project_id": "12345",
"name": "John Doe",
"email": "[email protected]",
"address": "123 Street",
"country": "US",
"state": "CA",
"card_token": "token123",
"zip_code": "12345"
}
}

beginPaddleSubscription

Description: Initiates a subscription using Paddle for a project.

Arguments:

project_id (required): ID of the project for which the subscription is being initiated.
plan_id: ID of the subscription plan.

Return Type: Returns the result of initiating the Paddle subscription.

BeginPaddleSubscriptionResult Fields:

state: State of the Paddle subscription.
metadata: Additional metadata associated with the subscription as a JSON object.

Example:

{
"mutation": "beginPaddleSubscription",
"variables": {
"project_id": "12345",
"plan_id": "plan123"
}
}

ensurePaddleSubscription

Description: Ensures that the Paddle subscription is active for a project.

Arguments:

project_id (required): ID of the project for which the subscription is being ensured.
subscription_id (required): ID of the subscription to ensure.

Return Type: Returns the subscription information.

Subscription Fields:

id: ID of the subscription.
started_at: Date when the subscription started.
period_started_at: Date when the subscription period started.
period_ending_at: Date when the subscription period ends.
status: Status of the subscription.
metadata: Additional metadata associated with the subscription as a JSON object.

Example:

{
"mutation": "ensurePaddleSubscription",
"variables": {
"project_id": "12345",
"subscription_id": "sub123"
}
}

ensureSubscription

Description: Ensures that a subscription is active for a project.

Arguments:

project_id (required): ID of the project for which the subscription is being ensured.
coupon: Coupon to apply to the subscription (optional).
plan_id (required): ID of the plan to ensure the subscription.

Return Type: Returns the subscription information.

Subscription Fields:

id: ID of the subscription.
started_at: Date when the subscription started.
period_started_at: Date when the subscription period started.
period_ending_at: Date when the subscription period ends.
status: Status of the subscription.
metadata: Additional metadata associated with the subscription as a JSON object.

Example:

{
"mutation": "ensureSubscription",
"variables": {
"project_id": "12345",
"coupon": "coupon123",
"plan_id": "plan123"
}
}

cancelSubscription

Description: Cancels the subscription for a project.

Arguments:

project_id (required): ID of the project for which the subscription is being canceled.

Return Type: Returns the result of canceling the subscription.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

{
"mutation": "cancelSubscription",
"variables": {
"project_id": "12345"
}
}

Project Members and Authentication

addProjectMember

Description: Adds a member to a specific project.

Arguments:

project_id (required): ID of the project to which the member is being added.
email (required): Email address of the member.
member_role: Role of the member (default: "owner").

Return Type: Returns the invite.

Invite Fields:

id: ID of the invite.
project_id: ID of the associated project.
email: Email address of the invitee.
role: Role of the invitee.

{
"mutation": "addProjectMember",
"variables": {
"project_id": "12345",
"email": "[email protected]",
"member_role": "owner"
}
}

removeProjectMember

Description: Removes a member from a specific project.

Arguments:

project_id (required): ID of the project from which the member is being removed.
user_id (required): ID of the user to be removed.

Return Type: Returns a boolean indicating the success of removing the member.

{
"mutation": "removeProjectMember",
"variables": {
"project_id": "project123",
"user_id": "user123"
}
}

removeProjectInvite

Description: Removes an invite from a specific project.

Arguments:

project_id (required): ID of the project from which the invite is being removed.
invite_id (required): ID of the invite to be removed.

Return Type: Returns a boolean indicating the success of removing the invite.

{
"mutation": "removeProjectInvite",
"variables": {
"project_id": "project123",
"invite_id": "invite123"
}
}

createTotpConfig

Description: Creates a Time-based One-Time Password (TOTP) configuration.

Return Type: Returns the TOTP configuration.

TOTPConfig Fields:

id: ID of the TOTP configuration.
user_id: ID of the user associated with the TOTP configuration.
qr_code: QR code for TOTP setup.
recovery_codes: List of recovery codes for TOTP.

{
"mutation": "createTotpConfig"
}

removeTotpConfig

Description: Removes the Time-based One-Time Password (TOTP) configuration.

Return Type: Returns the result of removing the TOTP configuration.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

{
"mutation": "removeTotpConfig"
}

activateTotpConfig

Description: Activates the Time-based One-Time Password (TOTP) configuration using the provided token.

Arguments:

token (required): Token for activating the TOTP configuration.

Return Type: Returns the activated TOTP configuration.

{
"mutation": "activateTotpConfig",
"variables": {
"token": "activationToken123"
}
}

User Management

saveUser

Description: Saves user information.

Arguments:

email: Email address of the user.
display_name: Display name of the user.
title: Title of the user.
password: Password of the user.
active_project_id: ID of the active project.
image_id: ID of the user's image.
is_unsubs: Boolean indicating whether the user has unsubscribed.

Return Type: Returns the saved user information.

User Fields:

id: ID of the user.
hash: Hash associated with the user.
email: Email address of the user.
display_name: Display name of the user.
title: Title of the user.
created_at: Date when the user was created.
image_id: ID of the user's image.
image: Image associated with the user.
active_project: Active project of the user.
memberships: Memberships associated with the user.
avatar: Avatar URL of the user.
is_validated: Boolean indicating whether the user is validated.
is_totp_enabled: Boolean indicating whether Time-based One-Time Password (TOTP) is enabled for the user.
is_unsubs: Boolean indicating whether the user has unsubscribed.

{
"mutation": "saveUser",
"variables": {
"email": "[email protected]",
"display_name": "John Doe",
"title": "Developer",
"password": "password123",
"active_project_id": "12345",
"image_id": "image123",
"is_unsubs": false
}
}

createUser

Description: Creates a new user.

Arguments:

email: Email address of the user.
display_name: Display name of the user.
title: Title of the user.
password: Password of the user.
recaptcha_token (required): Token for reCAPTCHA validation.
referrals: Referral information as a JSON object.

User Fields:

id: ID of the user.
hash: Hash associated with the user.
email: Email address of the user.
display_name: Display name of the user.
title: Title of the user.
created_at: Date when the user was created.
image_id: ID of the user's image.
image: Image associated with the user.
active_project: Active project of the user.
memberships: Memberships associated with the user.
avatar: Avatar URL of the user.
is_validated: Boolean indicating whether the user is validated.
is_totp_enabled: Boolean indicating whether Time-based One-Time Password (TOTP) is enabled for the user.
is_unsubs: Boolean indicating whether the user has unsubscribed.

mutation
{
saveUser(email:"[email protected]") {
id
title
}
}

acceptInvite

Description: Accepts an invitation using the provided token.

Arguments:

token (required): Token of the invitation.

Return Type: Returns a list of strings.

{
"mutation": "acceptInvite",
"variables": {
"token": "inviteToken123"
}
}

verifyByMail

Description: Accepts an invitation using the provided token.

Arguments:

token (required): Token of the invitation.

Return Type: Returns a list of strings.

{
"mutation": "verifyByMail",
"variables": {
"token": "verificationToken123"
}
}

recoverByMail

Description: Initiates a password recovery process using the provided token.

Arguments:

token (required): Token for password recovery.

Return Type: Returns a list of strings.

{
"mutation": "recoverByMail",
"variables": {
"token": "recoveryToken123"
}
}

resendValidationMail

Description: Resends the validation email to the user.

Return Type: Returns the result of resending the validation email.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

{
"mutation": "resendValidationMail"
}

deleteAllExternalUsers

Description: Deletes all external users within a project.

Arguments:

project_id (required): ID of the project from which all external users are being deleted.

Return Type: Returns the result of the deletion operation.

Result Fields:

type: Result type indicating success or failure.
message: Result message providing additional information.

Example:

{
"mutation": "deleteAllExternalUsers",
"variables": {
"project_id": "12345"
}
}

importExternalUsers

Description: Imports external users into a project.

Arguments:

input (required): Object containing the input fields for importing external users.

The input object should have the following fields:

project_id (required): ID of the project to import the external users into.
users (required): Array of ImportExternalUsersInputUserInput objects representing the external users to import.

Each ImportExternalUsersInputUserInput object should have the following fields:

id (required): ID of the external user.
email (required): Email address of the external user.
name (optional): Name of the external user.
is_subscribed (optional): Boolean indicating whether the external user is subscribed. Default is true.
fields (optional): Array of ImportExternalUsersInputFieldInput objects representing additional fields for the external user.

Each ImportExternalUsersInputFieldInput object should have the following fields:

name (required): Name of the additional field.
value (required): Value of the additional field.

Return Type: Returns the ImportExternalUsersResult object.

The ImportExternalUsersResult object has the following fields:

project_id: ID of the project.
users: Array of ImportExternalUsersInputUserInput objects representing the imported external users.

Example:

{
"mutation": "importExternalUsers",
"variables": {
"input": {
"project_id": "project123",
"users": [
{
"id": "user123",
"email": "[email protected]",
"name": "User 1",
"is_subscribed": true,
"fields": [
{
"name": "Field 1",
"value": "Value 1"
},
{
"name": "Field 2",
"value": "Value 2"
}
]
},
{
"id": "user456",
"email": "[email protected]",
"name": "User 2",
"is_subscribed": false,
"fields": [
{
"name": "Field 3",
"value": "Value 3"
}
]
}
]
}
}
}

createSegmentProfile

Description: Creates a segment profile for a project with the provided title and rules.

Arguments:

project_id (required): ID of the project to create the segment profile for.
title (required): Title of the segment profile.
rules (required): JSON object containing the rules for the segment profile.

Return Type: Returns a SegmentProfile object representing the created segment profile.

Example:

{
"mutation": "createSegmentProfile",
"variables": {
"project_id": "project123",
"title": "New Segment Profile",
"rules": {
"attribute": "age",
"operator": "greater_than",
"value": 30
}
}
}

removeSegmentProfile

Description: Removes a segment profile from a project.

Arguments:

project_id (required): ID of the project the segment profile belongs to.
title (required): Title of the segment profile to be removed.

Return Type: Returns a Boolean value indicating whether the removal of the segment profile was successful.

Example:

{
"mutation": "removeSegmentProfile",
"variables": {
"project_id": "project123",
"title": "Segment Profile 1"
}
}