Introduction

Name: Contextium
Author: Contextium

API Introduction

Access Contextium programmatically with the REST API.

What is the Contextium API?

The Contextium API enables programmatic access to:

Create, read, update, and delete files
Manage projects and folders
Add comments
Search content
Manage team members
Access version history
Configure webhooks

Perfect for:

Automated documentation generation
CI/CD integration
Custom integrations
AI agent workflows
Bulk operations
External tool connections

Requirements

Plan Requirements

API access requires:

Professional plan or higher
Starter plan does not include API access

See Plans & Pricing for details.

Authentication

All API requests require authentication with an API key.

See Authentication for how to create and use API keys.

Quick Start

1. Create an API Key

Navigate to Settings → API Keys
Click Create API Key
Enter a name (e.g., "CI/CD Integration")
Set permissions (Read, Write, Admin)
Click Generate
Copy and securely store your key

Warning: API keys are shown only once. Store securely.

2. Make Your First Request

Test your API key with a simple request:

curl https://api.contextium.io/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "My Workspace",
      "slug": "my-workspace",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

3. Create a File

curl -X POST https://api.contextium.io/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "name": "Getting Started",
    "content": "# Getting Started\n\nWelcome to our documentation."
  }'

Response:

{
  "id": "file_xyz789",
  "name": "Getting Started",
  "path": "/getting-started",
  "created_at": "2024-01-20T14:22:00Z",
  "url": "https://app.contextium.io/files/file_xyz789"
}

Base URL

All API requests use the base URL:

https://api.contextium.io

Request Format

Headers

All requests must include:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

POST and PUT requests accept JSON bodies:

{
  "name": "value",
  "nested": {
    "key": "value"
  }
}

Response Format

Success Response

Successful requests return JSON:

{
  "id": "resource_id",
  "name": "Resource Name",
  "created_at": "2024-01-20T14:22:00Z"
}

HTTP status codes for success:

200 OK - Request succeeded
201 Created - Resource created
204 No Content - Request succeeded, no response body

Error Response

Failed requests return error details:

{
  "error": {
    "code": "invalid_request",
    "message": "File name is required",
    "details": {
      "field": "name",
      "issue": "missing"
    }
  }
}

HTTP status codes for errors:

400 Bad Request - Invalid request
401 Unauthorized - Invalid or missing API key
403 Forbidden - Insufficient permissions
404 Not Found - Resource not found
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Rate Limits

API requests are rate-limited by plan:

Professional:

1,000 requests/hour
10,000 requests/day

Business:

5,000 requests/hour
50,000 requests/day

Enterprise:

Custom limits

Rate limit headers in every response:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1640000000

See Rate Limits for details.

Pagination

List endpoints return paginated results:

curl "https://api.contextium.io/files?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 156,
    "has_more": true
  }
}

Parameters:

limit - Results per page (default: 20, max: 100)
offset - Number of results to skip (default: 0)

Filtering & Sorting

List endpoints support filtering and sorting:

# Filter by project
curl "https://api.contextium.io/files?project_id=proj_123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by created date
curl "https://api.contextium.io/files?sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Combine filters
curl "https://api.contextium.io/files?project_id=proj_123&sort=name&order=asc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Receive real-time notifications for events:

# Create a webhook
curl -X POST https://api.contextium.io/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["file.created", "file.updated", "comment.added"]
  }'

See Webhooks for details.

API Resources

Core Resources

Files - Create and manage documentation files
Projects - Organize files into projects
Folders - Hierarchical file organization
Versions - Access version history

Collaboration

Comments - Add and manage comments

Search & Organization

Search - Search across content
Tags - Categorize with tags

Workspace Management

Workspaces - Workspace information
Members - Team member management

Configuration

Webhooks - Event notifications
API Keys - Manage API keys

SDKs & Libraries

Official SDKs coming soon for:

JavaScript/Node.js
Python
Go
Ruby

Currently use any HTTP client:

JavaScript (Node.js):

const response = await fetch('https://api.contextium.io/files', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const data = await response.json();

Python:

import requests

response = requests.get(
    'https://api.contextium.io/files',
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

cURL:

curl https://api.contextium.io/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Security

Store API keys securely (environment variables, secrets manager)
Never commit keys to version control
Use read-only keys when possible
Rotate keys every 90 days
Revoke unused keys immediately

Performance

Cache responses when appropriate
Use pagination for large result sets
Batch operations when possible
Monitor rate limits
Handle rate limit errors gracefully

Error Handling

Check HTTP status codes
Parse error messages
Implement retry logic (with exponential backoff)
Log errors for debugging
Handle network failures

Support

Need help with the API?

API Reference - Complete endpoint documentation
Examples - Code examples and use cases
Support - Technical support
Status Page - API status and incidents