What Can GraphQL Queries do for AnnounceKit?
GraphQL Queries are special commands for you to run in our IDE. These special commands are used to bring information about your project, such as your user_id, project_id and various of detailed information from your project.
How to use these queries?
Below is a documentation for all of the queries found in AnnounceKit, along with its explanations objects and arguments. 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 queries below are used by going into our IDE located here.
We recommend that you get your project and user ID by running the query below.
{
me {
id
active_project {
id
}
}
}
You can also click on the link here to run this query.
me
Query:
The me query returns the current user. The me query does not take any arguments.
Object:
The User object is the data structure that is returned by the me query. It contains the following properties:
id: The unique identifier for the user.hash: The hashed password for the user.email: The email address for the user.display_name: The display name for the user.title: The title for the user.created_at: The date and time the user was created.image_id: The ID of the user's image.image: The user's image.active_project: The user's active project.memberships: The user's memberships in projects.avatar: The user's avatar.is_validated: Whether the user has validated their email address.is_totp_enabled: Whether the user has enabled two-factor authentication.is_unsubs: Whether the user has unsubscribed from email notifications.
Examples:
The following example shows how to use the me query to get the current user's ID and name:
GraphQL
query {
me {
id
name
}
}
JSON
{
"me": {
"id": "123456789",
"name": "John Doe"
}
}
project
Query:
The project query returns a project by its ID. The project_id argument is the unique identifier for the project.
Argument:
The project_id argument is a required argument. It is the unique identifier for the project that you want to retrieve.
Object:
The Project object is the data structure that is returned by the project query. It contains the following properties:
id: The unique identifier for the project.encodedId: The encoded ID for the project.name: The name of the project.slug: The slug of the project.website: The website of the project.is_authors_listed: Whether the authors of the project are listed.is_whitelabel: Whether the project is whitelabeled.is_subscribable: Whether the project is subscribable.is_slack_subscribable: Whether the project is slack subscribable.is_feedback_enabled: Whether feedback is enabled for the project.is_demo: Whether the project is a demo project.is_readonly: Whether the project is readonly.image_id: The ID of the project's image.favicon_id: The ID of the project's favicon.image: The project's image.created_at: The date and time the project was created.ga_property: The Google Analytics property for the project.privacy_policy_url: The privacy policy URL for the project.members: The members of the project.invites: The invites to the project.labels: The labels for the project.statuses: The statuses for the project.billing_info: The billing information for the project.subscription: The subscription for the project.avatar: The avatar for the project.favicon: The favicon for the project.plan: The plan for the project.locale: The locale for the project.locales: The locales for the project.feeds: The feeds for the project.integrations: The integrations for the project.analytics: The analytics for the project.usesNewFeedHostname: Whether the project uses the new feed hostname.payment_gateway: The payment gateway for the project.trial_until: The trial end date for the project.metadata: The metadata for the project.widget: The widget for the project.
Examples:
The following example shows how to use the project query to get a project by its ID:
GraphQL
query {
project(project_id: "123456789") {
id
name
slug
}
}
The following JSON shows the response that would be returned by the GraphQL server:
JSON
{
"project": {
"id": "123456789",
"name": "My Project",
"slug": "my-project"
}
}
post
Query
The post query is a GraphQL query that returns information about a post. The query takes two arguments:
project_id(required): The ID of the project that the post belongs to.post_id(required): The ID of the post.
Object
Post: ThePostobject that is returned by thepostquery.id: The unique identifier for the post.project_id: The ID of the project that the post belongs to.user_id: The ID of the user who created the post.project: TheProjectobject that the post belongs to.user: TheUserobject who created the post.created_at: The date and time the post was created.visible_at: The date and time the post will be visible to everyone.image_id: The ID of the image for the post.expire_at: The date and time the post will expire.updated_at: The date and time the post was last updated.is_draft: Whether the post is a draft.is_pushed: Whether the post has been pushed to production.is_pinned: Whether the post is pinned to the top of the project.is_internal: Whether the post is internal only.external_url: The external URL for the post.labels: The labels for the post.segment_filters: The segment filters for the post.flags: The flags for the post.defaultContent: The default content for the post.contents: The contents of the post.view_data: The view data for the post.status: The status of the post.is_paused: Whether the post is paused.notification: The notification for the post.
Examples
The following query will return the post with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
post(project_id: 123456789, post_id: 123456789) {
id
project
user
created_at
}
}
This query will return the following JSON:
JSON
{
"post": {
"id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"user": {
"id": "123456789",
"name": "John Doe"
},
"created_at": "2023-07-13T11:11:11Z"
}
}
posts
Query
The posts query is a GraphQL query that returns a list of posts. The query takes the following arguments:
project_id(required): The ID of the project that the posts belong to.page(optional): The page number of the results to return. Defaults to 0.labels(optional): A list of IDs of the labels that the posts should have.query(optional): A search query for the posts.createdBy(optional): The ID of the user who created the posts.postStatus(optional): The status of the posts.orderField(optional): The field to order the posts by.
Object
Posts: ThePostsobject that is returned by thepostsquery.list: A list ofPostobjects.count: The total number of posts.page: The current page number.pages: The total number of pages.
Examples
The following query will return the first page of posts in the project with the ID 123456789:
GraphQL
{
posts(project_id: 123456789) {
list {
id
project
user
created_at
}
count
page
pages
}
}
JSON
{
"posts": {
"list": [
{
"id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"user": {
"id": "123456789",
"name": "John Doe"
},
"created_at": "2023-07-13T11:11:11Z"
}
],
"count": 100,
"page": 1,
"pages": 10
}
}
postTemplates
Query
The postTemplates query is a GraphQL query that returns a list of post templates. The query takes the following argument:
project_id(required): The ID of the project that the post templates belong to.
Object
PostTemplate: ThePostTemplateobject that is returned by thepostTemplatesquery.id: The unique identifier for the post template.title: The title of the post template.body: The body of the post template.
Examples
The following query will return all of the post templates in the project with the ID 123456789:
GraphQL
{
postTemplates(project_id: 123456789) {
id
title
body
}
}
This query will return the following JSON:
JSON
{
"postTemplates": [
{
"id": "123456789",
"title": "My Post Template",
"body": "This is the body of my post template."
},
{
"id": "987654321",
"title": "Another Post Template",
"body": "This is the body of another post template."
}
]
}
feedbackCounts
Query
The feedbackCounts query is a GraphQL query that returns a list of feedback counts for a post. The query takes the following arguments:
project_id(required): The ID of the project that the post belongs to.post_id(required): The ID of the post.
Object
FeedbackCount: TheFeedbackCountobject that is returned by thefeedbackCountsquery.reaction: The reaction type.count: The number of feedbacks for the reaction type.
Examples
The following query will return the feedback counts for the post with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
feedbackCounts(project_id: 123456789, post_id: 123456789) {
reaction
count
}
}
This query will return the following JSON:
JSON
{
"feedbackCounts": [
{
"reaction": ":)",
"count": 100
},
{
"reaction": ":(",
"count": 50
},
{
"reaction": ":)",
"count": 25
}
]
}
feedbackHappinessTable
Query
The feedbackHappinessTable query is a GraphQL query that returns a table of feedback happiness scores for a post. The query takes the following arguments:
project_id(required): The ID of the project that the post belongs to.post_id(required): The ID of the post.
Object
The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.
Examples
The following query will return the feedback happiness table for the post with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
feedbackHappinessTable(project_id:123456789,post_id:123456789)
}
This query will return the following JSON:
JSON
{
"data": {
"feedbackHappinessTable": [
[
1688947200000,
0.75
]
]
}
}
feedbacks
Query
The feedbacks query is a GraphQL query that returns a paginated list of feedbacks for a post. The query takes the following arguments:
project_id(required): The ID of the project that the post belongs to.post_id(required): The ID of the post.page(optional): The page number of the results to return. Defaults to 0.
Object
The PageOfFeedback object that is returned by the feedbacks query is a paginated list of feedbacks. The object has the following properties:
page(integer): The current page number.pages(integer): The total number of pages.count(integer): The total number of feedbacks.items(array ofFeedbackobjects): The list of feedbacks on the current page.
Examples
The following query will return the first page of feedbacks for the post with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
feedbacks(project_id: 123456789, post_id: 123456789) {
page
pages
count
items {
reaction
feedback
}
}
}
This query will return the following JSON:
JSON
{
"data": {
"feedbacks": {
"page": 0,
"pages": 1,
"count": 6,
"items": [
{
"reaction": ":)",
"feedback": null
},
{
"reaction": null,
"feedback": "test"
},
{
"reaction": ":)",
"feedback": null
},
{
"reaction": ":)",
"feedback": null
},
{
"reaction": ":)",
"feedback": null
},
{
"reaction": ":)",
"feedback": null
}
]
}
}
}
activities
Query
The activities query is a GraphQL query that returns a paginated list of activities for a post. The query takes the following arguments:
project_id(required): The ID of the project that the post belongs to.post_id(required): The ID of the post.external_user_id(optional): The ID of the external user who performed the activities.page(optional): The page number of the results to return. Defaults to 0.type(optional): A list of activity types.segmentProfile(optional): A JSON object that represents the segment profile of the user who performed the activities.
Object
The PageOfActivities object that is returned by the activities query is a paginated list of activities. The object has the following properties:
items(array ofActivityobjects): The list of activities on the current page.page(integer): The current page number.pages(integer): The total number of pages.count(integer): The total number of activities.
Examples
The following query will return the first page of activities for the post with the ID 123456789 in the project with the ID 123456789 for the post with the ID 123456789:
GraphQL
{
activities(project_id: 123456789, post_id: 123456789) {
items {
id
type
}
page
pages
count
}
}
This query will return the following JSON:
JSON
{
"data": {
"activities": {
"items": [
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-link-click"
},
{
"id": "123456789",
"type": "mail-read"
},
{
"id": "123456789",
"type": "mail-read"
}
],
"page": 0,
"pages": 240,
"count": 2399
}
}
}
unreadActivities
Query
The unreadActivities query is a GraphQL query that returns the number of unread activities for a project. The query takes the following argument:
project_id(required): The ID of the project.
Object
The UnreadActivities object that is returned by the unreadActivities query is a object with the following properties:
id(integer): The ID of the project.count(integer): The number of unread activities.
Examples
The following query will return the number of unread activities for the project with the ID 123456789:
GraphQL
{
unreadActivities(project_id:123456789) {
id
count
}
}
This query will return the following JSON:
JSON
{
"data": {
"unreadActivities": {
"id": "123456789",
"count": 27
}
}
}
checkEmailDigest
Query
The checkEmailDigest query is a GraphQL query that returns the status of email digests for a project. The query takes the following argument:
project_id(required): The ID of the project.
Object
The EmailDigestStatus object that is returned by the checkEmailDigest query is a object with the following properties:
id(integer): The ID of the project.sending_interval(string): The interval at which email digests are sent.
Examples
The following query will return the status of email digests for the project with the ID 123456789:
GraphQL
{
checkEmailDigest(project_id:123456789) {
id
}
}
This query will return the following JSON:
JSON
{
"checkEmailDigest": {
"id": "123456789",
"sending_interval": "weekly"
}
}
auditlog
Query
The auditlog query is a GraphQL query that returns a paginated list of audit logs for a project. The query takes the following arguments:
project_id(required): The ID of the project.page(optional): The page number of the results to return. Defaults to 0.
Argument
project_id: The ID of the project.This argument is required.
The ID must be a valid integer.
page: The page number of the results to return.This argument is optional.
The default value is 0.
Object
The PageOfAuditlog object that is returned by the auditlog query is a paginated list of audit logs. The object has the following properties:
items(array ofAuditlogobjects): The list of audit logs on the current page.page(integer): The current page number.pages(integer): The total number of pages.count(integer): The total number of audit logs.
Object
The Auditlog object that is returned by the auditlog query is a object with the following properties:
id(integer): The ID of the audit log.created_at(string): The date and time the audit log was created.username(string): The username of the user who performed the action.ip_address(string): The IP address of the user who performed the action.event_type(string): The type of event that was logged.event_action(string): The action that was performed.metadata(JSON object): A JSON object that contains additional metadata about the audit log.
Examples
The following query will return the first page of audit logs for the project with the ID 123456789:
GraphQL
{
auditlog(project_id: 123456789) {
items {
id
created_at
username
ip_address
event_type
event_action
metadata
}
page
pages
count
}
}
This query will return the following JSON:
JSON
{
"auditlog": {
"items": [
{
"id": "123456789",
"created_at": "2023-07-13T11:11:11Z",
"username": "John Doe",
"ip_address": "192.168.1.1",
"event_type": "post_created",
"event_action": "created",
"metadata": {
"post_id": "123456789"
}
},
{
"id": "987654321",
"created_at": "2023-07-13T11:11:12Z",
"username": "Jane Doe",
"ip_address": "192.168.1.2",
"event_type": "comment_created",
"event_action": "created",
"metadata": {
"post_id": "123456789",
"comment_id": "987654321"
}
}
],
"page": 1,
"pages": 10,
"count": 100
}
}
feed
The feed query is a GraphQL query that returns a feed. The query takes the following arguments:
project_id(required): The ID of the project that the feed belongs to.feed_id(required): The ID of the feed.
Note project_id and feed_id are usually the same
Argument
project_id: The ID of the project that the feed belongs to.This argument is required.
The ID must be a valid integer.
feed_id: The ID of the feed.This argument is required.
The ID must be a valid integer.
Object
The Feed object that is returned by the feed query is a object with the following properties:
id(integer): The ID of the feed.project_id(integer): The ID of the project that the feed belongs to.project(object): The project that the feed belongs to.name(string): The name of the feed.slug(string): The slug of the feed.created_at(string): The date and time the feed was created.custom_host(string): The custom host for the feed.website(string): The website for the feed.color(string): The color of the feed.url(string): The URL of the feed.is_disabled(boolean): Whether the feed is disabled.is_unindexed(boolean): Whether the feed is unindexed.is_private(boolean): Whether the feed is private.is_readmore(boolean): Whether the feed has readmore enabled.html_inject(string): The HTML inject for the feed.metadata(JSON object): A JSON object that contains additional metadata about the feed.theme(JSON object): A JSON object that contains the theme for the feed.version(integer): The version of the feed.
Examples
The following query will return the feed with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
feed(project_id: 123456789, feed_id: 123456789) {
id
project_id
project
name
slug
created_at
custom_host
website
color
url
is_disabled
is_unindexed
is_private
is_readmore
html_inject
metadata
theme
version
}
}
This query will return the following JSON:
JSON
{
"feed": {
"id": "123456789",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"name": "My Feed",
"slug": "my-feed",
"created_at": "2023-07-13T11:11:11Z",
"custom_host": null,
"website": null,
"color": "#ffffff",
"url": "https://my-feed.com/",
"is_disabled": false,
"is_unindexed": false,
"is_private": false,
"is_readmore": true,
"html_inject": null,
"metadata": {},
"theme": {},
"version": 1
}
}
feeds
Query
The feeds query is a GraphQL query that returns a list of feeds. The query takes the following arguments:
project_id(required): The ID of the project that the feeds belong to.
Argument
project_id: The ID of the project that the feeds belong to.This argument is required.
The ID must be a valid integer.
Object
The Feed object that is returned by the feeds query is a object with the following properties:
id(integer): The ID of the feed.project_id(integer): The ID of the project that the feed belongs to.project(object): The project that the feed belongs to.name(string): The name of the feed.slug(string): The slug of the feed.created_at(string): The date and time the feed was created.custom_host(string): The custom host for the feed.website(string): The website for the feed.color(string): The color of the feed.url(string): The URL of the feed.is_disabled(boolean): Whether the feed is disabled.is_unindexed(boolean): Whether the feed is unindexed.is_private(boolean): Whether the feed is private.is_readmore(boolean): Whether the feed has readmore enabled.html_inject(string): The HTML inject for the feed.metadata(JSON object): A JSON object that contains additional metadata about the feed.theme(JSON object): A JSON object that contains the theme for the feed.version(integer): The version of the feed.
Examples
The following query will return all of the feeds in the project with the ID 123456789:
GraphQL
{
feeds(project_id: 123456789) {
id
project_id
project
name
slug
created_at
custom_host
website
color
url
is_disabled
is_unindexed
is_private
is_readmore
html_inject
metadata
theme
version
}
}
This query will return the following JSON:
JSON
{
"feeds": [
{
"id": "123456789",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"name": "My Feed",
"slug": "my-feed",
"created_at": "2023-07-13T11:11:11Z",
"custom_host": null,
"website": null,
"color": "#ffffff",
"url": "https://my-feed.com/",
"is_disabled": false,
"is_unindexed": false,
"is_private": false,
"is_readmore": true,
"html_inject": null,
"metadata": {},
"theme": {},
"version": 1
},
{
"id": "987654321",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"name": "Another Feed",
"slug": "another-feed",
"created_at": "2023-07-13T1
widget
Query
The widget query is a GraphQL query that returns a widget. The query takes the following arguments:
project_id(required): The ID of the project that the widget belongs to.widget_id(required): The ID of the widget.
Argument
project_id: The ID of the project that the widget belongs to.This argument is required.
The ID must be a valid integer.
widget_id: The ID of the widget.This argument is required.
The ID must be a valid integer.
Object
The Widget object that is returned by the widget query is a object with the following properties:
id(integer): The ID of the widget.project_id(integer): The ID of the project that the widget belongs to.project(object): The project that the widget belongs to.created_at(string): The date and time the widget was created.name(string): The name of the widget.mode(string): The mode of the widget.action(string): The action of the widget.slug(string): The slug of the widget.options(JSON object): A JSON object that contains the options for the widget.theme(JSON object): A JSON object that contains the theme for the widget.version(integer): The version of the widget.ga_cookie_status(string): The status of the Google Analytics cookie for the widget.content_to_show(string): The content to show in the widget.
Examples
The following query will return the widget with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
widget(project_id: 123456789, widget_id: 123456789) {
id
project_id
project
created_at
name
mode
action
slug
options
theme
version
ga_cookie_status
content_to_show
}
}
This query will return the following JSON:
JSON
{
"widget": {
"id": "123456789",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"created_at": "2023-07-13T11:11:11Z",
"name": "My Widget",
"mode": "embed",
"action": "https://my-widget.com/",
"slug": "my-widget",
"options": {},
"theme": {},
"version": 1,
"ga_cookie_status": "allow",
"content_to_show": "This is the content to show in the widget"
}
}
widgets
Query
The widgets query is a GraphQL query that returns a list of widgets. The query takes the following arguments:
project_id(required): The ID of the project that the widgets belong to.
Argument
project_id: The ID of the project that the widgets belong to.This argument is required.
The ID must be a valid integer.
Object
The Widget object that is returned by the widgets query is a object with the following properties:
id(integer): The ID of the widget.project_id(integer): The ID of the project that the widget belongs to.project(object): The project that the widget belongs to.created_at(string): The date and time the widget was created.name(string): The name of the widget.mode(string): The mode of the widget.action(string): The action of the widget.slug(string): The slug of the widget.options(JSON object): A JSON object that contains the options for the widget.theme(JSON object): A JSON object that contains the theme for the widget.version(integer): The version of the widget.ga_cookie_status(string): The status of the Google Analytics cookie for the widget.content_to_show(string): The content to show in the widget.
Examples
The following query will return all of the widgets in the project with the ID 123456789:
GraphQL
{
widgets(project_id: 123456789) {
id
project_id
project
created_at
name
mode
action
slug
options
theme
version
ga_cookie_status
content_to_show
}
}
This query will return the following JSON:
JSON
{
"widgets": [
{
"id": "123456789",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"created_at": "2023-07-13T11:11:11Z",
"name": "My Widget",
"mode": "embed",
"action": "https://my-widget.com/",
"slug": "my-widget",
"options": {},
"theme": {},
"version": 1,
"ga_cookie_status": "allow",
"content_to_show": "This is the content to show in the widget"
},
{
"id": "987654321",
"project_id": "123456789",
"project": {
"id": "123456789",
"name": "My Project"
},
"created_at": "2023-07-13T11:11:12Z",
"name": "Another Widget",
"mode": "embed",
"action": "https://another-widget.com/",
"slug": "another-widget",
"options": {},
"theme": {},
"version": 1,
"ga_cookie_status": "allow",
"content_to_show": "This is the content to show in another widget"
}
]
}
imports & import
Query
Both import and imports is a GraphQL query that returns a list of migrartions made on your project from other services. The query takes the following arguments:
project_id(required): The ID of the project that the imports belong to.
Tne oly difference is that, import requires your import_id, which can be found within imports
Object
The Import object that is returned by the imports query is a object with the following properties:
id(integer): The ID of the import.project_id(integer): The ID of the project that the import belongs to.user_id(integer): The ID of the user who created the import.status(string): The status of the import.source(string): The source of the import.created_at(string): The date and time the import was created.is_continuous(boolean): Whether the import is continuous.message(string): A message about the import.
Examples
The following query will return all of the imports in the project with the ID 123456789:
GraphQL
{
imports(project_id: 29289) {
id
project_id
user_id
status
source
created_at
is_continuous
message
}
}
This query will return the following JSON:
JSON
{
"data": {
"imports": [
{
"id": "1053",
"project_id": "29289",
"user_id": "15924",
"status": "finished",
"source": "headway",
"created_at": "2023-07-17T16:14:55.667Z",
"is_continuous": false,
"message": "Import Finished"
}
]
}
}
labels
Query
The labels query is a GraphQL query that returns a list of labels. The query takes the following arguments:
project_id(required): The ID of the project that the labels belong to.
Argument
project_id: The ID of the project that the labels belong to.This argument is required.
The ID must be a valid integer.
Object
The Label object that is returned by the labels query is a object with the following properties:
id(integer): The ID of the label.project_id(integer): The ID of the project that the label belongs to.name(string): The name of the label.color(string): The color of the label.
Examples
The following query will return all of the labels in the project with the ID 123456789:
GraphQL
{
labels(project_id:123456789) {
id
name
color
}
}
This query will return the following JSON:
JSON
{
"labels": [
{
"id": "123456789",
"project_id": "123456789",
"name": "Important",
"color": "#ff0000"
},
{
"id": "987654321",
"project_id": "123456789",
"name": "Low Priority",
"color": "#00ff00"
}
]
}
segments
Query
The segments query is a GraphQL query that returns a list of segments used in the project. The query takes the following arguments:
project_id(required): The ID of the project that the segments belong to.
Argument
project_id: The ID of the project that the segments belong to.This argument is required.
The ID must be a valid integer.
Object
The Segment object that is returned by the segments query is a string with the following properties:
segment(string): The name of the segment.
Examples
The following query will return all of the segments in the project with the ID 123456789:
GraphQL
{
segments(project_id:123456789)
}
This query will return the following JSON:
JSON
{
"segments": [
"marketing",
"sales",
"support"
]
}
segmentProfiles
Query
The segmentProfiles query is a GraphQL query that returns the list of segment profiles and their rules. The query takes the following arguments:
project_id(required): The ID of the project that the segment profiles belong to.
Argument
project_id: The ID of the project that the segment profiles belong to.This argument is required.
The ID must be a valid integer.
Object
The SegmentProfile object that is returned by the segmentProfiles query is a object with the following properties:
project_id(integer): The ID of the project that the segment profile belongs to.title(string): The title of the segment profile.rules(JSON object): The rules for the segment profile.
Examples
The following query will return all of the segment profiles in the project with the ID 123456789:
GraphQL
{
segmentProfiles(project_id: 123456789) {
project_id
title
rules
}
}
This query will return the following JSON:
JSON
{
"data": {
"segmentProfiles": [
{
"project_id": "123456789",
"title": "Internal Team",
"rules": "{\"filter\":[\"contains\",\"user_email\",\"internalteam.com\"]}"
}
]
}
}
externalUsers
Query
The externalUsers query is a GraphQL query that returns a paginated list of external users. The query takes the following arguments:
project_id(required): The ID of the project that the external users belong to.filters(optional): A JSON object with filters to be applied to the query.page(optional): The page number of the results to return. Defaults to 0.sortField(optional): The field to sort the results by. Defaults toSEEN_AT.sortOrder(optional): The sort order of the results. Defaults toDESC.
Argument
project_id: The ID of the project that the external users belong to.This argument is required.
The ID must be a valid integer.
filters: A JSON object with filters to be applied to the query.This argument is optional.
The object must contain a
fieldproperty and avalueproperty. Thefieldproperty specifies the field to filter on, and thevalueproperty specifies the value to filter for.
page: The page number of the results to return.This argument is optional.
The default value is 0.
sortField: The field to sort the results by.This argument is optional.
The default value is
SEEN_AT.
sortOrder: The sort order of the results.This argument is optional.
The default value is
DESC.
Object
The PageOfExternalUsers object that is returned by the externalUsers query is a object with the following properties:
page(integer): The current page number.pages(integer): The total number of pages.count(integer): The total number of external users.items(array): An array ofExternalUserobjects.
Examples
The following query will return the first page of external users in the project with the ID 123456789, sorted by the SEEN_AT field in descending order:
GraphQL
{
externalUsers(
project_id: 123456789
sortField: SEEN_AT
sortOrder: DESC
) {
page
pages
count
items {
id
email
name
seen_at
}
}
}
This query will return the following JSON:
JSON
{
"externalUsers": {
"page": 1,
"pages": 10,
"count": 100,
"items": [
{
"id": "123456789",
"email": "[email protected]",
"name": "John Doe",
"seen_at": "2023-07-13T11:11:11Z"
},
{
"id": "987654321",
"email": "[email protected]",
"name": "Jane Doe",
"seen_at": "2023-07-13T11:11:12Z"
}
]
}
}
externalUserCount
Query
The externalUserCount query is a GraphQL query that returns the number of external users in a project. The query takes the following arguments:
project_id(required): The ID of the project that the external users belong to.filters(optional): A JSON object with filters to be applied to the query.
Argument
project_id: The ID of the project that the external users belong to.This argument is required.
The ID must be a valid integer.
filters: A JSON object with filters to be applied to the query.This argument is optional.
The object must contain a
fieldproperty and avalueproperty. Thefieldproperty specifies the field to filter on, and thevalueproperty specifies the value to filter for.
Object
The externalUserCount object that is returned by the externalUserCount query is a object with the following properties:
count(integer): The number of external users.
Examples
The following query will return the number of external users in the project with the ID 123456789:
GraphQL
{
externalUserCount(project_id: 123456789)
}
This query will return the following JSON:
JSON
{
"externalUserCount": 100
}
externalUser
Query
The externalUser query is a GraphQL query that returns an external user. The query takes the following arguments:
project_id(required): The ID of the project that the external user belongs to.external_user_id(required): The ID of the external user.
User id's can be found under Audience section.
Argument
project_id: The ID of the project that the external user belongs to.This argument is required.
The ID must be a valid integer.
external_user_id: The ID of the external user.This argument is required.
The ID must be a valid integer.
Object
The ExternalUser object that is returned by the externalUser query is a object with the following properties:
id(integer): The ID of the external user.project_id(integer): The ID of the project that the external user belongs to.created_at(string): The date and time the external user was created.seen_at(string): The date and time the external user was last seen.name(string): The name of the external user.email(string): The email address of the external user.fields(JSON object): A JSON object with custom fields for the external user.is_anon(boolean): Whether the external user is anonymous.is_following(boolean): Whether the external user is following the project.is_email_verified(boolean): Whether the external user's email address has been verified.is_imported(boolean): Whether the external user was imported from another system.avatar(string): The URL of the external user's avatar.is_app(boolean): Whether the external user is an app.
Examples
The following query will return the external user with the ID 123456789 in the project with the ID 123456789:
GraphQL
{
externalUser(project_id: 123456789, external_user_id: 123456789) {
id
project_id
created_at
seen_at
name
email
fields
is_anon
is_following
is_email_verified
is_imported
avatar
is_app
}
}
This query will return the following JSON:
JSON
{
"externalUser": {
"id": "123456789",
"project_id": "123456789",
"created_at": "2023-07-13T11:11:11Z",
"seen_at": "2023-07-13T11:11:12Z",
"name": "John Doe",
"email": "[email protected]",
"fields": {},
"is_anon": false,
"is_following": false,
"is_email_verified": true,
"is_imported": false,
"avatar": "https://avatars.example.com/john.doe",
"is_app": false
}
}
analytics
Query
The analytics query is a GraphQL query that returns analytics data for a project. The query takes the following arguments:
project_id(required): The ID of the project that the analytics data belongs to.startDate(required): The start date of the time period for which the analytics data is being retrieved.endDate(required): The end date of the time period for which the analytics data is being retrieved.
Argument
project_id: The ID of the project that the analytics data belongs to.This argument is required.
The ID must be a valid integer.
startDate: The start date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
endDate: The end date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
Object
The Analytics object that is returned by the analytics query is a object with the following properties:
unsubs(integer): The number of unsubscribes.subs(integer): The number of subscriptions.feedback(integer): The number of feedback submissions.reaction(integer): The number of reactions.mail_sent(integer): The number of emails sent.post_views(integer): The number of post views.feed_views(integer): The number of feed views.widget_imp(integer): The number of widget impressions.widget_views(integer): The number of widget views.
Examples
The following query will return the analytics data for the project with the ID 123456789 for the time period from 2023-07-01 to 2023-07-31:
GraphQL
{
analytics(project_id: 123456789, startDate: "2023-07-01", endDate: "2023-07-31") {
unsubs
subs
feedback
reaction
mail_sent
post_views
feed_views
widget_imp
widget_views
}
}
This query will return the following JSON:
JSON
{
"analytics": {
"unsubs": 100,
"subs": 200,
"feedback": 50,
"reaction": 1000,
"mail_sent": 10000,
"post_views": 100000,
"feed_views": 200000,
"widget_imp": 1000000,
"widget_views": 500000
}
}
analyticsChart
Query
The analyticsChart query is a GraphQL query that returns a chart of analytics data for a project. The query takes the following arguments:
project_id(required): The ID of the project that the analytics data belongs to.startDate(required): The start date of the time period for which the analytics data is being retrieved.endDate(required): The end date of the time period for which the analytics data is being retrieved.
Argument
project_id: The ID of the project that the analytics data belongs to.This argument is required.
The ID must be a valid integer.
startDate: The start date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
endDate: The end date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
Object
The AnalyticsChart object that is returned by the analyticsChart query is a object with the following properties:
labels(array of strings): The labels for the chart.datasets(array ofChartDatasetobjects): The datasets for the chart.
Object
The ChartDataset object that is returned by the analyticsChart query is a object with the following properties:
label(string): The label for the dataset.data(array of integers): The data for the dataset.
Examples
The following query will return a chart of the analytics data for the project with the ID 123456789 for the time period from 2023-07-17 to 2023-07-17: (same day)
GraphQL
{
analyticsChart(project_id: 123456789, startDate: "2023-07-17", endDate: "2023-07-17") {
labels
datasets {
label
data
}
}
}
This query will return the following JSON:
JSON
{
"data": {
"analyticsChart": {
"labels": [
"17/07"
],
"datasets": [
{
"label": "OPEN",
"data": [
113
]
},
{
"label": "LOAD",
"data": [
1289
]
},
{
"label": "CLOSE",
"data": [
52
]
}
]
}
}
}
analyticsPost
Query
The analyticsPost query is a GraphQL query that returns analytics data for posts in a project. The query takes the following arguments:
project_id(required): The ID of the project that the analytics data belongs to.startDate(required): The start date of the time period for which the analytics data is being retrieved.endDate(required): The end date of the time period for which the analytics data is being retrieved.
Argument
project_id: The ID of the project that the analytics data belongs to.This argument is required.
The ID must be a valid integer.
startDate: The start date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
endDate: The end date of the time period for which the analytics data is being retrieved.This argument is required.
The date must be in the format
YYYY-MM-DD.
Object
The AnalyticsPost object that is returned by the analyticsPost query is a object with the following properties:
posts(array ofAnalyticsPostItemobjects): The posts for the project.
Object
The AnalyticsPostItem object that is returned by the analyticsPost query is a object with the following properties:
id(integer): The ID of the post.title(string): The title of the post.view(integer): The number of views for the post.likes(integer): The number of likes for the post.dislikes(integer): The number of dislikes for the post.neutral(integer): The number of neutral reactions for the post.comment(integer): The number of comments for the post.
Examples
The following query will return the analytics data for posts in the project with the ID 123456789 for the time period from 2023-07-01 to 2023-07-31:
GraphQL
{
analyticsPost(project_id: 123456789, startDate: "2023-07-01", endDate: "2023-07-31") {
posts {
id
title
view
likes
dislikes
neutral
comment
}
}
}
This query will return the following JSON:
JSON
{
"analyticsPost": {
"posts": [
{
"id": 123456789,
"title": "My First Post",
"view": 1000,
"likes": 200,
"dislikes": 50,
"neutral": 10,
"comment": 50
},
{
"id": 987654321,
"title": "My Second Post",
"view": 500,
"likes": 100,
"dislikes": 20,
"neutral": 5,
"comment": 25
}
]
}
}
analyticsv2
Query
The analyticsv2 query is a GraphQL query that returns analytics data for a project. The query takes the following arguments:
input(required): An object that specifies the parameters for the analytics query.
Object
The AnalyticsInput object that is returned by the analyticsv2 query is a object with the following properties:
project_id(required): The ID of the project that the analytics data belongs to.start_date(required): The start date of the time period for which the analytics data is being retrieved.end_date(required): The end date of the time period for which the analytics data is being retrieved.dimensions(array of strings): The dimensions for the analytics report.metrics(array of strings): The metrics for the analytics report.event_type(array of strings): The event types for the analytics report.post_id(array of integers): The IDs of the posts for the analytics report.widget_id(array of integers): The IDs of the widgets for the analytics report.feed_id(array of integers): The IDs of the feeds for the analytics report.client_country(array of strings): The countries of the users for the analytics report.client_locale(array of strings): The locales of the users for the analytics report.client_device(array of strings): The devices of the users for the analytics report.sort_by(string): The field to sort the results by.sort_desc(boolean): Whether to sort the results in descending order.user_filter(JSON object): A JSON object with user filters for the analytics report.limit(integer): The maximum number of rows to return.offset(integer): The number of rows to skip.
Object
The AnalyticsReport object that is returned by the analyticsv2 query is a object with the following properties:
start_date(date): The start date of the time period for which the analytics data is being retrieved.end_date(date): The end date of the time period for which the analytics data is being retrieved.sort_by(string): The field to sort the results by.sort_desc(boolean): Whether to sort the results in descending order.headers(array ofAnalyticsReportHeaderobjects): The headers for the analytics report.rows(array of arrays of strings): The rows of the analytics report.
Object
The AnalyticsReportHeader object that is returned by the analyticsv2 query is a object with the following properties:
name(string): The name of the header.type(string): The type of the header.
Examples
The following query will return the analytics data for the project with the ID 123456789 for the time period from 2023-07-01 to 2023-07-31.
GraphQL
query {
analyticsv2(input: {
start_date: "2023-07-01"
end_date: "2023-07-31"
project_id: 123456789
}) {
start_date
sort_by
sort_desc
headers {
name
type
}
}
}
image
Query
The image query is a GraphQL query that returns an image of account. The query takes the following arguments:
image_id(required): The ID of the image.
image_id can be found by running the me query.
Object
The Image object that is returned by the image query is a object with the following properties:
id(integer): The ID of the image.src(string): The URL of the image.
Object
The src field of the Image object is a function that takes a size parameter and returns the URL of the image in that size. The size parameter can be one of the following values:
thumbsmallmediumlargeoriginal
Examples
The following query will return the image with the ID 123456789. The query will also return the URL of the image in the small size.
GraphQL
{
image(image_id: 4e62f9daea851b085c02e68e9b7366a7) {
id
src(size: "small")
}
}
This query will return the following JSON:
JSON
{
"image": {
"id": 123456789,
"src": "https://example.com/images/123456789-small.jpg"
}
}
checkSubscriptionPlan
Query
The checkSubscriptionPlan query is a GraphQL query that returns the subscription plans of AnnounceKit. The query takes the following arguments:
project_id(required): The ID of the project.coupon(optional): The coupon code applied to the subscription plan.
Object
The Plan object that is returned by the checkSubscriptionPlan query is a object with the following properties:
id(integer): The ID of the plan.group(string): The group of the plan.name(string): The name of the plan.hasCustomLabels(boolean): Whether the plan allows custom labels.hasCustomDomains(boolean): Whether the plan allows custom domains.hasWhiteLabel(boolean): Whether the plan allows white labeling.hasTeam(boolean): Whether the plan allows teams.hasPrivacy(boolean): Whether the plan allows privacy features.hasSubscriptions(boolean): Whether the plan allows subscriptions.hasFeedback(boolean): Whether the plan allows feedback.hasUserTracking(boolean): Whether the plan allows user tracking.hasSegmentation(boolean): Whether the plan allows segmentation.hasCustomCSS(boolean): Whether the plan allows custom CSS.hasIntegrations(boolean): Whether the plan allows integrations.hasPostCustomization(boolean): Whether the plan allows post customization.hasMultiLanguage(boolean): Whether the plan allows multi-language support.hasThemes(boolean): Whether the plan allows themes.hasBoosters(boolean): Whether the plan allows boosters.hasSaml(boolean): Whether the plan allows SAML.hasIPAccessControl(boolean): Whether the plan allows IP access control.hasEmailDigest(boolean): Whether the plan allows email digests.hasFeatureRequest(boolean): Whether the plan allows feature requests.hasJiraIntegration(boolean): Whether the plan allows Jira integration.hasNotify(boolean): Whether the plan allows notifications.interval(string): The billing interval for the plan.price(integer): The monthly price of the plan.setup_price(integer): The one-time setup price of the plan.bullets(array of strings): The bullets for the plan.
Examples
The following query will return the subscription plan for the project with the ID 123456789.
GraphQL
{
checkSubscriptionPlan(project_id: 123456789, coupon: "MY_COUPON") {
id
group
name
hasCustomLabels
hasCustomDomains
hasWhiteLabel
hasTeam
hasPrivacy
hasSubscriptions
hasFeedback
hasUserTracking
hasSegmentation
hasCustomCSS
hasIntegrations
hasPostCustomization
hasMultiLanguage
hasThemes
hasBoosters
hasSaml
hasIPAccessControl
hasEmailDigest
hasFeatureRequest
hasJiraIntegration
hasNotify
interval
price
setup_price
bullets
}
}
This query will return the following JSON:
JSON
{
"data": {
"checkSubscriptionPlan": [
{
"id": "essentialsv4",
"group": "essentials",
"name": "Essentials",
"hasCustomLabels": true,
"hasCustomDomains": false,
"hasWhiteLabel": false,
"hasTeam": false,
"hasPrivacy": false,
"hasSubscriptions": true,
"hasFeedback": true,
"hasUserTracking": false,
"hasSegmentation": false,
"hasCustomCSS": false,
"hasIntegrations": false,
"hasPostCustomization": true,
"hasMultiLanguage": false,
"hasThemes": false,
"hasBoosters": false,
"hasSaml": false,
"hasIPAccessControl": false,
"hasEmailDigest": false,
"hasFeatureRequest": false,
"hasJiraIntegration": false,
"hasNotify": false,
"interval": "month",
"price": XXXXX,
"setup_price": 0,
"bullets": [
"AI-Powered Post Editor",
"Grammarly Integration",
"Labels",
"Standalone Feed",
"Widgets",
"Comments & Reactions",
"Email Notifications",
"Basic Branding"
]
}
plans
Query
The plans query is a GraphQL query that returns all of the plans that are available. It is similar to "checkSubscriptionPlan"
Object
The Plan object that is returned by the plans query is a object with the following properties:
id(integer): The ID of the plan.group(string): The group of the plan.name(string): The name of the plan.hasCustomLabels(boolean): Whether the plan allows custom labels.hasCustomDomains(boolean): Whether the plan allows custom domains.hasWhiteLabel(boolean): Whether the plan allows white labeling.hasTeam(boolean): Whether the plan allows teams.hasPrivacy(boolean): Whether the plan allows privacy features.hasSubscriptions(boolean): Whether the plan allows subscriptions.hasFeedback(boolean): Whether the plan allows feedback.hasUserTracking(boolean): Whether the plan allows user tracking.hasSegmentation(boolean): Whether the plan allows segmentation.hasCustomCSS(boolean): Whether the plan allows custom CSS.hasIntegrations(boolean): Whether the plan allows integrations.hasPostCustomization(boolean): Whether the plan allows post customization.hasMultiLanguage(boolean): Whether the plan allows multi-language support.hasThemes(boolean): Whether the plan allows themes.hasBoosters(boolean): Whether the plan allows boosters.hasSaml(boolean): Whether the plan allows SAML.hasIPAccessControl(boolean): Whether the plan allows IP access control.hasEmailDigest(boolean): Whether the plan allows email digests.hasFeatureRequest(boolean): Whether the plan allows feature requests.hasJiraIntegration(boolean): Whether the plan allows Jira integration.hasNotify(boolean): Whether the plan allows notifications.interval(string): The billing interval for the plan.price(integer): The monthly price of the plan.setup_price(integer): The one-time setup price of the plan.bullets(array of strings): The bullets for the plan.
Examples
The following query will return all of the plans that are available.
GraphQL
{
plans {
id
group
name
hasCustomLabels
hasCustomDomains
hasWhiteLabel
hasTeam
hasPrivacy
hasSubscriptions
hasFeedback
hasUserTracking
hasSegmentation
hasCustomCSS
hasIntegrations
hasPostCustomization
hasMultiLanguage
hasThemes
hasBoosters
hasSaml
hasIPAccessControl
hasEmailDigest
hasFeatureRequest
hasJiraIntegration
hasNotify
interval
price
setup_price
bullets
}
}
This query will return the following JSON:
JSON
{
"plans": [
{
"id": 123456789,
"group": "Pro",
"name": "Pro Plan",
"hasCustomLabels": true,
"hasCustomDomains": true,
"hasWhiteLabel": true,
"hasTeam": true,
"hasPrivacy": true,
"hasSubscriptions": true,
"hasFeedback": true,
"hasUserTracking": true,
"hasSegmentation": true,
"hasCustomCSS": true,
"hasIntegrations": true,
"hasPostCustomization": true,
"hasMultiLanguage": true,
"hasThemes": true,
"hasBoosters
invoices
Query
The invoices query is a GraphQL query that returns all of the invoices for a project.
Object
The Invoice object that is returned by the invoices query is a object with the following properties:
id(integer): The ID of the invoice.amount(integer): The amount of the invoice.created_at(date): The date the invoice was created.paid(boolean): Whether the invoice has been paid.pdf(string): The URL of the PDF of the invoice.
Examples
The following query will return all of the invoices for the project with the ID 123456789.
GraphQL
{
invoices(project_id: 123456789) {
id
amount
created_at
paid
pdf
}
}
This query will return the following JSON:
JSON
{
"invoices": [
{
"id": 123456789,
"amount": 100,
"created_at": "2023-07-01T00:00:00Z",
"paid": true,
"pdf": "https://example.com/invoices/123456789.pdf"
},
{
"id": 987654321,
"amount": 50,
"created_at": "2023-06-30T00:00:00Z",
"paid": false,
"pdf": "https://example.com/invoices/987654321.pdf"
}
]
}
projectLocale
Query
The projectLocale query is a GraphQL query that returns a project locale.
Object
The ProjectLocale object that is returned by the projectLocale query is a object with the following properties:
id(integer): The ID of the project locale.project_id(integer): The ID of the project.locale_id(integer): The ID of the locale.overrides(array ofLocaleEntryobjects): The overrides for the locale.project(object): The project object.locale(object): The locale object.
Object
The LocaleEntry object that is returned by the projectLocale query is a object with the following properties:
key(string): The key of the locale entry.value(string): The value of the locale entry.
Examples
The following query will return the project locale for the project with the ID 123456789 and the locale ID 987654321.
GraphQL
{
projectLocale(project_id: 123456789, locale_id: 987654321) {
id
project_id
locale_id
overrides
project
locale
}
}
This query will return the following JSON:
JSON
{
"projectLocale": {
"id": 123456789,
"project_id": 123456789,
"locale_id": 987654321,
"overrides": [
{
"key": "app_name",
"value": "My Project (Spanish)"
},
{
"key": "hello_world",
"value": "Hola, mundo!"
}
],
"project": {
"id": 123456789,
"name": "My Project",
"slug": "my-project",
"description": "This is my project."
},
"locale": {
"id": 987654321,
"code": "es",
"name": "Spanish"
}
}
}
projectLocales
Query
The projectLocales query is a GraphQL query that returns all of the project locales for a project.
Object
The ProjectLocale object that is returned by the projectLocales query is a object with the following properties:
id(integer): The ID of the project locale.project_id(integer): The ID of the project.locale_id(integer): The ID of the locale.overrides(array ofLocaleEntryobjects): The overrides for the locale.project(object): The project object.locale(object): The locale object.
Object
The LocaleEntry object that is returned by the projectLocales query is a object with the following properties:
key(string): The key of the locale entry.value(string): The value of the locale entry.
Examples
The following query will return all of the project locales for the project with the ID 123456789.
GraphQL
{
projectLocales(project_id:123456789) {
id
project {
id
}
project_id
locale_id
locale {
id
}
}
}
This query will return the following JSON:
JSON
{
"data": {
"projectLocales": [
{
"id": "3-en",
"project": {
"id": "3"
},
"project_id": "3",
"locale_id": "en",
"locale": {
"id": "en"
}
}
]
}
}
projectWebhooks
Query
The projectWebhooks query is a GraphQL query that returns all of the project webhooks for a project.
Object
The ProjectWebhook object that is returned by the projectWebhooks query is a object with the following properties:
id(integer): The ID of the project webhook.project_id(integer): The ID of the project.is_enabled(boolean): Whether the webhook is enabled.url(string): The URL of the webhook.
Examples
The following query will return all of the project webhooks for the project with the ID 123456789.
GraphQL
{
projectWebhooks(project_id: 123456789) {
id
project_id
is_enabled
url
}
}
This query will return the following JSON:
JSON
{
"projectWebhooks": [
{
"id": 123456789,
"project_id": 123456789,
"is_enabled": true,
"url": "https://example.com/webhooks/my-project"
},
{
"id": 234567890,
"project_id": 123456789,
"is_enabled": false,
"url": "https://example.com/webhooks/my-project-2"
}
]
}
samlConfig
Query
The samlConfig query is a GraphQL query that returns the SAML configuration for a project.
Object
The SAMLConfig object that is returned by the samlConfig query is a object with the following properties:
id(integer): The ID of the SAML configuration.project_id(integer): The ID of the project.route(string): The route for the SAML SSO endpoint.login_url(string): The URL of the SAML IDP login page.certificate(string): The certificate for the SAML IDP.domain(string): The domain of the SAML IDP.is_domain_verified(boolean): Whether the domain has been verified.verify_token(string): The token for verifying the domain.
Examples
The following query will return the SAML configuration for the project with the ID 123456789.
GraphQL
{
samlConfig(project_id: 123456789) {
id
project_id
route
login_url
certificate
domain
is_domain_verified
verify_token
}
}
This query will return the following JSON:
JSON
{
"samlConfig": {
"id": 123456789,
"project_id": 123456789,
"route": "/saml/login",
"login_url": "https://idp.example.com/sso/saml2/login",
"certificate": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
"domain": "example.com",
"is_domain_verified": true,
"verify_token": "1234567890"
}
}
samlLoginURL
Query
The samlLoginURL query is a GraphQL query that returns the SAML login URL for a domain.
Object
The SAMLConfig object that is returned by the samlLoginURL query is a string with the following properties:
login_url(string): The URL of the SAML IDP login page.
Examples
The following query will return the SAML login URL for the domain example.com.
GraphQL
{
samlLoginURL(domain: "example.com")
}
JSON
{
"samlLoginURL": "https://idp.example.com/sso/saml2/login"
}
projectSecret
Query
The projectSecret query is a GraphQL query that returns the project secret for a project.
Object
The ProjectSecret object that is returned by the projectSecret query is a string with the following properties:
secret(string): The project secret.
Examples
The following query will return the project secret for the project with the ID 123456789.
GraphQL
{
projectSecret(project_id: 123456789)
}
This query will return the following JSON:
JSON
{
"secret": "my-secret-key"
}
Note: The project secret is a randomly generated string that is used to authenticate requests to the project's API. It is important to keep the project secret secret!
locale
Query
The locale query is a GraphQL query that returns a locale.
Object
The Locale object that is returned by the locale query is a object with the following properties:
id(integer): The ID of the locale.name(string): The name of the locale.entries(array ofLocaleEntryobjects): The entries for the locale.
Object
The LocaleEntry object that is returned by the locale query is a object with the following properties:
key(string): The key of the locale entry.value(string): The value of the locale entry.
Examples
The following query will return the locale with the ID 123456789.
GraphQL
{
locale(locale_id: 123456789) {
id
name
entries
}
}
This query will return the following JSON:
JSON
{
"locale": {
"id": 123456789,
"name": "Spanish",
"entries": [
{
"key": "app_name",
"value": "Mi Proyecto"
},
{
"key": "hello_world",
"value": "Hola, mundo!"
}
]
}
}
locales
Query
The locales query is a GraphQL query that returns all of the locales.
Object
The Locale object that is returned by the locales query is a object with the following properties:
id(integer): The ID of the locale.name(string): The name of the locale.entries(array ofLocaleEntryobjects): The entries for the locale.
Object
The LocaleEntry object that is returned by the locales query is a object with the following properties:
key(string): The key of the locale entry.value(string): The value of the locale entry.
Examples
The following query will return all of the locales:
GraphQL
{
locales {
id
name
}
}
This query will return the following JSON:
JSON
{
"data": {
"locales": [
{
"id": "en",
"name": "English"
},
{
"id": "gb",
"name": "English (en-GB)"
},
{
"id": "de",
"name": "Deutsch"
},
}
]
}
}
users
Query
The users query is a GraphQL query that returns all of the users.
Object
The User object that is returned by the users query is a object with the following properties:
id(integer): The ID of the user.hash(string): The hash of the user's password.email(string): The email address of the user.display_name(string): The display name of the user.title(string): The title of the user.created_at(date): The date the user was created.image_id(integer): The ID of the user's image.image(object): The user's image.active_project(object): The user's active project.memberships(array ofProjectMemberobjects): The user's memberships.avatar(string): The user's avatar.is_validated(boolean): Whether the user has been validated.is_totp_enabled(boolean): Whether the user has two-factor authentication enabled.is_unsubs(boolean): Whether the user has unsubscribed from emails.
Examples
The following query will return all of the users.
GraphQL
{
users(page: 0) {
id
hash
email
display_name
title
created_at
image_id
image
active_project
memberships
avatar
is_validated
is_totp_enabled
is_unsubs
}
}
This query will return the following JSON:
JSON
{
"users": [
{
"id": 123456789,
"hash": "some-hash",
"email": "[email protected]",
"display_name": "John Doe",
"title": "Software Engineer",
"created_at": "2023-07-17T00:00:00Z",
"image_id": 123456789,
"image": {
"id": 123456789,
"filename": "avatar.png",
"url": "https://example.com/avatars/123456789.png"
},
"active_project": {
"id": 123456789,
"name": "My Project"
},
"memberships": [
{
"project_id": 123456789,
"role": "Owner"
},
{
"project_id": 987654321,
"role": "Member"
}
],
"avatar": "https://example.com/avatars/123456789.png",
"is_validated": true,
"is_totp_enabled": false,
"is_unsubs": false
},
{
"id": 987654321,
"hash": "some-other-hash",
"email": "[email protected]",
"display_name": "Jane Doe",
"title": "Product Manager",
"created_at": "2023-07-16T00:00:00Z",
"image_id": 987654321,
"image": {
"id": 987654321,
"filename": "avatar2.png",
"url": "https://example.com/avatars/987654321.png"
},
"active_project": {
"id": 98765
checkActiveFeatures
Query
The checkActiveFeatures query is a GraphQL query that returns the active features for a project.
Object
The Features object that is returned by the checkActiveFeatures query is a object with the following properties:
hasCustomLabels(boolean): Whether the project has custom labels enabled.hasCustomDomains(boolean): Whether the project has custom domains enabled.hasWhiteLabel(boolean): Whether the project has white labeling enabled.hasTeam(boolean): Whether the project has teams enabled.hasPrivacy(boolean): Whether the project has privacy features enabled.hasSubscriptions(boolean): Whether the project has subscriptions enabled.hasFeedback(boolean): Whether the project has feedback enabled.hasUserTracking(boolean): Whether the project has user tracking enabled.hasSegmentation(boolean): Whether the project has segmentation enabled.hasCustomCSS(boolean): Whether the project has custom CSS enabled.hasIntegrations(boolean): Whether the project has integrations enabled.hasPostCustomization(boolean): Whether the project has post customization enabled.hasMultiLanguage(boolean): Whether the project has multi-language support enabled.hasThemes(boolean): Whether the project has themes enabled.hasBoosters(boolean): Whether the project has boosters enabled.hasEmailDigest(boolean): Whether the project has email digests enabled.hasFeatureRequest(boolean): Whether the project has feature requests enabled.hasJiraIntegration(boolean): Whether the project has Jira integration enabled.hasNotify(boolean): Whether the project has notifications enabled.
Examples
The following query will return the active features for the project with the ID 123456789.
GraphQL
{
checkActiveFeatures(project_id: 123456789) {
hasThemes {
value
}
hasPrivacy {
value
}
hasBoosters {
value
}
}
}
This query will return the following JSON:
JSON
{
"data": {
"checkActiveFeatures": {
"hasThemes": {
"value": true
},
"hasPrivacy": {
"value": false
},
"hasBoosters": {
"value": false
}
}
}
}
onboarding
Query
The onboarding query is a GraphQL query that returns the onboarding progress for a project.
Object
The Onboarding object that is returned by the onboarding query is a object with the following properties:
progress(integer): The current progress of the onboarding process.items(array ofOnboardingStepobjects): The onboarding steps.
Object
The OnboardingStep object that is returned by the onboarding query is a object with the following properties:
step_key(string): The unique identifier of the onboarding step.index(integer): The index of the onboarding step.is_done(boolean): Whether the onboarding step has been completed.is_active(boolean): Whether the onboarding step is active.title(string): The title of the onboarding step.description(string): The description of the onboarding step.target_url(array ofQuickStartControllersobjects): The URLs of the resources for the onboarding step.time(string): The estimated time to complete the onboarding step.
Examples
The following query will return the onboarding progress for the project with the ID 123456789.
GraphQL
{
onboarding(project_id: 123456789) {
progress
items {
step_key
index
is_done
is_active
title
description
target_url {
forceReload
error
}
time
}
}
}
This query will return the following JSON:
JSON
{
"data": {
"onboarding": {
"progress": 4,
"items": [
{
"step_key": "post_create",
"index": 0,
"is_done": true,
"is_active": false,
"title": "Draft your first announcement",
"description": "New feature? Bug fix? Improvement? Whatever it is, leverage the power of AI to manage ideas & solutions with your users.",
"target_url": [
{
"forceReload": null,
"error": null
},
{
"forceReload": true,
"error": null
}
],
"time": "2 min"
},
{
"step_key": "customize_feed",
"index": 1,
"is_done": true,
"is_active": false,
"title": "Customize your standalone feed page",
"description": "Set up your feed page according to your needs. Stand out from the crowd and reflect your brand with your own designs and colors.",
"target_url": [
{
"forceReload": null,
"error": null
}
],
"time": "3 min"
},
{
"step_key": "widget_create",
"index": 2,
"is_done": true,
"is_active": false,
"title": "Create a widget to display announcements",
"description": "Set up a widget to make sure your announcements reach your users in the right place, at the right time. No coding required.",
"target_url": [
{
"forceReload": null,
"error": null
},
{
"forceReload": null,
"error": null
}
],
"time": "4 min"
},
{
"step_key": "team_invite",
"index": 3,
"is_done": true,
"is_active": false,
"title": "Invite your teammates",
"description": "Invite your teammates and colleagues to work together on this project.",
"target_url": [
{
"forceReload": null,
"error": null
}
],
"time": "2 min"
},
{
"step_key": "project_update",
"index": 4,
"is_done": false,
"is_active": true,
"title": "Update project settings",
"description": "Check the project settings and update them according to your needs & requirements. That way there are no surprises.",
"target_url": [
{
"forceReload": null,
"error": null
}
],
"time": "2 min"
}
]
}
}
}
emailConfig
Query
The emailConfig query is a GraphQL query that returns the email digest configuration for a project.
Object
The EmailConfig object that is returned by the emailConfig query is a object with the following properties:
project_id(integer): The ID of the project.send_day(integer): The day of the week to send emails.sending_interval(string): The interval between email sends.filter_labels(array ofStringobjects): The labels to filter emails by.include_labels(array ofStringobjects): The labels to include emails by.include_segmented_posts(boolean): Whether to include segmented posts in emails.post_content_type(string): The type of content to include in emails.last_send_date(date): The date of the last email send.is_enabled(boolean): Whether email notifications are enabled.
Examples
The following query will return the email configuration for the project with the ID 123456789.
GraphQL
{
emailConfig(project_id: 3) {
project_id
send_day
sending_interval
filter_labels
include_labels
include_segmented_posts
post_content_type
last_send_date
is_enabled
}
}
JSON
{
"data": {
"emailConfig": {
"project_id": "123456789",
"send_day": 3,
"sending_interval": "monthly",
"filter_labels": [],
"include_labels": [],
"include_segmented_posts": true,
"post_content_type": "summary",
"last_send_date": "2023-06-01T00:00:00.000Z",
"is_enabled": true
}
}
}
projectEmailSenderConfig
Query
The projectEmailSenderConfig query is a GraphQL query that returns the email sender configuration for a project.
Object
The ProjectEmailSenderConfig object that is returned by the projectEmailSenderConfig query is a object with the following properties:
project_id(integer): The ID of the project.provider(string): The email sender provider.sender_name(string): The sender name.sender_email(string): The sender email address.sender_domain(string): The sender domain.provider_endpoint(string): The provider endpoint.provider_api_key(string): The provider API key.provider_username(string): The provider username.provider_password(string): The provider password.email_reply_to(string): The email reply-to address.
Examples
The following query will return the email sender configuration for the project with the ID 123456789.
GraphQL
{
projectEmailSenderConfig(project_id: 123456789) {
project_id
provider
sender_name
sender_email
sender_domain
provider_endpoint
provider_api_key
provider_username
provider_password
email_reply_to
}
}
This query will return the following JSON:
JSON
{
"projectEmailSenderConfig": {
"project_id": 123456789,
"provider": "Mailgun",
"sender_name": "Bard Team",
"sender_email": "[email protected]",
"sender_domain": "example.com",
"provider_endpoint": "https://api.mailgun.com/v3/example.com",
"provider_api_key": "abc123",
"provider_username": "bard",
"provider_password": "secret",
"email_reply_to": "[email protected]"
}
}
projectRoadmapConfig
Query
The projectRoadmapConfig query is a GraphQL query that returns the roadmap configuration for a project.
Object
The ProjectRoadmapConfig object that is returned by the projectRoadmapConfig query is a object with the following properties:
project_id(integer): The ID of the project.title(string): The title of the roadmap.is_enabled(boolean): Whether the roadmap is enabled.is_hidden_in_feed(boolean): Whether the roadmap is hidden in the feed.is_hidden_in_widget(boolean): Whether the roadmap is hidden in the widget.
Examples
The following query will return the roadmap configuration for the project with the ID 123456789.
GraphQL
{
projectRoadmapConfig(project_id: 1234456789) {
project_id
title
is_enabled
is_hidden_in_feed
is_hidden_in_widget
}
}
This query will return the following JSON:
JSON
{
"data": {
"projectRoadmapConfig": {
"project_id": "3",
"title": null,
"is_enabled": true,
"is_hidden_in_feed": false,
"is_hidden_in_widget": false
}
}
}
projectFeatureRequestConfig
Query
The projectFeatureRequestConfig query is a GraphQL query that returns the feature request configuration for a project.
Object
The ProjectFeatureRequestConfig object that is returned by the projectFeatureRequestConfig query is a object with the following properties:
project_id(integer): The ID of the project.is_enabled(boolean): Whether feature requests are enabled.is_hidden_in_feed(boolean): Whether feature requests are hidden in the feed.is_hidden_in_widget(boolean): Whether feature requests are hidden in the widget.is_approvement_enabled(boolean): Whether feature requests require approval.is_default_status_private(boolean): Whether feature requests are private by default.is_comments_public(boolean): Whether comments on feature requests are public.button_name(string): The text of the feature request button.
Examples
The following query will return the feature request configuration for the project with the ID 123456789.
GraphQL
{
projectFeatureRequestConfig(project_id: 123456789) {
project_id
is_enabled
is_hidden_in_feed
is_hidden_in_widget
is_approvement_enabled
is_default_status_private
is_comments_public
button_name
}
}
This query will return the following JSON:
JSON
{
"projectFeatureRequestConfig": {
"project_id": 123456789,
"is_enabled": true,
"is_hidden_in_feed": false,
"is_hidden_in_widget": false,
"is_approvement_enabled": true,
"is_default_status_private": false,
"is_comments_public": true,
"button_name": "Request a Feature"
}
}
projectWarnings
Query
The projectWarnings query is a GraphQL query that returns all of the warnings for a project.
Object
The ProjectWarning object that is returned by the projectWarnings query is a object with the following properties:
id(integer): The ID of the warning.created_at(date): The date the warning was created.project_id(integer): The ID of the project.event_vars(JSON object): The event variables that triggered the warning.
Examples
The following query will return all of the warnings for the project with the ID 123456789.
GraphQL
{
projectWarnings(project_id: 123456789) {
id
created_at
project_id
event_vars
}
}
This query will return the following JSON:
JSON
{
"projectWarnings": [
{
"id": 1,
"created_at": "2023-07-17T00:00:00Z",
"project_id": 123456789,
"event_vars": {
"warning_type": "invalid_label_name",
"label_name": "invalid-label-name"
}
},
{
"id": 2,
"created_at": "2023-07-17T00:00:01Z",
"project_id": 123456789,
"event_vars": {
"warning_type": "invalid_post_content",
"post_content": "This post contains invalid content."
}
}
]
}
projectMagicInviteLink
Query
The projectMagicInviteLink query is a GraphQL query that returns the magic invite link for a project.
Object
The ProjectMagicInviteLink object that is returned by the projectMagicInviteLink query is a string that represents the magic invite link for the project.
Examples
The following query will return the magic invite link for the project with the ID 123456789.
GraphQL
{
projectMagicInviteLink(project_id: 123456789)
}
This query will return the following string:
https://example.com/join/123456789
Note: The magic invite link is a unique URL that can be used to invite users to join a project. The link will expire after a certain amount of time.
previewPost
Query
The previewPost query is a GraphQL query that previews a post.
Object
The PreviewPost object that is returned by the previewPost query is a JSON object that contains the following properties:
locale_id(string): The locale ID of the post.title(string): The title of the post.body(string): The body of the post.summary(string): The summary of the post.name(string): The name of the post.image_id(integer): The ID of the image for the post.labels(array of integers): The IDs of the labels for the post.flags(array of strings): The flags for the post.
Examples
The following query will preview a post with the following content:
query {
previewPost(project_id: 3, content: { locale_id: "en_US", title: "My Title", body: "Post body", summary: "Post summary" })
}
This query will return the following JSON object:
JSON
{
"locale_id": "en-US",
"title": "My Post Title",
"body": "This is the body of my post.",
"summary": "This is the summary of my post.",
"name": "My Post Name",
"image_id": 123456789,
"labels": [1, 2, 3],
"flags": ["draft", "private"]
}
Note: The previewPost query does not actually create a post. It simply returns a preview of what the post would look like if it were created.
statuses
Query
The statuses query is a GraphQL query that returns all of the statuses of the Feature Request for a project.
Object
The Status object that is returned by the statuses query is a object with the following properties:
id(integer): The ID of the status.name(string): The name of the status.color(string): The color of the status.
Examples
The following query will return all of the statuses for the project with the ID 123456789.
GraphQL
{
statuses(project_id: 123456789) {
id
name
color
}
}
This query will return the following JSON:
JSON
{
"statuses": [
{
"id": 1,
"name": "Open",
"color": "#337ab7"
},
{
"id": 2,
"name": "In Progress",
"color": "#97ca86"
},
{
"id": 3,
"name": "Done",
"color": "#43a047"
}
]
}
issues
Query
The issues query is a GraphQL query that returns all of the live Roadmap items for a project.
Object
The Issues object that is returned by the issues query is a object with the following properties:
list(array ofIssueobjects): The list of issues.count(integer): The total number of issues.page(integer): The current page number.pages(integer): The total number of pages.
Object
The Issue object that is returned by the issues query is a object with the following properties:
id(integer): The ID of the issue.created_at(date): The date the issue was created.updated_at(date): The date the issue was updated.status_id(integer): The ID of the status for the issue.status(Status object): The status for the issue.title(string): The title of the issue.summary(string): The summary of the issue.due_at(date): The due date for the issue.sort_index(integer): The sort index for the issue.user_id(integer): The ID of the user who created the issue.user(User object): The user who created the issue.labels(array ofIssueLabelobjects): The labels for the issue.
Examples
The following query will return all of the issues for the project with the ID 123456789.
GraphQL
{
issues(project_id: 29289) {
list {
id
created_at
updated_at
status_id
status {
id
}
title
summary
due_at
sort_index
user_id
user {
id
}
labels {
label_id
}
}
count
page
pages
}
}
This query will return the following JSON:
JSON
{
"data": {
"issues": {
"list": [
{
"id": "1884",
"created_at": "2023-07-17T20:49:23.248Z",
"updated_at": "2023-07-17T20:49:23.248Z",
"status_id": "2645",
"status": {
"id": "2645"
},
"title": "Testing",
"summary": "This is a live example in a Roadmap",
"due_at": "2023-07-16T21:00:00.000Z",
"sort_index": 0,
"user_id": "15924",
"user": {
"id": "15924"
},
"labels": [
{
"label_id": "47061"
}
]
}
],
"count": 1,
"page": 0,
"pages": 1
}
}
}
feature¨Requests
Query
The featureRequests query is a GraphQL query that returns all of the feature requests for a project.
Object
The FeatureRequests object that is returned by the featureRequests query is a object with the following properties:
list(array ofFeatureRequestobjects): The list of feature requests.count(integer): The total number of feature requests.page(integer): The current page number.pages(integer): The total number of pages.
Object
The FeatureRequest object that is returned by the featureRequests query is a object with the following properties:
id(integer): The ID of the feature request.project_id(integer): The ID of the project the feature request belongs to.project(Project object): The project the feature request belongs to.created_at(date): The date the feature request was created.updated_at(date): The date the feature request was updated.user_id(integer): The ID of the user who created the feature request.user(User object): The user who created the feature request.external_user_id(string): The ID of the external user who created the feature request, if applicable.external_user(ExternalUser object): The external user who created the feature request, if applicable.title(string): The title of the feature request.summary(string): The summary of the feature request.is_deleted(boolean): Whether the feature request has been deleted.is_archived(boolean): Whether the feature request has been archived.is_internal(boolean): Whether the feature request is internal.is_approved(boolean): Whether the feature request has been approved.is_voting_enabled(boolean): Whether voting is enabled for the feature request.is_commenting_enabled(boolean): Whether commenting is enabled for the feature request.user_info(UserInfo object): The user information for the user who created the feature request.issue_id(integer): The ID of the issue associated with the feature request, if applicable.stats(FeatureRequestStats object): The statistics for the feature request.comments(array ofFeatureRequestCommentobjects): The comments for the feature request.votes(array ofFeatureRequestVoteobjects): The votes for the feature request.labels(array ofFeatureRequestLabelobjects): The labels for the feature request.
Examples
The following query will return all of the feature requests for the project with the ID 123456789.
GraphQL
{
featureRequests(project_id:123456789,sort_by:TOP,sort_order:DESC) {
list {
id
user_id
title
}
count
page
pages
}
}
This query will return the following JSON:
JSON
{
"featureRequests": {
"list": [
{
"id": 1,
"user_id": 1,
"title": "My Top Feature Request"
},
{
"id": 2,
"user_id": 2,
"title": "Another Great Feature Request"
},
{
"id": 3,
"user_id": 3,
"title": "This Feature Request is Really Good"
}
],
"count": 3,
"page": 1,
"pages": 1
}
}
projectMembers
Query
The projectMembers query is a GraphQL query that returns all of the project members for a project.
Object
The ProjectMembers object that is returned by the projectMembers query is a object with the following properties:
list(array ofProjectMemberobjects): The list of project members.
Object
The ProjectMember object that is returned by the projectMembers query is a object with the following properties:
id(integer): The ID of the project member.user_id(integer): The ID of the user who is a project member.project_id(integer): The ID of the project the user is a project member for.user(User object): The user who is a project member.project(Project object): The project the user is a project member for.member_role(string): The role of the project member.
Examples
The following query will return all of the project members for the project with the ID 123456789.
GraphQL
{
projectMembers(project_id: 123456789) {
id
user_id
project_id
user {
id
}
project {
id
}
member_role
}
}
This query will return the following JSON:
JSON
{
"data": {
"projectMembers": [
{
"id": "12345",
"user_id": "12345",
"project_id": "12345",
"user": {
"id": "12345"
},
"project": {
"id": "12345"
},
"member_role": "owner"
}
]
}
}
getProjectDetails
Query
The getProjectDetails query is a GraphQL query that returns the details of a project.
Object
The ProjectDetails object that is returned by the getProjectDetails query is a object with the following properties:
id(integer): The ID of the project.project_id(integer): The ID of the project.url(string): The URL of the project.description(string): The description of the project.user_persona(string): The user persona of the project.
Examples
The following query will return the details of the project with the ID 123456789.
GraphQL
{
getProjectDetails(project_id: 123456789) {
id
project_id
url
description
user_persona
}
}
This query will return the following JSON:
JSON
{
"data": {
"getProjectDetails": {
"id": "123456",
"project_id": "123456789",
"url": "https://announcekit.app",
"description": "AnnounceKit is a software solution that enables businesses to communicate updates, releases, and news directly to their users. With AnnounceKit, companies can create and publish customizable announcements on their website, in-app, or via email. The platform offers features such as audience targeting, feedback collection, and analytics to help businesses understand how their announcements are being received.",
"user_persona": "AnnounceKit is ideal for SaaS companies, eCommerce businesses, and other online platforms looking to improve their user experience and keep their customers informed about the latest updates and changes. The tool is also suitable for marketing teams and product managers who need a streamlined way to communicate with their users."
}
}
}
getNotification
Query
The getNotification query is a GraphQL query that returns a notification of a specified post.
Object
The Notification object that is returned by the getNotification query is a object with the following properties:
id(integer): The ID of the notification.project_id(integer): The ID of the project the notification is for.post_id(integer): The ID of the post the notification is for.type(string): The type of the notification.content(string): The content of the notification.created_at(date): The date the notification was created.url(string): The URL of the notification.is_read(boolean): Whether the notification has been read.
Examples
The following query will return the notification with the ID 123456789.
GraphQL
{
getNotification(project_id: 3, post_id: 349722) {
id
project_id
post_id
type
url
}
}
This query will return the following JSON:
JSON
{
"notification": {
"id": 1,
"project_id": 3,
"post_id": 349722,
"type": "new_comment",
"url": "https://my-project.bard.ai/posts/349722#comment-1"
}
}