GraphQL API

The GraphQL API gives you full creative control of AnnounceKit to build customized solutions for your application.

Client

The API can be explored by using the GraphiQL IDE.

Endpoint

The GraphQL API has a single endpoint that returns flexible data structures, and it remains constant no matter what operation you perform.
https://announcekit.app/gq/v2

Authentication

To communicate with the GraphQL API, you need to supply Basic Authentication token in request Header, or you can use your login Cookies (sesid, sesid.sig).
After singing-in to Dashboard, you can use GraphiQL IDE without supplying Basic Authentication token or any Cookies.

Rate Limiting

The GraphQL API uses IP-based rate limiting to protect against abuse and ensure fair usage. By default, the API allows 60 requests per minute per IP address.

Rate Limit Headers

Every API response includes the following headers:

• X-RateLimit-Limit: The maximum number of requests allowed per time window
• X-RateLimit-Remaining: The number of requests remaining in the current time window

Rate Limit Exceeded

If you exceed the rate limit, the API will return a 429 Too Many Requests status code with the following error response:

{
  "errors": [{
    "message": "Too many requests. Please slow down.",
    "extensions": {
      "code": "RATE_LIMITED",
      "limit": 60,
      "remaining": 0
    }
  }]
}

Best Practices

• Monitor the X-RateLimit-Remaining header to track your usage
• Implement exponential backoff when you receive a 429 response
• Cache responses when possible to reduce API calls
• Use authenticated requests from the official dashboard for unlimited access

Reference

API Reference is automatically generated from GraphQL schema and can be explored from GraphiQL IDE’s Documentation Explorer section.

Tutorial

How to create a post with the GraphQL API?

Creating AnnounceKit post using GrapQL API is very easy.
Initially, make sure that you have created a project and authenticated to the GraphQL API.

Step 1. Get project id

Firstly, You need the id of the project. You’ll use it to retrieve labels and create a post.

Run Query

{
  me {
    active_project {
      id
      name
    }
  }
}

As a result, you get the id and name of the project. Please check the name field to make sure that you have the correct project.

{
  "data": {
    "me": {
      "active_project": {
        "id": "2672",
        "name": "Awesome App"
      }
    }
  }
}

Step 2 (Optional). Get labels

If you want to attach labels to the post, you need id of the label. Labels in the post are optional.

Run Query

{
  labels(project_id: 2672) {
    id
    name
  }
}

Here you get a list of the labels that you have created and the default ones. You’ll use these id fields in the following step.

{
  "data": {
    "labels": [
      {
        "id": "5442",
        "name": "fix"
      },
      {
        "id": "5443",
        "name": "announcement"
      },
      {
        "id": "5444",
        "name": "improvement"
      }
    ]
  }
}

Step 3. Publish post

At this step, you’ll combine all the values that you get and finally create a post.

These arguments are required project_id, and contents. The contents argument is an array of PostContent object which consists of title, body, locale_id.

You can use some basic HTML tags in the body argument. By default, a post will be created as a draft, so if you want to publish it, please set is_draft argument as false.

Please check API Reference for all mutation savePost arguments and detailed usage.

Run Query

mutation {
  savePost(project_id: 2672, contents: [{title: "Hello World", body: "<h2>Hello World</h2>", locale_id: "en"}], is_draft: false) {
    id
  }
}

As a query result, you get the id of the created post.

Feel free to write us in chat, or email to [email protected] if you need any assistance or have questions.