Introduction to the Postpone API (👋 Start Here!)

Create scripts and automations using Postpone's GraphQL API.

Written by Grant - Postpone Founder

Updated 2 weeks ago

Introduction

Postpone offers a GraphQL API to query data and perform mutations to schedule social media 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 retrieve data, such as a list of scheduled posts or post analytics.

Mutations change data, such as scheduling a post on Reddit or X/Twitter.

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.

At this time, the Postpone API is only available to customers on a paid Postpone plan.

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 social media post that is going to be submitted. It comes from a single author and contains the post's content, such as title, link, media, comment, and other post settings. A Post has one or more Submissions.

A Submission represents a submission of a social media post at a point in time.

A Submission has one of the following: a Result (successfully submitted to the platform), an Error (failed to submit to the platform), or neither (the post is either scheduled or a Draft).

Validation Errors

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

success is a boolean that indicates if the mutation was performed successfully.
validationErrors is a list of validation error objects. They provide more information than error codes in errors.
errors (deprecated) is a list of string error codes indicating the error that took place.

Check the return value of every mutation to see if it returns errors, validationErrors, or both.

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.

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"}'

Did this answer your question?