Mutations

GraphQL mutations create and modify objects, similar to a PUT, POST, or DELETE request in REST. Mutation requests are sent to the same endpoint as query requests.

A list of all mutations available on Bettermode's GraphQL API is available here under Mutations section.

note

All requests to Bettermode's GraphQL endpoint should be authenticated using App Access Token or Member Access Token.

Mutations Structure

Mutations have the following structure:

• The mutation operation name
• The mutation field name, such as addSpace
• The input data to use in the mutation passed as an argument, such as the information for a new space
• A selection of return fields that should be included in the response, such as the ID of the successfully created Space object

Mutation Structure

mutation {
  mutationName(arg: "Data") {
    # return fields
  }
}

info

If your community is hosted on a region other than the US region (us-east-1), you should use a different GraphQL URL as stated here under the GraphQL Endpoint section.

Input objects

Mutations require input data, such as the data to create a new object, or the ID of an object to delete. For mutations that might require a substantial data object, the schema provides a dedicated input object type.

For example, the createSpace mutation requires an input argument, which accepts a CreateSpaceInput object. The CreateSpaceInput type defines all the fields that can be used to create or modify a space.

mutation {
  createSpace(
    input: {
      name: "Product Updates"
      collectionId: "p15Q7zycbml0"
    }
  ) {
    # ...
  }
}

note

We will cover what collectionId id later in this guide.

Return fields

Each mutation provides a set of fields that can be returned in the response. For example, one of the return fields available for the createSpace mutation is the Space object that was created by a successful mutation. Similar to a GraphQL query, you can select the fields on the new object that you want to include in the response.

mutation {
  createSpace(input: {
    # ...
  }) {
    id
    name
    slug
  }
}

Create a space

The following mutation uses input objects and return fields to create a new space and return their ID, name, and slug.

mutation {
  createSpace(
    input: {
      name: "Product Updates"
      collectionId: "p15Q7zycbml0"
    }
  ) {
    id
    name
    slug
  }
}

JSON Response

{
  "data": {
    "createSpace": {
      "id": "qgmFho8F6jlA",
      "name": "Product Updates",
      "slug": "product-updates-fw15x39k"
    }
  }
}