View Markdown
v1

Heights Platform API Docs

This reference documents the currently available Heights Platform API endpoints for customers and integration partners. Requests are account-specific, authenticated by API key, and return JSON responses.

Base URL

https://{account_subdomain}.heightsplatform.com/api/v1/...

Authentication

Use an admin user API key in the Authorization header:

Authorization: Token token=YOUR_API_KEY

Bearer tokens are also accepted: Authorization: Bearer YOUR_API_KEY.

Content Type

  • Responses are JSON.
  • Use Content-Type: application/json when sending JSON bodies.

Rate Limiting

Public API requests are rate limited per account: standard accounts receive 60 requests per minute, and Academy plan accounts receive 300 requests per minute.

Response Headers

  • X-Request-Id for support/debugging.
  • X-API-Version: v1.

Pagination

Students are paginated by default. Orders support optional pagination when a page parameter is provided.

Current behavior

  • GET /api/v1/students?page=N
  • Page size is fixed at 50.
  • GET /api/v1/orders?page=N&per_page=50
  • Order per_page is capped at 100.
Example meta block 
{
  "meta": {
    "total_pages": 12,
    "total_students": 587
  }
}

Errors

The API currently uses standard HTTP status codes.

401 Unauthorized — Missing or invalid API token.
403 Forbidden — Token is valid but not allowed, such as a non-admin API key.
404 Not Found — Record not found or endpoint unavailable.
422 Unprocessable Entity — Validation failure, typically with a JSON error body.
429 Too Many Requests — Rate limit exceeded.

Account

Inspect the authenticated admin API user, account metadata, capabilities, and supported webhook events.

GET
/api/v1/account

Returns account details and API capabilities for the authenticated admin key.

Example response 
{
  "account": {
    "id": 1,
    "subdomain": "academy",
    "app_name": "Academy",
    "custom_domain": null,
    "currency": "USD",
    "locale": "en"
  },
  "user": {
    "id": 10,
    "name": "Admin Name",
    "email": "[email protected]",
    "admin": true
  },
  "capabilities": {
    "admin_api": true,
    "read_orders": true,
    "read_order_webhook_payloads": true,
    "webhooks": true
  },
  "webhook_events": ["new_student", "new_order", "course_completed", "student_completed", "new_answer", "new_project_post"]
}

Courses

Read published courses, fetch course details, retrieve roles, and check completion for a specific student.

GET
/api/v1/courses

Returns published courses.

Notes

  • Only published courses are returned.
Example response 
{
  "courses": [
    {
      "id": 123,
      "title": "Example Course",
      "sold_separately": true,
      "price": "99.0"
    }
  ]
}
GET
/api/v1/courses/:id

Returns detailed metadata for a single course.

Example response 
{
  "id": 123,
  "title": "Example Course",
  "description": "...",
  "slug": "example-course",
  "sold_separately": true,
  "price": "99.0",
  "is_published": true,
  "is_challenge": false,
  "cover_image_url": "https://...",
  "cover_image_thumbnail_url": "https://...",
  "unsplash_image_url": "https://...",
  "lesson_count": 12
}
GET
/api/v1/courses/roles

Lists available roles that can be granted to students.

Example response 
{
  "roles": [
    { "id": 1, "name": "Gold" }
  ]
}
POST
/api/v1/courses/:id/completion-percentage

Returns overall and course-specific completion data for a student identified by email.

Parameter Type Required Description
user_email string Yes Email address of the student to inspect.
Example request 
curl -X POST \
  -H 'Authorization: Token token=YOUR_API_KEY' \
  -d '[email protected]' \
  https://{subdomain}.heightsplatform.com/api/v1/courses/123/completion-percentage
Example response 
{
  "id": 55,
  "name": "Student Name",
  "email": "[email protected]",
  "created_at": "2024-01-01T12:00:00Z",
  "enrolled": true,
  "admin": false,
  "is_active": true,
  "sign_in_count": 3,
  "points": 120,
  "completion_percent": 42,
  "course_completion_percent": 25
}

Bundles / Offers

Bundles are also referred to in parts of the UI as offers.

GET
/api/v1/bundles

Lists bundles.

Example response 
{
  "bundles": [
    { "id": 10, "title": "Starter Offer" }
  ]
}
GET
/api/v1/bundles/:id

