API Documentation - HyperPlanner

Overview

The HyperPlanner API provides programmatic access to your tasks, events, templates, and settings. Use it to integrate HyperPlanner with your existing tools, build custom automations, or create third-party applications.

Authentication Rate Limits Tasks API Events API Templates API Settings API Error Codes Webhooks SDKs

Base URL

https://api.hyperplanner.app/v1

API Access

API access is available on Pro and Team plans. Free accounts can use the API in read-only mode with limited rate limits. Upgrade your plan for full API access.

Authentication

The HyperPlanner API supports two authentication methods: API Keys for server-to-server communication, and OAuth 2.0 for user-authorized applications.

API Keys

API keys are the simplest way to authenticate. Generate a key from your Settings > Developer > API Keys panel.

Request Header HTTP

Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keep Your Keys Secret

Never expose API keys in client-side code or public repositories. Use environment variables and server-side requests. Rotate keys immediately if compromised.

API Key Types

Key Prefix	Type	Use Case
`hp_live_`	Production	Live environment with full access
`hp_test_`	Test	Sandbox environment for development
`hp_readonly_`	Read-only	Read access only, no mutations

OAuth 2.0

For applications that act on behalf of users, implement OAuth 2.0 authorization flow.

OAuth Authorization URL HTTP

GET https://hyperplanner.app/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=tasks:read tasks:write events:read events:write
  &state=random_state_string

OAuth Token Exchange

Token Request HTTP

POST https://api.hyperplanner.app/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTH_CODE_FROM_CALLBACK
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

Token Response JSON

{
  "access_token": "hp_oauth_xxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "hp_refresh_xxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "tasks:read tasks:write events:read events:write"
}

Available Scopes

Scope	Description
`tasks:read`	Read access to tasks
`tasks:write`	Create, update, delete tasks
`events:read`	Read access to calendar events
`events:write`	Create, update, delete events
`templates:read`	Read access to templates
`templates:write`	Create templates
`settings:read`	Read user settings
`settings:write`	Modify user settings
`webhooks:manage`	Create and manage webhooks

Rate Limits

API requests are rate-limited to ensure fair usage and system stability. Limits vary by plan and endpoint type.

Rate Limit Tiers

Plan	Requests/Minute	Requests/Day	Burst Limit
Free	30	1,000	10
Pro	120	10,000	50
Team	300	50,000	100
Enterprise	Custom	Custom	Custom

Rate Limit Headers

Every API response includes headers indicating your current rate limit status:

Response Headers HTTP

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1699545600
X-RateLimit-RetryAfter: 45

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per minute
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the limit resets
`X-RateLimit-RetryAfter`	Seconds to wait before retrying (when rate limited)

Handling Rate Limits

When you receive a 429 Too Many Requests response, wait for the time specified in X-RateLimit-RetryAfter before retrying. Implement exponential backoff for robust error handling.

Tasks API

Create, read, update, and delete tasks. Tasks are the core entities in HyperPlanner, representing actionable items with optional due dates, priorities, and metadata.

GET /api/tasks

Retrieve a list of tasks with optional filtering and pagination.

Query Parameters

Parameter	Type	Description
`status`optional	string	Filter by status: `pending`, `in_progress`, `completed`, `archived`
`priority`optional	string	Filter by priority: `high`, `medium`, `low`
`context`optional	string	Filter by context (e.g., `work`, `personal`)
`due_before`optional	ISO 8601	Tasks due before this date
`due_after`optional	ISO 8601	Tasks due after this date
`tags`optional	string	Comma-separated list of tags
`limit`optional	integer	Number of results (default: 50, max: 100)
`offset`optional	integer	Pagination offset

Example Request cURL

curl -X GET "https://api.hyperplanner.app/v1/tasks?status=pending&priority=high&limit=10" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response JSON

