API Limitations

Token Limits

• Maximum tokens per instance: 50 tokens
• Maximum expiration period: 30 days
• Minimum expiration period: 1 day
• Token visibility: Tokens shown only once at creation

Request Limits

• Content size: Subject to Confluence page size limits (approximately 1MB)
• Rate limiting: Subject to Atlassian API rate limits
• Concurrent requests: No explicit limit, but recommended to implement backoff strategy

Content Limitations

• Markdown format: Must be valid markdown string
• Empty content: Content cannot be empty or whitespace-only
• Special characters: Properly escape special characters in JSON payload

Feature Limitations

• Page creation only: Cannot create blog posts or other content types
• No attachment support: Attachments must be uploaded separately
• No version control: Updates increment version but don't preserve history details
• Single page operations: Bulk operations require multiple API calls

License Requirements

• Active license required: Token creation requires active license
• License validation: Tokens validate license status at creation time
• Token persistence: Tokens remain valid until expiration even if license expires after creation

Workarounds

Large Content

If you need to import content larger than 1MB:

1. Split the content into multiple pages
2. Use a hierarchical structure with parent/child pages
3. Link pages together using markdown links

Attachments

To add attachments to pages created via the API:

1. Create the page using the Markdown Importer API
2. Use Confluence's REST API to upload attachments
3. Reference the attachment ID in subsequent page updates

Example:

// Step 1: Create page via Markdown Importer API
const pageResponse = await createPage({
  spaceId: '98765432',
  parentId: '123456789',
  pageTitle: 'My Page',
  content: '# My Page\n\nContent here...'
});

// Step 2: Upload attachment via Confluence API
const formData = new FormData();
formData.append('file', fileBuffer, 'document.pdf');

await fetch(`https://your-site.atlassian.net/wiki/rest/api/content/${pageId}/child/attachment`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${confluenceToken}`,
    'X-Atlassian-Token': 'no-check'
  },
  body: formData
});

Bulk Operations

For importing multiple pages efficiently:

// Use rate-limited batch processing
const pLimit = require('p-limit');
const limit = pLimit(3); // Max 3 concurrent requests

const pages = [/* your pages */];

const results = await Promise.all(
  pages.map(page =>
    limit(() => importToConfluence(page))
  )
);

Version History

While the API doesn't preserve detailed version history, you can:

1. Maintain your own changelog in the page content
2. Use git to track markdown file changes
3. Reference git commit hashes in page metadata

Related Documentation

• API Reference - Endpoint details
• Best Practices - Production recommendations
• FAQ - Common questions