IntelliPlan REST API: Developer Reference and Overview

The IntelliPlan REST API gives your application direct, programmatic access to the same student data that powers the IntelliPlan dashboard — assignments, grades, study schedules, streak progress, and the learner identity profile. Every route lives under a stable v1 prefix, every response carries a traceable request ID, and every failure uses a single, predictable error envelope so you never have to guess what went wrong. Whether you are building a mobile companion app, an automation script, or a custom integration, this reference is your starting point.

Base URL

All API requests target the following base URL. There are no environment-specific subdomains — the versioned path is the stable surface.

https://intelliplan.tech/api/v1/

Every path in this reference is relative to the base URL above. For example, GET /api/v1/me is the full path for the authenticated user endpoint.

Authentication

The API supports two authentication schemes. They are not interchangeable — use the one that matches your use case.

Scheme	Header	Best For
API Key	`X-API-Key: ip_live_…`	Third-party apps and integrations
Bearer Token	`Authorization: Bearer …`	First-party clients (MCP server, browser extension)

API Keys are scoped, revocable, and rate-limited per key. Apply for one at intelliplan.tech/developers. Read-only applications are approved automatically; anything requesting write scopes goes to a human reviewer. Bearer Tokens are obtained by posting credentials to POST /api/v1/auth/token. They carry every scope and cannot be revoked without rotating the server’s secret key — so they are reserved for first-party clients where the user is authenticating as themselves. See the Authentication guide for detailed instructions, scope definitions, and code examples.

Liveness Probe

Before burning rate-limit budget, you can confirm the API is reachable without any credential:

Health check

curl https://intelliplan.tech/api/v1/health

Response

{
  "status": "ok",
  "version": "v1",
  "time": "2025-01-15T18:32:00.000000"
}

A Simple Authenticated Request

Here is a complete example using an API key to fetch the authenticated user’s profile:

Fetch your profile with an API key

curl https://intelliplan.tech/api/v1/me \
  -H "X-API-Key: ip_live_YOUR_KEY_HERE"

Response

{
  "id": 42,
  "email": "student@university.edu",
  "name": "Alex Chen",
  "created_at": "2024-09-01T12:00:00",
  "credential": {
    "type": "api_key",
    "app_name": "My Study App",
    "key_prefix": "ip_live_abc123",
    "scopes": ["read:profile", "read:assignments"]
  }
}

Response Headers