Returns detailed metadata for a single bundle.

Example response 
{
  "id": 10,
  "title": "Starter Offer",
  "description": "...",
  "slug": "starter-offer",
  "is_published": true,
  "cover_image_thumbnail_url": "https://...",
  "product_count": 3
}

Digital Products

Retrieve digital product listings and individual product metadata.

GET
/api/v1/digital_products

Lists digital products.

Example response 
{
  "digital_products": [
    {
      "id": 7,
      "title": "Workbook PDF",
      "description": "...",
      "price": "29.0",
      "is_published": true,
      "cover_image_url": "https://..."
    }
  ]
}
GET
/api/v1/digital_products/:id

Returns metadata for a single digital product.

Example response 
{
  "id": 7,
  "title": "Workbook PDF",
  "description": "...",
  "product_type": "download",
  "slug": "workbook-pdf",
  "price": "29.0",
  "is_published": true,
  "cover_image_url": "https://..."
}

Orders

Retrieve paid orders by default, filter order lists, and fetch a single order using the same shape as the new_order webhook payload.

GET
/api/v1/orders

Returns orders where status = "paid" unless a different status filter is supplied.

Query Parameter Required Description
status No One of pending, failed, paid, paypal_executed, or all. Defaults to paid.
user_email No Exact student email match.
created_after / created_before No ISO-8601 date/time filters.
page / per_page No Optional pagination. per_page is capped at 100.
Example response 
{
  "orders": [
    {
      "id": "ORD_ABC123",
      "amount": "99.0",
      "currency": "USD",
      "description": "Course Purchase",
      "user_email": "[email protected]",
      "user_name": "Student Name",
      "user_first_name": "Student",
      "user_last_name": "Name",
      "status": "paid",
      "affiliate_id": null,
      "courses": [
        { "id": 123, "title": "Example Course" }
      ],
      "digital_products": [],
      "bundles": [],
      "billing_city": "Austin",
      "billing_state": "TX",
      "billing_country": "US",
      "billing_street": "123 Main St",
      "billing_zip": "78701",
      "billing_company": null,
      "billing_phone": null,
      "created_at": "2024-01-01T12:00:00Z",
      "updated_at": "2024-01-01T12:00:00Z"
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_orders": 1,
    "current_page": 1,
    "per_page": 50
  }
}
GET
/api/v1/orders/:id

:id is the public unique_order value returned as id by order list responses and the new_order webhook. The response is a single order object using the webhook field shape.

Example response 
{
  "id": "ORD_ABC123",
  "amount": "99.0",
  "currency": "USD",
  "description": "Course Purchase",
  "user_email": "[email protected]",
  "user_name": "Student Name",
  "user_first_name": "Student",
  "user_last_name": "Name",
  "status": "paid",
  "affiliate_id": null,
  "courses": [
    { "id": 123, "title": "Example Course" }
  ],
  "digital_products": [],
  "bundles": [],
  "billing_city": "Austin",
  "billing_state": "TX",
  "billing_country": "US",
  "billing_street": "123 Main St",
  "billing_zip": "78701",
  "billing_company": null,
  "billing_phone": null,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}

Students

Read student lists, details, and related assignment/project data.

GET
/api/v1/students?page=N

Lists students in paginated form.

Pagination

  • Use the page query parameter.
  • Page size is fixed at 50.
Example response 
{
  "students": [
    {
      "id": 55,
      "name": "Student Name",
      "email": "[email protected]",
      "created_at": "2024-01-01T12:00:00Z",
      "location": null,
      "facebook_link": null,
      "twitter_link": null,
      "enrolled": true,
      "admin": false,
      "is_active": true,
      "sign_in_count": 3,
      "points": 120,
      "completion_percent": 42
    }
  ],
  "meta": {
    "total_pages": 12,
    "total_students": 587
  }
}
GET
/api/v1/students/[email protected]

Returns student details by email.

Includes

  • Student attributes
  • Lesson views count
  • Lesson completions count
  • Paid orders
  • Enrolled courses
GET
/api/v1/students/completions

Returns students whose total_completion >= 100.

GET
/api/v1/students/answers

Returns all assignment answers.

GET
/api/v1/students/project-posts

Returns all project posts.

Student Access Management

These action-style endpoints live under the singular student resource and are all POST requests.

POST
/api/v1/student/enroll

Creates or updates a student and optionally grants access to a course or bundle by creating a $0 paid order.

Parameter Type Required Description
email string Yes Student email address.
name string Required when creating Name for a new student record.
course_id integer No Grant access to a course by creating a $0 paid order.
bundle_id integer No Grant access to a bundle by creating a $0 paid order.

If both course_id and bundle_id are supplied, separate $0 orders are created.

Example request 
curl -X POST \
  -H 'Authorization: Token token=YOUR_API_KEY' \
  -d '[email protected]&name=Student Name&course_id=123' \
  https://{subdomain}.heightsplatform.com/api/v1/student/enroll
POST
/api/v1/student/unenroll

Unenrolls a student from paid membership by setting paying_student=false.

Parameter Type Required Description
email string Yes Student email address.
name string Yes Student name.
POST
/api/v1/student/revoke-course

Removes a course from each of the student’s orders.

Parameter Type Required Description
email string Yes Student email address.
name string Yes Student name.
course_id integer Yes Course to revoke.
POST
/api/v1/student/revoke-bundle

Removes bundle access and also removes the bundle’s courses and digital products from orders.

Parameter Type Required Description
email string Yes Student email address.
bundle_id integer Yes Bundle to revoke.
POST
/api/v1/student/grant-role

Grants a role to a student.

Parameter Type Required Description
email string Yes Student email address.
role_id integer Yes Role to grant.
POST
/api/v1/student/revoke-role

Revokes a role from a student.

Parameter Type Required Description
email string Yes Student email address.
role_id integer Yes Role to revoke.
POST
/api/v1/student/reset-course-progress

Resets a student’s completion/progress records for a single course. Requires permission to reset the course.

Parameter Type Required Description
email string Yes Student email address.
course_id integer Yes Course progress to reset.
POST
/api/v1/student/reset-bundle-progress

Resets a student’s completion/progress records for all courses in a bundle. Requires permission to reset the bundle.

Parameter Type Required Description
email string Yes Student email address.
bundle_id integer Yes Bundle progress to reset.

Webhooks

Heights has an existing webhook subscription system. Use the existing subscription UI instead of building duplicate webhook routes for customer integrations.

Subscription process

How to subscribe

  • Sign in to the Heights account as an admin.
  • Go to Account Settings → Integrations → Webhooks.
  • Enter a target URL, choose an event, and save the subscription.
Available events
Event When it triggers
new_studentStudent enrolls in the program.
new_orderAn order is generated, including paid purchases and granted access orders.
course_completedStudent completes a course.
student_completedStudent reaches 100% program completion.
new_answerStudent submits an assignment answer.
new_project_postStudent posts in a project.
new_order payload

The new_order webhook payload matches GET /api/v1/orders/:id.

{
  "id": "ORD_ABC123",
  "amount": "99.0",
  "currency": "USD",
  "description": "Course Purchase",
  "user_email": "[email protected]",
  "user_name": "Student Name",
  "user_first_name": "Student",
  "user_last_name": "Name",
  "status": "paid",
  "affiliate_id": null,
  "courses": [
    { "id": 123, "title": "Example Course" }
  ],
  "digital_products": [],
  "bundles": [],
  "billing_city": "Austin",
  "billing_state": "TX",
  "billing_country": "US",
  "billing_street": "123 Main St",
  "billing_zip": "78701",
  "billing_company": null,
  "billing_phone": null,
  "created_at": "2024-01-01T12:00:00Z",
  "updated_at": "2024-01-01T12:00:00Z"
}
Other payload examples
// new_student and student_completed
{
  "id": 55,
  "name": "Student Name",
  "email": "[email protected]"
}

// course_completed
{
  "id": 55,
  "name": "Student Name",
  "email": "[email protected]",
  "course": "Example Course",
  "course_id": 123
}

// new_answer
{
  "id": 55,
  "name": "Student Name",
  "email": "[email protected]",
  "answer": "My answer text",
  "question": "Assignment prompt",
  "lesson": "Lesson Title"
}

// new_project_post
{
  "id": 55,
  "name": "Student Name",
  "email": "[email protected]",
  "post": "Project post title"
}

View or copy the markdown version to provide to AI agents using the controls above, or View Markdown here.