GraphQL API

Attentive's API now supports GraphQL to enable developers to integrate with the Attentive platform. This API is in beta - the current set of fields in the Graph is equivalent to our Attentive API and we plan to expand our GraphQL API. Attentive intends for GraphQL to become the primary query language for its API. Please note that the schema may experience some changes over time.

For the time being, all supported functionality in the Graph is documented in this section.

Further information about GraphQL is available here.

Authentication

All GraphQL API queries require a valid Attentive application token. These are the same tokens used by the REST API, granted in the OAuth 2.0 flow. The access token is provided as a bearer token in the Authorization header.

Fields and mutations on the Graph are tied to access scopes. Scopes are assigned to applications during the install flow. The access token in your request must have all access scopes required by the requested fields or mutations.

Graph queries

GraphQL queries are executed by sending POST HTTP requests to the endpoint:

POST https://api.attentivemobile.com/v1/graphql

Read requests always begin at the query root, whereas write requests always begin at the mutation root.

For example, this query provides information about the caller's access token, similar to the /me endpoint:

Copy
Copied
query {
  viewer {
    installedApplication {
      name
      installerCompany {
        name
      }
    }
  }
}

Status and error codes

Like REST, GraphQL queries return HTTP status codes. However, an important distinction is that the GraphQL API can return a 200 OK response code in cases that would typically produce 4xx or 5xx errors in REST. If there was an error in a query, the errors object in the response will be present and contain additional detail to help you debug.

For example, if a query requested a non-existent field in the Graph, the response would have a 200 OK status code, along with error details:

Copy
Copied
{
    "data": null,
    "errors": [
        {
            "message": "Validation error of type FieldUndefined: Field 'abc' in type 'installerCompany' is undefined",
            "locations": [
                {
                    "line": 3,
                    "column": 1
                }
            ],
            "extensions": {
                "classification": "ValidationError"
            }
        }
    ]
}

4xx and 5xx status codes will only be returned in the case of authorization (401 Unauthorized) or malformed requests.