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 GraphQL.org.
Postpone's API URL: 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 requests against the GraphQL API. You can obtain your API token from the Settings page under the API Token section.
For detailed information on authentication, including how to get your API token, security best practices, and troubleshooting, see our Authentication guide.
Rate Limits
To ensure fair usage and system stability, Postpone enforces rate limits on API requests:
- Free accounts: 25 requests per 10 minutes
- Paid accounts: 300 requests per 10 minutes
Rate limits are applied per user. For more information about rate limits, including headers and best practices, see our Rate Limits guide.
Core Models
Postpone has four key models in its API: Post, Submission, Result, and Error.
Post
A social media post that is going to be submitted. Contains the post's content, such as title, link, media, comment, and other post settings. A Post has one or more Submissions.
Submission
A submission of a social media post at a point in time.
Result
Successfully submitted to the platform.
Error
Failed to submit to the platform.
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).
Error Handling
When working with mutations in the Postpone API, it's important to properly handle errors and validation issues. The API provides detailed error information to help you understand what went wrong and how to fix it.
For comprehensive information about error handling, validation errors, and best practices, see our dedicated Error Handling guide.
Complete API Request Example
Here's 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"}'