API Reference

The Changelogy API allows you to publish changelog posts programmatically from your CI/CD pipeline, application, or any automated workflow.

Requirements

• PRO Subscription Required: API access is only available for organizations with an active PRO subscription
• API Key: You'll need to create an API key from your organization's API settings page

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Creating an API Key

1. Navigate to your organization dashboard
2. Click "API" in the sidebar
3. Click "Create API Key"
4. Give your key a descriptive name (e.g., "Production CI/CD")
5. Copy the key immediately - you won't be able to see it again!

Security Best Practices:

• Store API keys securely (use environment variables or secrets management)
• Never commit API keys to version control
• Rotate keys regularly
• Use separate keys for different environments (dev, staging, prod)
• Delete unused keys

Base URL

https://www.changelogy.com/api/v1

Endpoints

POST /changelogs

Create a new changelog post.

Endpoint:

POST https://www.changelogy.com/api/v1/changelogs

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body:

{
  "page_id": "uuid-of-your-page",
  "title": "Version 2.0 Released",
  "content": "# What's New\n\nWe're excited to announce...\n\n## Features\n- Feature 1\n- Feature 2",
  "status": "published",
  "tag_ids": ["tag-uuid-1", "tag-uuid-2"],
  "published_at": "2024-12-02T10:00:00Z"
}

Parameters:

• page_id (required): UUID of the changelog page to publish to
• title (required): Title of the changelog post
• content (required): Content in Markdown format
• status (optional): Post status - "draft", "published", or "scheduled" (default: "draft")
• tag_ids (optional): Array of tag UUIDs to associate with the post
• published_at (optional): Publication timestamp (required for "scheduled" status)

Response (201 Created):

{
  "success": true,
  "message": "Changelog post created successfully",
  "post": {
    "id": "post-uuid",
    "slug": "version-2-0-released",
    "title": "Version 2.0 Released",
    "status": "published",
    "published_at": "2024-12-02T10:00:00Z",
    "created_at": "2024-12-02T09:55:00Z"
  }
}

Finding Your Page ID

To publish to a specific changelog page, you need its UUID:

1. Go to your organization settings
2. Click "Pages" in the sidebar
3. View the page details - the ID is in the URL or page settings

Alternatively, you can use the browser developer tools:

1. Visit your changelog page
2. Open Developer Tools (F12)
3. Check the network tab for API calls - the page_id is in the responses

Content Formatting

The content field supports full Markdown syntax:

Headings:

# H1 Heading
## H2 Heading
### H3 Heading

Lists:

- Bullet point 1
- Bullet point 2

1. Numbered item 1
2. Numbered item 2

Emphasis:

**Bold text**
*Italic text*
`Code inline`

Code Blocks:

```javascript
const example = "code";
console.log(example);
```

Links:

[Link text](https://example.com)

Images:

![Alt text](https://example.com/image.png)

Example: Curl

curl -X POST https://www.changelogy.com/api/v1/changelogs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -d '{
    "page_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Bug Fixes and Improvements",
    "content": "## Bug Fixes\n\n- Fixed login issue\n- Improved performance\n\n## Improvements\n\n- Updated UI",
    "status": "published"
  }'

Example: JavaScript/Node.js

const fetch = require('node-fetch');

async function publishChangelog() {
  const response = await fetch('https://www.changelogy.com/api/v1/changelogs', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer sk_live_your_api_key_here'
    },
    body: JSON.stringify({
      page_id: '123e4567-e89b-12d3-a456-426614174000',
      title: 'Version 1.5 Released',
      content: '## What\'s New\n\n- New dashboard\n- Performance improvements',
      status: 'published'
    })
  });

  const data = await response.json();
  console.log('Post created:', data.post);
}

publishChangelog();

Example: Python

import requests
import json

url = 'https://www.changelogy.com/api/v1/changelogs'
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer sk_live_your_api_key_here'
}

payload = {
    'page_id': '123e4567-e89b-12d3-a456-426614174000',
    'title': 'Version 1.5 Released',
    'content': '## What\'s New\n\n- New dashboard\n- Performance improvements',
    'status': 'published'
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
result = response.json()
print('Post created:', result['post'])

Example: GitHub Actions CI/CD

Create a workflow file .github/workflows/publish-changelog.yml:

name: Publish Changelog

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Publish to Changelogy
        env:
          CHANGELOGY_API_KEY: CHANGELOGY_API_KEY
          CHANGELOGY_PAGE_ID: CHANGELOGY_PAGE_ID
        run: |
          curl -X POST https://www.changelogy.com/api/v1/changelogs \
            -H "Content-Type: application/json" \
            -H "Authorization: Bearer CHANGELOGY_API_KEY" \
            -d "{
              \"page_id\": \"CHANGELOGY_PAGE_ID\",
              \"title\": \"Release VERSION_TAG\",
              \"content\": \"RELEASE_NOTES\",
              \"status\": \"published\"
            }"

Setup:

1. Go to your repository Settings > Secrets
2. Add CHANGELOGY_API_KEY with your API key
3. Add CHANGELOGY_PAGE_ID with your page UUID

Error Handling

The API returns standard HTTP status codes:

200-299: Success

• 201 Created - Post created successfully

400-499: Client Errors

• 400 Bad Request - Invalid request body or missing required fields
• 401 Unauthorized - Missing or invalid API key
• 403 Forbidden - API key disabled, expired, or subscription not active
• 404 Not Found - Page not found or doesn't belong to organization

500-599: Server Errors

• 500 Internal Server Error - Something went wrong on our end

Error Response Format:

{
  "error": "Error message describing what went wrong",
  "details": "Additional error details if available"
}

Common Errors

Missing API Key:

{
  "error": "Missing or invalid Authorization header. Use: Authorization: Bearer YOUR_API_KEY"
}

Invalid API Key:

{
  "error": "Invalid API key"
}

Subscription Required:

{
  "error": "API access requires an active PRO subscription"
}

Missing Required Fields:

{
  "error": "Missing required fields: title and content are required"
}

Invalid Page ID:

{
  "error": "Page not found or does not belong to this organization"
}

Rate Limiting

• Currently no rate limits are enforced
• We monitor for abuse and may implement rate limiting in the future
• Best practice: Don't exceed 100 requests per minute

CORS Support

The API supports Cross-Origin Resource Sharing (CORS) and can be called from any domain. This allows you to publish changelogs directly from your web applications.

Monitoring and Logs

View your API usage in your organization's API settings page:

1. Navigate to your organization dashboard
2. Click "API" in the sidebar
3. Scroll to "Recent API Requests"

The logs show:

• Endpoint and method
• Request timestamp
• Response status
• IP address
• API key used
• Error messages (if any)

Logs are retained for 30 days.

Support

Need help with the API?

• Check this documentation for examples and common issues
• View your API logs for debugging
• Contact support: contact@changelogy.com

Include in your support request:

• Organization name
• API key prefix (first 16 characters)
• Error message
• Request example (without sensitive data)