API Keys & Documentation

Welcome to your developer hub. This guide provides everything you need to manage your API keys and interact with your content programmatically. Our REST API allows you to build custom integrations, automate workflows, and extend the functionality of your platform.

API Key Management

API keys provide secure, authenticated access to your account's data via the API. You can create multiple keys with different permissions for various applications.

Creating a New API Key

To start using the API, you first need to create an API key.

1. Navigate to the API Keys page in your dashboard.

2. Click the "Create API Key" button.

3. A dialog box will appear where you need to fill in the following information:

   • Name: A descriptive name for your key to help you identify it later (e.g., "Zapier Integration", "My Custom App").
   • Expiration Date (Optional): For enhanced security, you can set a date and time when the key will automatically expire. Leave it blank for a key that never expires.
   • Permissions (Scopes): This is the most crucial part. Select the specific permissions (scopes) that this key will have. Always follow the principle of least privilege: only grant the permissions that your application absolutely needs.

4. Click "Create API Key".

Managing Your API Keys

Once created, your API keys will be listed in a table. Here you can manage and monitor them:

• View Key Prefix: For security, only the beginning of your key (keyPrefix) is stored and displayed. This helps you identify which key is being used without exposing the full secret.
• Toggle Visibility: You can click the eye icon (<Eye />) to temporarily reveal the key prefix.
• Status (Active/Inactive): You can activate or deactivate a key at any time. A deactivated key cannot be used to make API requests. This is useful for temporarily disabling an integration without permanently deleting the key.
• Last Used: This column shows the last time the key was successfully used to make an API request, helping you identify unused keys.
• Expires & Created: Shows the expiration and creation dates for the key.
• Actions: The dropdown menu allows you to Activate/Deactivate or permanently Delete a key.

API Documentation

Our API is designed to be predictable and easy to use.

API Overview

• Base URL: All API endpoints are relative to this URL.

https://postion.app/api/v1

• Format: All requests and responses are in JSON format.
• Rate Limit: To ensure stability, the API is rate-limited to 100 requests per minute. Rate limit headers are included in every response.

Authentication

All API requests must be authenticated using a Bearer Token in the Authorization header.

Authorization: Bearer pk_your_api_key_here

Replace pk_your_api_key_here with the secret API key you created.

Example cURL Request

Here is an example of how to fetch a list of your posts using cURL:

curl -X GET "https://postion.app/api/v1/posts" \
  -H "Authorization: Bearer pk_your_api_key_here" \
  -H "Content-Type: application/json"

Endpoints

We provide a range of endpoints to manage your content. Below are some of the main resources available.

Posts

The Posts endpoint allows you to manage your blog posts.

• GET /api/v1/posts: List all posts.
• POST /api/v1/posts: Create a new post.
• GET /api/v1/posts/{id}: Get a specific post by its ID.
• PUT /api/v1/posts/{id}: Update a specific post.
• DELETE /api/v1/posts/{id}: Delete a post.

Sites

The Sites endpoint allows you to manage your sites.

• GET /api/v1/sites: List all sites.

Webhooks

Webhooks allow you to receive real-time notifications for events happening in your account.

• GET /api/v1/webhooks: List all webhooks.
• POST /api/v1/webhooks: Create a new webhook.

Code Examples

Here are some practical examples of how to use the API in different programming languages.

JavaScript (Node.js) - Create a Post

const response = await fetch('https://postion.app/api/v1/posts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer pk_your_api_key_here',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'My New Post',
    content: { /* Your post content in JSON format */ },
    description: 'A brief description of my post',
    published: true,
    tags: ['javascript', 'api']
  })
});
 
const data = await response.json();
console.log('Created post:', data);

Python - Fetch Posts

import requests
 
headers = {
    'Authorization': 'Bearer pk_your_api_key_here',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://postion.app/api/v1/posts',
    headers=headers,
    params={'published': True}
)
 
if response.status_code == 200:
    data = response.json()
    posts = data['data']
    print(f"Found {len(posts)} posts")
else:
    print(f"Error: {response.status_code}")

Handling Webhooks (Node.js/Express)

It is critical to verify webhook signatures to ensure that the request is legitimate.

// Express.js webhook handler
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = req.body;
  
  // Verify the signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  // Process the event
  switch (event.event.type) {
    case 'post.published':
      // Handle post publication...
      break;
    default:
      console.log('Unknown event type:', event.event.type);
  }
  
  res.status(200).send('OK');
});

Additional API Endpoints

Below are more endpoints available for building comprehensive integrations.

Subscribers

Manage your subscriber base programmatically.

Example: Get Subscribers

const response = await fetch('https://postion.app/api/v1/subscribers', {
  headers: {
    'Authorization': 'Bearer pk_your_api_key_here',
  }
});
 
const { data: subscribers, pagination } = await response.json();
console.log(`Found ${subscribers.length} subscribers`);

Plans

Manage subscription plans for your sites.

Subscriptions

Access subscription data for your subscribers.

Transactions

View revenue and transaction history.

Tags

Manage content tags.

Rate Limiting Details

To ensure platform stability, API requests are rate-limited.

Rate Limit Headers

Every API response includes these headers:

Rate Limits by Plan

Handling Rate Limits

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please slow down.",
    "retry_after": 30
  }
}

Best Practices:

• Implement exponential backoff when you receive 429s
• Cache responses when possible
• Use webhooks instead of polling for real-time updates

Error Handling

All API errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  }
}

Common Error Codes

Pagination

List endpoints support pagination for large datasets.

Query Parameters

Pagination Response

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "total_pages": 8,
    "has_next": true,
    "has_prev": false
  }
}

API Changelog

Stay informed about API updates.

Version History