{
  "data": [
    {
      "id": "task_abc123xyz",
      "title": "Review quarterly report",
      "description": "Review and approve Q4 financial report",
      "status": "pending",
      "priority": "high",
      "context": "work",
      "tags": ["finance", "quarterly"],
      "due_at": "2024-01-15T17:00:00Z",
      "created_at": "2024-01-10T09:30:00Z",
      "updated_at": "2024-01-10T09:30:00Z",
      "subtasks": [],
      "metadata": {}
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

POST /api/tasks

Create a new task.

Request Body

Field	Type	Description
`title`required	string	Task title (max 500 characters)
`description`optional	string	Task description (max 5000 characters)
`priority`optional	string	Priority level: `high`, `medium`, `low`
`context`optional	string	Context label
`tags`optional	array	Array of tag strings
`due_at`optional	ISO 8601	Due date and time
`subtasks`optional	array	Array of subtask objects
`metadata`optional	object	Custom key-value pairs

Example Request cURL

curl -X POST "https://api.hyperplanner.app/v1/tasks" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare presentation",
    "description": "Create slides for Monday all-hands meeting",
    "priority": "high",
    "context": "work",
    "tags": ["meeting", "presentation"],
    "due_at": "2024-01-15T09:00:00Z",
    "subtasks": [
      {"title": "Draft outline"},
      {"title": "Create slides"},
      {"title": "Add visuals"}
    ]
  }'

Example Response JSON

{
  "data": {
    "id": "task_def456uvw",
    "title": "Prepare presentation",
    "description": "Create slides for Monday all-hands meeting",
    "status": "pending",
    "priority": "high",
    "context": "work",
    "tags": ["meeting", "presentation"],
    "due_at": "2024-01-15T09:00:00Z",
    "created_at": "2024-01-10T14:22:00Z",
    "updated_at": "2024-01-10T14:22:00Z",
    "subtasks": [
      {"id": "sub_001", "title": "Draft outline", "completed": false},
      {"id": "sub_002", "title": "Create slides", "completed": false},
      {"id": "sub_003", "title": "Add visuals", "completed": false}
    ],
    "metadata": {}
  }
}

PUT /api/tasks/:id

Update an existing task. Supports partial updates - only include fields you want to change.

Example Request cURL

curl -X PUT "https://api.hyperplanner.app/v1/tasks/task_def456uvw" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "in_progress",
    "priority": "medium"
  }'

Example Response JSON

{
  "data": {
    "id": "task_def456uvw",
    "title": "Prepare presentation",
    "status": "in_progress",
    "priority": "medium",
    "updated_at": "2024-01-10T15:45:00Z"
    // ... other fields unchanged
  }
}

DELETE /api/tasks/:id

Delete a task. This action is irreversible. Use status: "archived" for soft delete.

Example Request cURL

curl -X DELETE "https://api.hyperplanner.app/v1/tasks/task_def456uvw" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response JSON

{
  "data": {
    "id": "task_def456uvw",
    "deleted": true,
    "deleted_at": "2024-01-10T16:00:00Z"
  }
}

Events API

Manage calendar events with time blocks, recurrence patterns, and attendee information. Events integrate seamlessly with tasks for time-blocking workflows.

GET /api/events

Retrieve calendar events within a date range.

Query Parameters

Parameter	Type	Description
`start_date`required	ISO 8601	Start of date range
`end_date`required	ISO 8601	End of date range
`calendar_id`optional	string	Filter by specific calendar
`include_recurring`optional	boolean	Expand recurring events (default: true)

Example Request cURL

curl -X GET "https://api.hyperplanner.app/v1/events?start_date=2024-01-15&end_date=2024-01-21" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response JSON

{
  "data": [
    {
      "id": "event_ghi789rst",
      "title": "Team Standup",
      "description": "Daily sync with engineering team",
      "start_at": "2024-01-15T10:00:00Z",
      "end_at": "2024-01-15T10:30:00Z",
      "all_day": false,
      "calendar_id": "cal_work",
      "color": "#6366f1",
      "location": "Zoom",
      "recurrence": {
        "frequency": "weekly",
        "days": ["mon", "wed", "fri"],
        "until": "2024-12-31"
      },
      "reminders": [
        {"type": "notification", "minutes_before": 10}
      ],
      "created_at": "2024-01-01T08:00:00Z",
      "updated_at": "2024-01-10T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "has_more": false
  }
}

POST /api/events

Create a new calendar event.

Request Body

Field	Type	Description
`title`required	string	Event title
`start_at`required	ISO 8601	Event start time
`end_at`required	ISO 8601	Event end time
`all_day`optional	boolean	All-day event flag
`calendar_id`optional	string	Target calendar ID
`color`optional	string	Hex color code
`location`optional	string	Event location or meeting link
`recurrence`optional	object	Recurrence pattern configuration
`reminders`optional	array	Array of reminder objects
`task_id`optional	string	Link to an existing task (time-blocking)

Example Request cURL

curl -X POST "https://api.hyperplanner.app/v1/events" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project Review",
    "start_at": "2024-01-16T14:00:00Z",
    "end_at": "2024-01-16T15:00:00Z",
    "calendar_id": "cal_work",
    "color": "#ec4899",
    "location": "Conference Room B",
    "reminders": [
      {"type": "notification", "minutes_before": 15},
      {"type": "email", "minutes_before": 60}
    ]
  }'

PUT /api/events/:id

Update an existing event. For recurring events, specify update scope.

Additional Parameters for Recurring Events

Parameter	Description
`update_scope: "single"`	Update only this occurrence
`update_scope: "future"`	Update this and all future occurrences
`update_scope: "all"`	Update all occurrences in the series

Example Request cURL

curl -X PUT "https://api.hyperplanner.app/v1/events/event_ghi789rst" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team Standup (Updated)",
    "start_at": "2024-01-15T10:30:00Z",
    "end_at": "2024-01-15T11:00:00Z",
    "update_scope": "future"
  }'

