# API quickstart

{% hint style="success" %}
**The Glue API is in beta.** As the product evolves, we need to evolve the API as well. While we take breaking changes and deprecations seriously, the API is still in beta and we will need to make some of these changes. 

While we're in beta, the notice period may be as short as a few weeks. 

Glue's GraphQL API doesn't have versioning like many REST APIs. Instead the schema will evolve with certain things being marked with the `@deprecated` directive. This is usually accompanied by an addition to the schema intended to replace the deprecated functionality. Anything marked with `@deprecated` will be removed after some time.
{% endhint %}

Glue's public API is built using GraphQL and follows the [Relay](https://relay.dev/docs/) specification. It's the same API we use internally for developing our applications. If you are new to GraphQL, Apollo has [resources for beginners](https://blog.apollographql.com/the-basics-of-graphql-in-5-links-9e1dc4cac055). The official [GraphQL documentation](https://graphql.org/) is another good starting point.

## Endpoint

Glue's GraphQL endpoint is:

```http
https://api.gluegroups.com/public/graphql
```

It supports introspection so you can query the whole schema.

## Authentication

The Glue API supports OAuth2 authentication.

### OAuth

[OAuth2 authentication](https://docs.glue.ai/developers/authentication/oauth-2-0-authentication) is required. Once you complete the authentication flow and acquire an access token, pass it with the header `Authorization: Bearer <ACCESS_TOKEN>`

```sh
curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  --data '{ "query": "{ groups { nodes { id name } } }" }' \
  https://api.gluegroups.com/public/graphql
```

## Glue IDs

Glue uses prefixed IDs to identify different types of resources. The prefix indicates the resource type, followed by a unique identifier. Common prefixes include:

* `usr_` - Users
* `thr_` - Threads
* `grp_` - Groups
* `wks_` - Workspaces
* `msg_` - Messages

For example: `usr_2a1b3c4d5e6f7g8h9i0j`, `thr_1b2c3d4e5f6g7h8i9j0k`, `grp_3c4d5e6f7g8h9i0j1k2l`

These IDs can be used in GraphQL queries and mutations, and they work with the Relay `node` query to fetch any type of resource.

## Glue SDK

The [Glue SDK](https://docs.glue.ai/developers/sdk) exposes the Glue GraphQL schema, and makes it easy to access models, or perform mutations. We recommend using it to interact with the GraphQL API. It is written in TypeScript, allowing all operations to be strongly typed.

## Getting Started

Our GraphQL API is explorable and queryable via [Apollo Studio](https://studio.apollographql.com/public/glue-api/variant/current/home), no download or log in required. Click the Schema tab to browse the schema, and click the Explorer tab to run queries.

{% embed url="<https://studio.apollographql.com/public/glue-api/variant/current/schema/reference>" %}

Once you have your client installed, you can start making queries (read) and mutations (write) to the API.

{% hint style="info" %}
We highly recommend using a GraphQL client to introspect and explore the schema if you are not using the Glue Client (SDK).
{% endhint %}

### Queries & Mutations

To get information about the authenticated user, you can use the `me` query:

```graphql
query Me {
  me {
    id
    name
  }
}
```

You can use the `groups` query to get a list of groups.

```graphql
query Groups {
  groups {
    nodes {
      id
      name
    }
    totalCount
  }
}
```

If you have a specific group ID, you can use a `node` query to query for the group.

```graphql
query Group {
  node(id: "grp_2a1b3c4d5e6f7g8h9i0j") {
    ... on Group {
      id
      name
    }
  }
}
```

The node query is part of the [Relay](https://relay.dev/docs/) specification. It can be used to query any object by its ID, and the response is polymorphic. The response type is tied directly to the type of ID passed in and you need to use fragments to specify which type you're querying.

Here's a similar example where we query for a thread:

```graphql
query Thread {
  node(id: "thr_1b2c3d4e5f6g7h8i9j0k") {
    ... on Thread {
      id
      subject
    }
  }
}
```

And here's an example of querying a thread edge. The thread edge contains user specific information for the given thread ID.

```graphql
query ThreadEdge {
  node(id: "thr_1b2c3d4e5f6g7h8i9j0k-usr_2a1b3c4d5e6f7g8h9i0j") {
    ... on ThreadEdge {
      id
      cursor
      recipientRole
      subscription
      node {
        id
        subject
        createdAt
      }
    }
  }
}
```

This query returns the user's recipientRole and subscription with respect to the thread, as well as the thread subject and creation date.

To learn more, take a look at these other pages:

[messages\_and\_threading](https://docs.glue.ai/developers/graphql-api/messages_and_threading "mention")

[understanding-glue-thread-types](https://docs.glue.ai/developers/graphql-api/understanding-glue-thread-types "mention")

[pagination](https://docs.glue.ai/developers/graphql-api/pagination "mention")

To see everything that is available, check out our [GraphQL Explorer](https://studio.apollographql.com/public/glue-api/variant/current/home). This serves as a complete API reference and also provides an interface to help you construct and run queries.

## Support

If you run into problems or have questions or suggestions, you can reach us in Glue using the "Contact Support" option under the Help menu in the top right corner or send us a note (<support@gluegroups.com>).