API Overview

The 200Notes API provides programmatic access to core features, allowing you to integrate 200Notes with your existing tools, build custom applications, and automate workflows.

Getting Started

API Basics

The 200Notes API is a RESTful API that uses JSON for data exchange. All API requests must be made over HTTPS.

• Base URL: https://200notes.com/api/v1
• Format: JSON
• Authentication: Bearer token (api_key:api_secret)
• Rate Limiting: Not yet implemented

API Versioning

We use URL-based versioning for our API. The current version is v1.

• Version Format: /v1/ in the URL path
• Current Version: v1 (initial release)
• Future Plans: Semantic versioning with backward compatibility

Available Resources

✅ Authentication

User registration, login, and API key management:

• POST /auth/register - Create new account
• POST /auth/login - Login and get API credentials
• POST /auth/refresh-keys - Refresh API keys

✅ Projects

Manage projects and their settings:

• GET /projects - List all projects
• POST /projects - Create a new project
• GET /projects/{id} - Get project details
• PUT /projects/{id} - Update project
• DELETE /projects/{id} - Delete project
• POST /projects/{id}/favorite - Toggle favorite status

✅ Team Management

Manage project team members and collaboration:

• POST /projects/{id}/invite - Invite team member
• GET /projects/{id}/members - List project members
• PUT /projects/{id}/members/{user_id} - Update member role
• DELETE /projects/{id}/members/{user_id} - Remove member

🚧 Notes (Coming in Phase 2)

Create and manage notes within projects:

• GET /projects/{id}/notes - List project notes (planned)
• POST /projects/{id}/notes - Create a new note (planned)
• GET /notes/{id} - Get note details (planned)
• PUT /notes/{id} - Update note (planned)
• DELETE /notes/{id} - Delete note (planned)

✅ Tasks

Manage tasks and their workflow:

• GET /projects/{id}/tasks - List project tasks
• POST /projects/{id}/tasks - Create a new task
• GET /tasks/{id} - Get task details
• PUT /tasks/{id} - Update task
• DELETE /tasks/{id} - Delete task
• PATCH /tasks/{id}/status - Update task status
• POST /tasks/{id}/start - Start task (set to in_progress)
• POST /tasks/{id}/complete - Complete task (set to done)

🚀 Claude Code Integration

AI-powered development workflow integration:

• POST /claude-code/projects/{id}/init - Initialize Claude Code integration
• GET /claude-code/projects/{id}/status - Get project status with task summary
• POST /claude-code/projects/{id}/sync - Synchronize project data
• GET /claude-code/projects/{id}/claude-md - Get CLAUDE.md content
• POST /claude-code/tasks/map-files - Map file changes to tasks
• POST /claude-code/tasks/auto-update - Auto-update tasks based on development activity
• GET /claude-code/projects/{id}/config - Get project configuration
• PUT /claude-code/projects/{id}/config - Update project configuration

🚧 AI Features (Coming in Phase 3)

AI-powered analysis and suggestions:

• POST /ai/analyze-project/{id} - Analyze project (planned)
• GET /ai/analyses/{project_id} - Get analysis history (planned)
• POST /ai/generate-tasks - Generate task suggestions (planned)

Request Format

HTTP Methods

The API uses standard HTTP methods:

• GET: Retrieve data
• POST: Create new resources
• PUT: Update existing resources
• DELETE: Remove resources
• PATCH: Partial updates

Request Headers

Required headers for API requests:

Content-Type: application/json
Accept: application/vnd.200notes.v1+json
Authorization: Bearer YOUR_API_TOKEN

Request Body

For POST and PUT requests, send data as JSON in the request body:

{
  "name": "My New Project",
  "description": "A project for managing client deliverables",
  "visibility": "private"
}

Response Format

Success Responses

Successful requests return data in a simple, consistent format:

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Project",
    "description": "Project description",
    "is_favorite": false,
    "owner": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com"
    },
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  },
  "message": "Project created successfully"
}

Error Responses

Error responses follow standard HTTP status codes:

