Pitchly API reference

Ground rules

Since Pitchly uses GraphQL for its API, every request is routed to a single URL endpoint.


Since REST is backwards compatible with GraphQL, if you would rather use REST, you can do so by:

  • Sending all requests to the same URL above

  • Using the POST method for all requests

  • Setting the Content-Type header of the request to application/json

  • Putting the REST-equivalent JSON from each example in the Body of the request

Each example provided in this documentation reference will show both a GraphQL version of the request and an equivalent REST version. The result that follows the request will be the same for each.


It is common practice to put authorization tokens in the header of API requests, but we include tokens in the body of our requests for convenience and better event tracking.

In the following examples, we are going to use an App Secret (shown as secretKey) to authorize each request. This makes sense when using our API to interact with your own account programmatically. If you are alternatively accessing data on behalf of another user or account using our App SDK, you would swap out the secretKey for an accessToken instead.

No matter whether you're creating an App for others on our platform or you're simply using our API to interact with your own account, each registered "entity" that interacts with Pitchly programmatically is considered an "App" and has its own set of credentials.

As the owner of an App, you will be given both an App ID and App Secret. It is vitally important that your App Secret is never exposed publicly, including through client-side code, code repositories, or online message boards! Any request using your App Secret should be strictly run server-side. Failing to do so could result in others having access to your account and being able to modify data!

If you don't already have an App Secret, contact us and we'll get you squared away.

Request types

At a high level, there are three types of requests you can make with Pitchly's API:

  • Queries (for pulling data from Pitchly)

  • Mutations (for pushing data to Pitchly)

  • Subscriptions (for listening to changes to data on Pitchly)