GraphQL API

Overview

Flat's API lets you read and write your organization's data programmatically. You can use it to import data into Flat, generate custom reports, build automations driven by events in other apps, and more.

The API is based on GraphQL. Unlike a REST API, a GraphQL API has just a single endpoint for all requests, both reads and writes, and it gives you full control over the shape of the data you get in response. If you're new to GraphQL, we recommend checking out the official GraphQL documentation to learn the basics.

The API is currently in beta and undergoing rapid development. We don't expect there to be breaking changes, but if there are, we'll keep you in the loop.

Endpoint and schema

Flat's GraphQL API endpoint is:

https://api.flat.app/v1/beta/graphql

The endpoint supports GraphQL introspection, so the easiest way to explore the API schema and take it for a spin is via a GraphQL client.

Alternatively, you can view the schema here in SDL format.

If you don't already have a preferred GraphQL client, we recommend checking out Insomnia, Postman, or GraphiQL.

Authentication and authorization

You authenticate to the API using a bearer token. Just include the HTTP Authorization header in all of your API requests:

Authorization: Bearer YOUR_API_TOKEN

Currently, the API supports personal access tokens. A personal access token is tied to a particular user. It has access to the same workspaces and topics as the user, and any mutations using it are attributed to the user.

To request your personal access token, reach out to us through one of our support channels.

Operations

The API supports two kinds of operations: queries and mutations.

Queries

Queries fetch data from your organization and are read-only. The API supports:

  • Fetching individual objects by ID, e.g., getting a specific topic

  • Listing whole classes of objects, e.g., all accessible workspaces in your organization

  • Traversing the relationships between objects, e.g., getting a topic along with its labels, owner, collaborators, etc.

Mutations

Mutations modify data in your organization, such as creating or updating a topic. Every mutation returns a reference to the object that was created or updated. That way, you can retrieve information about the mutated object, such as getting a newly created object's system-generated ID.

Making your first request

Request

To make a request to the API, just issue a POST request with a JSON object as the body, structured like this:

{
  "query": "query { ... }",
  "variables": { "variable1": "value1", "variable2": "value2" }
}

The properties are:

  • query: required property that contains a GraphQL document describing one or more operations (queries or mutations)

  • variables: optional property that contains a mapping of variables and values to substitute into the GraphQL document

Below is an example JSON body requesting a topic's description and title, using a variable for the topic ID.

{
  "query": "query($id: ID!) { topic(id: $id) { description title } }",
  "variables": { "id": "TOPIC_ID" }
}

Here's an example of a complete request that retrieves info about all accessible topics in your organization.

curl --request POST \
  --url https://api.flat.app/v1/beta/graphql \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --data '{"query":"query { topics { nodes { id description title owner { id displayName } } } }"}'

Response

In GraphQL, the response data is always structured to match the shape of your request.

In the example request above, the response would look like this:

{
  "data": {
    "topics": {
      "nodes": [
        {
          "id": "TOPIC_ID_1",
          "description": null,
          "title": "Title of the topic",
          "owner": null
        },
        {
          "id": "TOPIC_ID_2",
          "description": "Description of the topic",
          "title": "Title of the topic",
          "owner": {
            "id": "USER_ID_1",
            "displayName": "Foobar"
          }
        }
      ]
    }
  }
}

Examples

Below are some example GraphQL documents for common use cases.

Keep in mind:

  • These are example GraphQL documents, not complete API requests. See Making your first request to form a complete API request from a GraphQL document.

  • In these examples, the values are hard-coded into the GraphQL document for illustration. However, you'll typically want to use variables to parameterize your queries and mutations for easy reuse.

To see all of the queries and mutations that the API supports, instrospect the API using a GraphQL client like Insomnia, Postman, or GraphiQL.

Queries

Fetching info about workspaces and their stages

query {
  workspaces {
    nodes {
      id
      displayName
      
      stages {
        nodes {
          id
          displayName
          position
        }
      }
    }
  }
}

Fetching info about users

query {
  users {
    nodes {
      id
      disabledAt
      displayName
      fullName
    }
  }
}

Fetching info about a single topic

query {
  topic(id: "TOPIC_ID") {
    id
    description
    dueDate
    position
    title
    
    collaborators {
      nodes {
        id
        displayName
      }
    }
    
    stage {
      id
      displayName
    }
    
    labels {
      nodes {
        color
        text
      }
    }
    
    owner {
      id
      displayName
    }
    
    workspace {
      id
      displayName
    }
  }
}

Mutations

Creating a topic

mutation {
  topicCreate(input: {
    position: 3.14159265
    stageId: "STAGE_ID"
    title: "Title"
  }) {
    topic {
      id
    }
  }
}

Updating a topic's basic details

mutation {
  topicUpdate(
    id: "TOPIC_ID"
    input: {
      description: "New description"
      dueDate: "2024-04-08"
      title: "New title"
    }
  ) {
    topic {
      id
    }
  }
}

Updating a topic's owner

mutation {
  topicUpdate(
    id: "TOPIC_ID"
    input: {
      ownerId: "USER_ID"
    }
  ) {
    topic {
      id
    }
  }
}

Updating a topic's collaborators

mutation {
  topicUpdateCollaborators(
    id: "TOPIC_ID"
    collaboratorIdsToAdd: ["USER_ID_1", "USER_ID_2"]
    collaboratorIdsToRemove: ["USER_ID_3"]
  ) {
    topic {
      id
    }
  }
}

Updating a topic's labels

mutation {
  topicUpdateLabels(
    id: "TOPIC_ID"
    labelsToAdd: [{ color: "RED", text: "bug" }]
    labelsToRemove: [{ color: "blue", text: "feedback" }]
  ) {
    topic {
      id
    }
  }
}

Support

If you have any questions or issues with the API, just reach out to us through one of our support channels.

Last updated