Introduction

Postpone offers a GraphQL API to query data and perform mutations to schedule Reddit posts. If you're new to GraphQL then check out https://graphql.org/.

Postpone's API URL is https://api.postpone.app/gql.

API Playground

The best way to learn Postpone's API is to play around with it in our GraphQL explorer. To do that, log into Postpone in a web browser then navigate to https://api.postpone.app/gql.

From here you can execute queries and mutations against Postpone. Queries return data, such as a list of scheduled Reddit posts. Mutations change data, such as scheduling a Reddit post.

Try out this GraphQL query to return a list of Reddit posts, each post's submissions, and the results of those submissions.

Authentication

Postpone uses personal API tokens to authenticate against our API. To retrieve your personal API token, head to your Settings and scroll down to the API Token section. From here you can reveal your API token or generate a new one.

API tokens should be passed to Postpone using the Authorization header. Include the prefix Bearer before the token in your API requests.

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.postpone.app/gql

Models

Postpone has four key models in its API: Post, Submission, Result, and Error.

A Post represents a Reddit post that is going to be submitted. It comes from a single Reddit author and contains the post's title, link, content, comment, and post settings (nsfw, spoiler, and send replies to inbox). A Post has one or more Submissions.

A Submission represents a submission of a Reddit post to a subreddit at a point in time. It also contains the flair that should be included in the submission. A Submission has one of the following: a Result (successfully submitted to Reddit), an Error (failed to submit to Reddit), or neither (scheduled to be submitted to Reddit).

Validation Errors

GraphQL does not return a 400 response status code when a request is invalid. Instead, Postpone's GraphQL API returns the following two attributes for all mutations: success and errors.

success is a boolean that indicates if the mutation was performed successfully. errors is a list of string error codes indicating the error that took place.

The following is an example response from the createRedditPost mutation when no post link or content is provided:

{
  "data": {
    "createRedditPost": {
      "success": false,
      "errors": [
        "linkOrContentRequired"
      ]
    }
  }
}

Examples

The following links include example queries and mutations that you can execute against the Postpone API.

• Query a list of Reddit posts with their submissions, results, and errors
• Schedule a Reddit post with submissions to two different subreddits

The following is a full example of making a request to the Postpone API:

curl --request POST \
  --url https://api.postpone.app/gql \
  --header 'authorization: Bearer YOUR-TOKEN' \
  --header 'content-type: application/json' \
  --data '{"query": "query profile { profile { id username email registeredAt } }", "operationName": "profile"}'