Getting started

Learn about some general principles for working with our API. To learn more about GraphQL itself we recommend visiting

graphql.org/learn

.

Authentication

All requests to the API must be authenticated with an access token. This access token can be taken from Settings > Organization > API, and you can send it along with requests in the HTTP Authorization header:

Authorization: Bearer <TOKEN>

note

Getting the access token requires admin access.

All API requests must be made over HTTPS. Calls made over plain HTTP or requests without authentication will fail.

Endpoint

Unlike a REST API, a GraphQL API has just a single endpoint. For the Groove GraphQL API you need to run every operation against the following endpoint:

https://api.groovehq.com/v2/graphql

Make your first request

Use this request to confirm your token works before writing a larger query.

curl https://api.groovehq.com/v2/graphql \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"query":"query { __typename }"}'

Successful responses are JSON:

{
  "data": {
    "__typename": "Query"
  }
}

You can also explore shared examples in the Groove Postman collection.

The same request in JavaScript:

const response = await fetch('https://api.groovehq.com/v2/graphql', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ query: 'query { __typename }' }),
});

const result = await response.json();
console.log(result);

And in Ruby:

require 'json'
require 'net/http'

uri = URI('https://api.groovehq.com/v2/graphql')
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer <TOKEN>'
request['Content-Type'] = 'application/json'
request.body = JSON.dump(query: 'query { __typename }')

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.body

Do not send access tokens in query strings. Use the Authorization header.

Pagination

The Groove API conforms to the GraphQL Cursor Connections Specification. These connections make use of cursor-based pagination. Cursors are like pointers, and they point to a place in the list of where your last request left off.

You can find more details about this pattern on the GraphQL Cursor Connections Specification page.

Lists of nodes that are paged all implement this pattern.

Arguments

Name	Description
after (String)	Returns the elements in the list that come after the specified cursor.
before (String)	Returns the elements in the list that come before the specified cursor.
first (Int)	Returns the first _n_ elements from the list.
last (Int)	Returns the last _n_ elements from the list.

Fields

Name	Description
edges ([ObjectEdge])	A list of edges.
nodes ([Object])	A list of nodes.
pageInfo (PageInfo!)	Information to aid in pagination.
totalCount (Int)	The total number of objects returned from the query.
totalPageCount (Int)	The total number of pages based on total page count and page size.

Edges

Edges represent nodes within a result set. They contain the node and a cursor which is a string represenation of that node's position within the result set.

Fields

Name	Description
cursor (String)	A string representation of the node's position within the result set.
node (Object)	The node for the respective edge