DELETE /api/events/:id

Delete a calendar event. For recurring events, specify deletion scope.

Example Request cURL

curl -X DELETE "https://api.hyperplanner.app/v1/events/event_ghi789rst?delete_scope=single" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Templates API

Templates allow you to create reusable task and project structures. Use them to quickly instantiate common workflows.

GET /api/templates

Retrieve available templates.

Example Request cURL

curl -X GET "https://api.hyperplanner.app/v1/templates" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response JSON

{
  "data": [
    {
      "id": "tmpl_weekly_review",
      "name": "Weekly Review",
      "description": "End-of-week reflection and planning checklist",
      "category": "productivity",
      "task_count": 8,
      "is_public": false,
      "created_at": "2024-01-05T10:00:00Z",
      "usage_count": 24
    },
    {
      "id": "tmpl_project_kickoff",
      "name": "Project Kickoff",
      "description": "Standard tasks for starting a new project",
      "category": "project",
      "task_count": 12,
      "is_public": true,
      "created_at": "2024-01-02T14:30:00Z",
      "usage_count": 156
    }
  ]
}

POST /api/templates

Create a new template from scratch or from existing tasks.

Example Request cURL

curl -X POST "https://api.hyperplanner.app/v1/templates" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blog Post Workflow",
    "description": "Standard workflow for publishing blog content",
    "category": "content",
    "is_public": false,
    "tasks": [
      {
        "title": "Research topic",
        "relative_due_days": 0,
        "priority": "high"
      },
      {
        "title": "Write first draft",
        "relative_due_days": 2,
        "priority": "high"
      },
      {
        "title": "Edit and revise",
        "relative_due_days": 3,
        "priority": "medium"
      },
      {
        "title": "Add images and formatting",
        "relative_due_days": 4,
        "priority": "medium"
      },
      {
        "title": "SEO optimization",
        "relative_due_days": 4,
        "priority": "low"
      },
      {
        "title": "Publish and promote",
        "relative_due_days": 5,
        "priority": "high"
      }
    ]
  }'

Example Response JSON

{
  "data": {
    "id": "tmpl_blog_workflow",
    "name": "Blog Post Workflow",
    "task_count": 6,
    "created_at": "2024-01-10T16:45:00Z"
  }
}

POST /api/templates/:id/instantiate

Create tasks from a template with a specified start date.

Example Request cURL

curl -X POST "https://api.hyperplanner.app/v1/templates/tmpl_blog_workflow/instantiate" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-01-20",
    "context": "work",
    "tags": ["blog", "marketing"]
  }'

Example Response JSON

{
  "data": {
    "template_id": "tmpl_blog_workflow",
    "tasks_created": 6,
    "task_ids": [
      "task_new001",
      "task_new002",
      "task_new003",
      "task_new004",
      "task_new005",
      "task_new006"
    ]
  }
}

Settings API

Read and update user preferences, notification settings, and app configuration.

GET /api/settings

Retrieve current user settings.

Example Response JSON

{
  "data": {
    "user_id": "user_abc123",
    "preferences": {
      "theme": "glassy_warm",
      "default_view": "split",
      "week_start": "monday",
      "time_format": "12h",
      "date_format": "MM/DD/YYYY",
      "timezone": "America/New_York",
      "default_task_duration": 30,
      "show_completed_tasks": true,
      "auto_archive_days": 7
    },
    "notifications": {
      "email_reminders": true,
      "push_notifications": true,
      "daily_digest": false,
      "digest_time": "08:00",
      "reminder_default_minutes": 15
    },
    "integrations": {
      "google_calendar": true,
      "slack": false,
      "github": true
    },
    "ai_features": {
      "enabled": true,
      "auto_suggestions": true,
      "smart_scheduling": false
    }
  }
}

PUT /api/settings

Update user settings. Supports partial updates.

Example Request cURL