Every response from /api/v1/* includes these headers regardless of success or failure:

Header	Description
`X-Request-Id`	A 16-character hex ID unique to this request. Provide this when reporting issues.
`X-IntelliPlan-API-Version`	Always `v1`.
`X-RateLimit-Limit`	Requests per minute ceiling for the authenticated key.
`Cache-Control`	Always `no-store` — API responses are per-credential and must not be cached.

Error Envelope

Every failure — regardless of the HTTP status code — returns the same JSON envelope. Your error handler only needs to be written once.

Error envelope format

{
  "status": "error",
  "error": "insufficient_scope",
  "message": "This key is not authorized for that. Missing scope(s): read:grades.",
  "request_id": "a1b2c3d4e5f60718"
}

status

string

Always "error" on failure.

error

string

A machine-readable error code. See the table below.

message

string

A human-readable explanation. Suitable to display in logs; not guaranteed stable across releases.

request_id

string

The same 16-character hex ID as the X-Request-Id response header. Quote this when filing a support request.

Error Codes

Code	HTTP Status	When It Appears
`invalid_request`	400	Missing or malformed request parameters
`unauthorized`	401	No valid credential sent
`insufficient_scope`	403	Credential is valid but lacks a required scope
`not_found`	404	No endpoint at this path
`method_not_allowed`	405	Wrong HTTP verb for this endpoint
`rate_limited`	429	Too many requests; back off and retry
`upstream_failed`	502	IntelliPlan’s internal call to the school platform failed
`server_error`	500	Unexpected server-side failure

When you receive a rate_limited error, the response may include a retry_after field with the number of seconds to wait before retrying.

Versioning

The current API version is v1, reflected in every path and in the X-IntelliPlan-API-Version response header. The API index at GET /api/v1/ (or GET /api/v1/docs) always returns the current version, available scopes, and a live listing of all endpoints.

API discovery

curl https://intelliplan.tech/api/v1/docs

Rate Limiting

Rate limits are enforced per credential, not per IP address. This means a noisy integration cannot consume another key’s budget, and multiple users behind a shared office network each get their own allowance.

Tier	Default limit
Standard (auto-approved read-only keys)	60 requests / minute
Medium volume (self-declared, approved)	300 requests / minute
High volume (self-declared, human-reviewed)	1,000 requests / minute

The X-RateLimit-Limit header on every response tells you the ceiling for the current key. When you exceed it, you receive a 429 rate_limited error. Back off exponentially and resume when retry_after seconds have elapsed.

Rate limit ceilings for medium and high volume tiers are self-declared at application time. High-volume applications are subject to human review before approval.

Applying for an API Key

Navigate to intelliplan.tech/developers while signed in to your IntelliPlan account. You will need:

Describe your application

Provide an app name and a use-case description of at least 40 characters. This is what reviewers read for write-scope applications.

Select scopes

Choose the minimum scopes your integration needs. Read-only scopes are auto-approved; write scopes require human review (typically within two business days).

Declare expected volume

Choose low, medium, or high. This sets your initial rate-limit ceiling.

Accept the API terms

Check the acceptance box to proceed.

Copy your key immediately

Auto-approved applications receive the key in the same response. The plaintext secret is shown exactly once. IntelliPlan stores only a SHA-256 hash — if you lose the key, roll it from the developer dashboard.

Each IntelliPlan account can hold up to 5 active or pending keys. Revoke unused keys before applying for new ones.

Endpoint Groups

Identity & Profile

GET /api/v1/me — authenticated user info. GET /api/v1/identity and PATCH /api/v1/identity — student learning profile (grade level, focus areas, goals, availability). Requires read:profile.

Assignments

GET /api/v1/assignments — unified assignment feed from every connected platform. GET /api/v1/tasks — all tasks including manual and Notion-synced items. POST /api/v1/tasks — create a manual task. POST /api/v1/assignments/dismiss and /restore — mark done or undo. Requires read:assignments or write:tasks.

Tests

GET /api/v1/tests — all assignments flagged as tests. POST /api/v1/tests — mark an assignment as a test. DELETE /api/v1/tests — unmark a test. Requires read:tests or write:tests.

Schedule

GET /api/v1/schedule — retrieve the student’s saved study plan. POST /api/v1/schedule/generate — build a new AI study schedule. Accepts assignments, hours_per_day, preferred_time, and custom_tasks. Requires read:schedule.

Grades

GET /api/v1/grades — course grades and GPA from the connected school platform. Grades carry their own scope (read:grades) separate from assignments — knowing what is due is a different trust level than knowing what the student scored.

Streak & Sparks

GET /api/v1/streak — streak length, sparks balance, freeze count, current level, and quest state. Requires read:streak.

Push Notifications

POST /api/v1/push/register — register an Expo push token for deadline reminders. POST /api/v1/push/unregister — remove a device token on sign-out. Requires read:profile.

Authentication

POST /api/v1/auth/token — exchange email and password for a Bearer token. No credential required to call; returns token, token_type, scopes, and basic user info.

Discovery Endpoint

The API self-documents. GET /api/v1/ (or GET /api/v1/docs) returns a complete machine-readable index of every endpoint, all scopes and their descriptions, the error shape, and current rate-limit policy — no authentication required.

Fetch the API index

curl https://intelliplan.tech/api/v1/docs

Next Steps

Authentication

Learn how to obtain an API key or Bearer token, understand scopes, and see code samples for both auth methods.

Developers Portal

Apply for an API key, manage your applications, and roll compromised keys from the developer dashboard.

Overview

Endpoints

Developer Tools

IntelliPlan REST API: Developer Reference and Overview

Base URL

Authentication

Liveness Probe

A Simple Authenticated Request

Response Headers

Error Envelope

Error Codes

Versioning

Rate Limiting

Applying for an API Key

Endpoint Groups

Identity & Profile

Assignments

Tests

Schedule

Grades

Streak & Sparks

Push Notifications

Authentication

Discovery Endpoint

Next Steps

Authentication

Developers Portal

Build docs developers (and LLMs) love

Overview

Endpoints

Developer Tools

Documentation Index

​Base URL

​Authentication

​Liveness Probe

​A Simple Authenticated Request

​Response Headers

​Error Envelope

​Error Codes

​Versioning

​Rate Limiting

​Applying for an API Key

​Endpoint Groups

Identity & Profile

Assignments

Tests

Schedule

Grades

Streak & Sparks

Push Notifications

Authentication

​Discovery Endpoint

​Next Steps

Authentication

Developers Portal

Build docs developers (and LLMs) love

Base URL

Authentication

Liveness Probe

A Simple Authenticated Request

Response Headers

Error Envelope

Error Codes

Versioning

Rate Limiting

Applying for an API Key

Endpoint Groups

Discovery Endpoint

Next Steps