👋 Clickety is closing. We are no longer accepting new users, and will turn the service off on 10/1/21. Read more here.

Clickety API

Clickety is entirely API-driven. Every feature available in the front end is also available in our API. If you’re comfortable writing your own tools and scripts, you can take advantage of this to do things that our main interface hasn’t enabled yet.

API access is currently by request only. If you would like access, send us a note.

Stability warning

The fact that this is our actual, live API means it’s much more powerful and useful – we use it to build the core application, so you can be sure it’s always the most recent and most complete.

That also means it’s undergoing constant development. We not only cannot promise that an API call that works today will work tomorrow, we can guarantee constant breaking changes to the API. We will not be making arbitrary changes just to mess with things. But our primary focus is on improving application functionality, not API stability.

Thankfully, the nature of GraphQL means you can always easily get a snapshot of the current API (see below), so if there are changes, you can absorb them quickly.

Prerequisites

Our API works via GraphQL over HTTPS.

To effectively use it, you’ll need to be familiar with both of those, plus a programming language (or the shell!) you can use to work with them.

What can I do with the API?

You can perform any action done in the GUI, such as:

  • View group membership
  • Retrieve interactions for a given user
  • List all groups

Of course, because you’ll be using an actual programming language to do this, you can take this data and do anything you want. For instance:

  • Export group members with their email addresses in CSV format, to be imported into a spreadsheet
  • Update the Notes field for a list of people to include a link to their LinkedIn profile
  • Create a new interaction based on data stored in another system

Haven’t you heard of no-code automation?!

We absolutely do plan to provide in-application automation without requiring coding. But, well, the API is already here, and some of us are using it for our own tool building already. We figured it was better to open it up for those who could use it than to wait until we had the perfect solution for everyone.

Getting Started

  1. Get the API key: Before you can use the API, you’ll need to get the API key from us. We plan to remove this requirement soon, but for now, it’s an easy way to ensure our API isn’t abused by bots and such.

  2. Generate an authorization key: Once you have the main API key, you’ll need a key to allow you to authenticate as yourself. Be very careful with this key – it allows direct access to all of your data. Go to Settings -> API Keys, and create one there. Save it to your computer in a safe place.

  3. Optional: Download Altair (or another graphical GraphQL tool). This is a great way to explore the API and test queries. Altair also can export any functional query into a curl command you can run in the shell, which is very helpful.

  4. Connect to the API: Configure Altair and/or your tools with these HTTPS headers:

  5. Hack away!

Example queries

Once you have Altair connected, you can use it to download all of the docs for our API. This enables autocompletion of queries and mutations. Here are a few queries to get you started, though.

List all keys

The easiest query out there: List the keys you have created. If this works, any of the rest of your queries should work, too.

    query {
      apiKeys {
        gid
        description
        key
        createdAt
        revokedAt
       }
     }

Group and Stack information

GraphQL requires that every object have a GID, which uniquely identifies it. You’ll find basically every useful query returns or relies on this field.

Here’s how to list all groups and their GIDs:

    {
      groups {
        gid
        name
        description
        glyph
        position
        parentGid
        childGids
      }
    }

Given a group, here’s how to list the board/stack information, including membership:

    query peopleInStacks($gid: ID!) {
      groupByGid(gid: $gid) {
        gid
        board {
          gid
          stacks {
            gid
            name
            people {
              nodes {
                person {
                  gid
                  name
                  description
                  notes
                  lastInteraction {
                      gid
                      title
                      type
                      sourceTimestamp
                  }
                }
              }
            }
          }
        }
      }
    }

You can remove anything you don’t need from the query (e.g., you just want the stack GIDs).

Running queries from the CLI

The easiest and fastest way to get started outside of Altair is to use curl to make the HTTPS calls. You can then wrap those commands in your favorite scripting language, and eventually replace those with direct HTTPS calls using the appropriate library.

    curl https://api.clickety.dev/contacts/graphql \
      -H 'Accept-Encoding: gzip, deflate, br' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Connection: keep-alive' \
      -H 'Origin: https://run.clickety.app' \
      -H 'x-api-key: <api key>' \
      -H 'clickety-api-key: <personal key>' \
      --compressed \
      --data-binary '{
          "query": "query {
            apiKeys {
              gid
              description
              key
              createdAt
              revokedAt
            }
          }"
        }'

You can replace the embedded query with whatever you need (but, as with all shell commands, be careful of quoting).

Conclusion

We will hopefully soon publish a the comprehensive API documentation, and remove the requirement for the API key. We’ll also soon have a CLI module (most likely in Ruby) that does a lot of the setup work for you.

But hopefully this will be enough to get started for those particularly keen on wandering outside the comfortable walls of our core application.