curl -X PUT "https://api.hyperplanner.app/v1/settings" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "theme": "midnight_focus",
      "week_start": "sunday"
    },
    "notifications": {
      "daily_digest": true,
      "digest_time": "07:00"
    }
  }'

Example Response JSON

{
  "data": {
    "updated": true,
    "changes": [
      "preferences.theme",
      "preferences.week_start",
      "notifications.daily_digest",
      "notifications.digest_time"
    ],
    "updated_at": "2024-01-10T17:30:00Z"
  }
}

Error Codes

The API uses standard HTTP status codes and returns detailed error information in JSON format.

Error Response Format

Error Response Structure JSON

{
  "error": {
    "code": "invalid_request",
    "message": "The 'title' field is required",
    "field": "title",
    "doc_url": "https://docs.hyperplanner.app/errors#invalid_request"
  }
}

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created successfully
204	No Content	Request succeeded with no response body
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Valid auth but insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Resource conflict (e.g., duplicate)
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service unavailable
503	Service Unavailable	API temporarily unavailable

Error Codes Reference

Error Code	Description	Resolution
`invalid_request`	Request body is malformed	Check JSON syntax and required fields
`invalid_api_key`	API key is invalid or expired	Generate a new key in Settings
`insufficient_scope`	Token lacks required scope	Request additional OAuth scopes
`resource_not_found`	Requested resource doesn't exist	Verify the resource ID
`validation_error`	Field validation failed	Check field constraints in docs
`rate_limit_exceeded`	Too many requests	Wait and retry with backoff
`quota_exceeded`	Plan limit reached	Upgrade plan or wait for reset
`conflict`	Resource state conflict	Fetch latest state and retry

Webhooks

Webhooks allow you to receive real-time notifications when events occur in HyperPlanner. Configure endpoints to be notified of task completions, event changes, and more.

Setting Up Webhooks

Create webhooks via the API or in Settings > Developer > Webhooks.

Create Webhook cURL

curl -X POST "https://api.hyperplanner.app/v1/webhooks" \
  -H "Authorization: Bearer hp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/hyperplanner",
    "events": ["task.created", "task.completed", "event.created"],
    "secret": "your_webhook_secret_for_verification"
  }'

Available Webhook Events

Event	Description
`task.created`	A new task was created
`task.updated`	A task was modified
`task.completed`	A task was marked as complete
`task.deleted`	A task was deleted
`event.created`	A new calendar event was created
`event.updated`	A calendar event was modified
`event.deleted`	A calendar event was deleted
`template.used`	A template was instantiated

Webhook Payload Format

Example Webhook Payload JSON

{
  "id": "whevt_abc123",
  "type": "task.completed",
  "created_at": "2024-01-10T18:00:00Z",
  "data": {
    "task": {
      "id": "task_def456uvw",
      "title": "Prepare presentation",
      "status": "completed",
      "completed_at": "2024-01-10T18:00:00Z"
    },
    "previous_status": "in_progress"
  }
}

Verifying Webhook Signatures

Each webhook request includes an X-HyperPlanner-Signature header containing an HMAC-SHA256 signature. Verify this to ensure the request came from HyperPlanner.

Signature Verification (Node.js) JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}

Webhook Reliability

Webhooks are delivered with automatic retries (3 attempts with exponential backoff). If your endpoint returns a non-2xx status code, we'll retry. Always return 200 OK quickly and process asynchronously.

SDKs & Libraries

Official SDKs are in development to make API integration easier. Sign up to be notified when they launch.

📜

JavaScript/Node.js

Coming Q1 2024

🐍

Python

Coming Q1 2024

💼

Ruby

Coming Q2 2024

⚙

Go

Coming Q2 2024

☕

Java

Coming Q3 2024

🔌

PHP

Coming Q3 2024

Community Libraries

The community has created unofficial libraries for various languages. Check our Community Resources page for a curated list. Note that these are not officially supported.

API Client Best Practices

Use environment variables for API keys, never hardcode them
Implement retry logic with exponential backoff for failed requests
Cache responses where appropriate to reduce API calls
Handle pagination for list endpoints that return many results
Validate input before sending to avoid unnecessary API errors
Log API interactions for debugging (without logging sensitive data)

Need Help?

If you have questions about the API or need assistance with your integration:

💬

Developer Forum

Ask questions and share solutions with other developers.

📧

API Support

Contact api-support@hyperplanner.app for technical issues.

🛠

Status Page

Check status.hyperplanner.app for service status.

📖

Changelog

Stay updated on API changes and new features.