{
  "message": "The name field is required.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

Authentication Errors

{
  "message": "Unauthenticated."
}

HTTP Status Codes

The API uses standard HTTP status codes:

Pagination

Paginated Responses

List endpoints return paginated results:

{
  "success": true,
  "data": [
    { "id": 1, "name": "Project 1" },
    { "id": 2, "name": "Project 2" }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 20,
    "total": 45,
    "total_pages": 3,
    "has_next": true,
    "has_previous": false
  }
}

Pagination Parameters

Control pagination with query parameters:

• page: Page number (default: 1)
• per_page: Results per page (default: 20, max: 100)
• sort: Sort field
• order: Sort order (asc/desc)

Example: GET /projects?page=2&per_page=10&sort=name&order=asc

Filtering and Searching

Query Parameters

Filter results using query parameters:

• search: Full-text search
• status: Filter by status
• created_after: Filter by creation date
• created_before: Filter by creation date
• assignee: Filter by assignee
• tags: Filter by tags

Example: GET /tasks?status=in_progress&assignee=123&tags=urgent

Advanced Filtering

Use operators for complex filtering:

• eq: Equal to
• ne: Not equal to
• gt: Greater than
• gte: Greater than or equal to
• lt: Less than
• lte: Less than or equal to
• in: In array
• contains: Contains substring

Example: GET /tasks?priority[in]=high,medium&due_date[gte]=2024-01-01

Webhooks

Webhook Events

Receive real-time notifications when events occur:

• project.created - New project created
• project.updated - Project updated
• project.deleted - Project deleted
• note.created - New note created
• note.updated - Note updated
• task.created - New task created
• task.updated - Task updated
• task.completed - Task completed
• member.invited - Team member invited
• member.removed - Team member removed

Webhook Payload

Webhook payloads include event data:

{
  "event": "task.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": 456,
    "title": "New Task",
    "project_id": 123,
    "assignee_id": 789,
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Rate Limiting

Rate Limits

API requests are subject to rate limiting:

• Default Limit: 1000 requests per hour
• Burst Limit: 100 requests per minute
• Premium Limit: 5000 requests per hour

Rate Limit Headers

Response headers indicate rate limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642248000

Handling Rate Limits

When rate limits are exceeded:

• Status Code: 429 Too Many Requests
• Retry-After: Seconds to wait before retrying
• Exponential Backoff: Recommended retry strategy

SDKs and Libraries

Official SDKs

We provide official SDKs for popular programming languages:

• Claude Code CLI: npm install -g @200notes/claude-code (Featured Integration)
• JavaScript/Node.js: npm install @200notes/js-sdk
• Python: pip install 200notes-python
• PHP: composer require 200notes/php-sdk
• Ruby: gem install 200notes
• Go: go get github.com/200notes/go-sdk

SDK Examples

Claude Code CLI

Command-line interface for Claude Code integration:

# Initialize project integration
200notes init "My Project"

# Create and manage tasks
200notes task create "Implement payment flow" --priority high --tags backend,stripe
200notes task start "Implement payment flow"
200notes task done "Implement payment flow"

# Check project status
200notes status

# Sync with 200notes dashboard  
200notes sync

JavaScript SDK

Quick examples using our JavaScript SDK:

import { TwoHundredNotes } from '@200notes/js-sdk';

const client = new TwoHundredNotes('your-api-token');

// Create a project
const project = await client.projects.create({
  name: 'My API Project',
  description: 'Created via API'
});

// Create a note
const note = await client.notes.create(project.id, {
  title: 'API Documentation',
  content: '# Getting Started\n\nThis is my first API note!'
});

// List tasks
const tasks = await client.tasks.list(project.id, {
  status: 'in_progress',
  assignee: 'me'
});

Common Use Cases

Integration Scenarios

Popular ways to integrate with 200Notes:

• Claude Code Integration: Intelligent task tracking during AI-assisted development
• Project Management Tools: Sync tasks between systems
• Documentation Sites: Export notes to static sites
• Reporting Dashboards: Create custom analytics
• Mobile Apps: Build custom mobile experiences
• Automation Scripts: Automate repetitive tasks
• Backup Systems: Create automated backups

Workflow Examples

Example workflows using the API:

• Claude Code Hooks: Automatically track task progress during development sessions
• Smart File Mapping: Map code changes to relevant tasks using AI algorithms
• Daily Standup Bot: Automatically create daily standup notes
• Issue Tracking: Create tasks from support tickets
• Meeting Notes: Auto-generate meeting notes from calendar events
• Progress Reports: Generate weekly progress reports
• Content Migration: Import content from other systems

Best Practices

Performance Tips

Security Best Practices

Testing

API Testing Tools

Tools for testing API integration:

• Postman: Interactive API testing
• curl: Command-line testing
• Insomnia: API client with environment management
• HTTPie: Human-friendly HTTP client

Test Environment

We provide a sandbox environment for testing:

• Sandbox URL: https://sandbox.200notes.com/api/v1
• Test Data: Pre-populated with sample data
• Rate Limits: Relaxed limits for testing
• Reset: Data resets nightly

Support and Resources

Getting Help

Resources for API developers:

• API Documentation: Complete endpoint reference
• SDK Documentation: Language-specific guides
• Code Examples: Sample implementations
• Community Forum: Developer discussions
• Support Tickets: Direct technical support

Stay Updated

Keep up with API changes:

• Changelog: Track API updates
• Developer Newsletter: Monthly updates
• Breaking Changes: Advance notice of changes
• Status Page: Real-time API status