Developer Documentation
Pythoughts REST API
Build powerful integrations with the Pythoughts publishing platform. Create, publish, and manage blog posts programmatically using our REST API.
Get API Token
Generate your API token in settings
Swagger UI
Interactive API documentation
OpenAPI Spec
Download OpenAPI specification
Getting Started
Follow these steps to start using the Pythoughts API
Create an Account
Sign up for a free account at pythoughts.com/sign-up
Generate API Token
Go to Settings → API Tokens and create a new token with the required scopes
Authorization: Bearer pt_your_api_token_hereMake Your First Request
Test your token by listing your posts
curl -X GET "https://pythoughts.com/api/v1/posts?page=1&limit=20" \
-H "Authorization: Bearer pt_your_token_here"Authentication & Scopes
All API requests require a Bearer token with appropriate scopes
posts:readRead posts and drafts
posts:writeCreate, update, and delete posts
posts:publishPublish and unpublish posts
blogs:readRead blog information
blogs:writeCreate and update blogs
Rate Limits
API requests are rate limited to ensure fair usage
| Operation | Limit | Window |
|---|---|---|
| Read (GET) | 100 requests | 1 minute |
| Write (POST/PUT) | 60 requests | 1 minute |
| Publish | 10 requests | 1 hour |
| Token Creation | 10 tokens | 1 hour |
Rate Limit Headers
Check X-RateLimit-Remaining and X-RateLimit-Reset headers to monitor your usage
API Endpoints
All endpoints are prefixed with https://pythoughts.com/api/v1
/postsList all posts with pagination
Required scope: posts:read/posts/{id}Get a single post by ID
Required scope: posts:read/postsCreate a new draft post
Required scope: posts:write/posts/{id}Update an existing post
Required scope: posts:write/posts/{id}Delete a post permanently
Required scope: posts:write/posts/{id}/publishPublish a draft post
Required scope: posts:publish/posts/{id}/unpublishUnpublish a published post
Required scope: posts:publish/blogsList all blogs for authenticated user
Required scope: blogs:readHTTP Status Codes
Standard HTTP status codes used by the API
200OK
Request successful
201Created
Resource created
400Bad Request
Invalid request body or parameters
401Unauthorized
Invalid or missing API token
403Forbidden
Insufficient permissions or IDOR attempt
404Not Found
Resource doesn't exist
429Too Many Requests
Rate limit exceeded
500Internal Server Error
Server error (contact support)
Client Libraries
Download pre-built client libraries for your favorite language
Quick Start Examples
Get started quickly with these code snippets
Python
from pythoughts_client import PythoughtsClient
client = PythoughtsClient('pt_your_token_here')
# List posts
posts = client.list_posts(page=1, limit=20)
# Create post
content = {
'type': 'doc',
'content': [
{
'type': 'paragraph',
'content': [{'type': 'text', 'text': 'Hello from Python!'}]
}
]
}
post = client.create_post(
blog_id='your_blog_id',
title='My Python Post',
content=content
)
# Publish post
client.publish_post(post['data']['post']['id'])JavaScript
const PythoughtsClient = require('./pythoughtsClient');
const client = new PythoughtsClient('pt_your_token_here');
// List posts
const posts = await client.listPosts({ page: 1, limit: 20 });
// Create post
const content = {
type: 'doc',
content: [
{
type: 'paragraph',
content: [{ type: 'text', text: 'Hello from JavaScript!' }]
}
]
};
const post = await client.createPost({
blogId: 'your_blog_id',
title: 'My JavaScript Post',
content
});
// Publish post
await client.publishPost(post.data.post.id);TypeScript
import PythoughtsClient from './pythoughtsClient';
const client = new PythoughtsClient('pt_your_token_here');
// List posts
const posts = await client.listPosts({ page: 1, limit: 20 });
// Create post
const content: TiptapContent = {
type: 'doc',
content: [
{
type: 'paragraph',
content: [{ type: 'text', text: 'Hello from TypeScript!' }]
}
]
};
const post = await client.createPost({
blogId: 'your_blog_id',
title: 'My TypeScript Post',
content
});
// Publish post
await client.publishPost(post.data.post.id);Best Practices
Follow these guidelines for secure and efficient API usage
Do
- ✓ Store tokens in environment variables
- ✓ Use separate tokens for different environments
- ✓ Implement exponential backoff for retries
- ✓ Handle rate limit errors gracefully
- ✓ Validate responses before processing
Don't
- ✗ Commit tokens to version control
- ✗ Log tokens in application logs
- ✗ Ignore rate limit headers
- ✗ Make synchronous batch requests
- ✗ Skip error handling
Need Help?
Join our developer community, explore the interactive Swagger documentation, or reach out to our support team.