GraphQL API

Equipped with an access token, you may now use it to make requests to our GraphQL API.

If you've never used GraphQL before, below you will find everything you need to make requests. If you're already familiar with GraphQL or are ready to start making GraphQL requests, you can head over to our GraphQL schema documentation to find example queries and test them using the Explorer.

Why GraphQL?

We chose to deliver our API with GraphQL because, compared to traditional REST endpoints, GraphQL allows you to specify exactly the data you want returned, and it enables fetching complex data structures in one request instead of many smaller requests. GraphQL also supports real-time updates via GraphQL subscriptions with websockets out of the box.

Do I need special software to make GraphQL calls?

No. Our GraphQL API can be called in the same way you make REST API calls, by just sending a request to an HTTP endpoint.

How do I make GraphQL calls?

Compared to typical REST APIs, all requests to GraphQL are POST requests to the following endpoint:

https://api.pitchly.com/graphql

In the headers of your request, you must include:

{
    "Content-Type": "application/json",
    "Authorization": `Bearer ${accessToken}`
}

Replace ${accessToken} with your access token.

Next, the body of your request should be a JSON-encoded object containing your GraphQL query and any applicable variables in the following format.

{
    query: "...", // your GraphQL query as a string
    variables: { ... } // any applicable variables to include in the query (optional)
}

When you receive a response back to your request, the response will take the following form:

// if successful
{
    "data": { ... }
}

// if error
{
    "errors": [ ... ],
    "data": null
}

Note: Unlike most REST APIs, GraphQL will always return a 200 OK HTTP status code, even if your query failed. You can instead determine if an error occurred by checking whether data in the response is null.

Example request

The following example demonstrates how you would get a list of tables in a specific workspace using the Pitchly GraphQL API in Node.js.

// third-party fetch package for making HTTP calls
import fetch from "node-fetch";

const response = await fetch("https://api.pitchly.com/graphql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json", // must be included in GraphQL requests
    "Authorization": "Bearer " + accessToken
  },
  body: JSON.stringify({
    query: `
      query workspace($id: ID!) {
        workspace(id: $id) {
          tables {
            id
            name
          }
        }
      }
    `,
    variables: {
      id: workspaceId
    }
  })
});

// GraphQL will always return a 200 OK status code,
// even when there is an error. So first check that
// the HTTP status code is 200, and then check that
// "data" exists in the response, indicating success.

if (!response.ok) {
  throw new Error("HTTP request returned error status code.");
}

// decode response json
const data = await response.json();

if (!data.data) {
  throw new Error("GraphQL query failed.");
}

console.log(data);

A successful response for this request may look something like this:

{
  "data": {
    "workspace": {
      "tables": [
        {
          "id": "wksEtbAYd6bcTKigHGm4|tbloJnfkHi85WscsjTvG",
          "name": "Companies"
        },
        {
          "id": "wksEtbAYd6bcTKigHGm4|tblR59H2hbufDMpp5BTp",
          "name": "Matters"
        },
        {
          "id": "wksEtbAYd6bcTKigHGm4|tblqafbaJW9ZqeiZbJ9Q",
          "name": "Employees"
        }
      ]
    }
  }
}

If the request had failed due to an invalid access token, for example, data would have looked something like this (and you still would have received a 200 OK HTTP status code):

{
  "errors": [
    {
      "message": "You must be authenticated to access this resource. Please provide a valid Bearer Token in the Authorization header.",
      "locations": [
        {
          "line": 2,
          "column": 3
        }
      ],
      "path": [
        "workspace"
      ],
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ],
  "data": null
}

Resources

GraphQL Schema Documentation

Click here to view our full GraphQL schema documentation and all query options.

GraphQL Explorer

Click here to access the GraphQL Explorer, a web interface where you can test GraphQL requests against our API straight from your browser!

Pitchly Field Types/Returns

Click here to consult the full list of pitchly field types and sample return values for each type.