API Reference

EliteCircle's REST API gives you full programmatic control over users, memberships, subscriptions, and courses. Build custom integrations, automate workflows, and power your own applications.

BASE URL: https://api.elitecircle.com/v2

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authentication

EliteCircle uses API keys to authenticate requests. You can manage your API keys from the Dashboard > Developer Settings. Keep your API keys secret — do not share them in publicly accessible locations.

💡 Best Practice Use separate keys for development and production. Never commit API keys to version control.

API Key Format

API keys start with ec_live_ for production and ec_test_ for sandbox/test environments. Always use test keys during development.

Bash

curl https://api.elitecircle.com/v2/memberships \
  -H "Authorization: Bearer ec_live_sk_4f8a2b..." \
  -H "Content-Type: application/json"

Python

import elitecircle

elitecircle.api_key = "ec_live_sk_4f8a2b..."

memberships = elitecircle.Membership.list()

Node.js

const elitecircle = require('elitecircle')('ec_live_sk_4f8a2b...');

const memberships = await elitecircle.memberships.list();

OAuth 2.0

For applications that act on behalf of users, use OAuth 2.0 with the membership:read, membership:write, subscription:read, and subscription:write scopes.

Authorization Request

GET https://auth.elitecircle.com/oauth/authorize?
  client_id=your_client_id
&redirect_uri=https://yourapp.com/callback
&response_type=code
&scope=membership:read subscription:write

Base URL & Versions

The current stable API version is v2. We maintain backward compatibility within major versions and deprecate old versions with at least 12 months of notice.

Version	Status	Deprecation Date	Notes
v2 (current)	Active	—	Latest version with all features
v1	Deprecated	Dec 31, 2025	Legacy — migrate to v2

HTTP Methods

Method	Description
GET	Retrieve a resource or collection of resources
POST	Create a new resource or trigger an action
PUT	Update an existing resource (full replacement)
PATCH	Partially update an existing resource
DEL	Delete a resource permanently

Errors

EliteCircle uses standard HTTP status codes to indicate the success or failure of a request. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Error Response Format

{
  "error": {
    "code": "invalid_request_error",
    "message": "The card was declined.",
    "type": "card_error",
    "param": "card",
    "code_param": "card_declined"
  }
}

Common Error Codes

400

Bad Request — Malformed request or missing required fields

401

Unauthorized — Invalid or expired API key

403

Forbidden — Insufficient permissions for this action

404

Not Found — The requested resource does not exist

409

Conflict — Resource already exists or state conflict

429

Too Many Requests — Rate limit exceeded

500

Server Error — An unexpected error occurred

503

Service Unavailable — Temporary maintenance

⚠️ Retry Strategy For 429 and 5xx errors, implement exponential backoff. Retry at most 3 times with delays of 1s, 2s, and 4s.

Rate Limiting

API requests are rate limited per API key. You can inspect your remaining requests from the response headers.

100

Requests per minute

Shared across all endpoints

1,000

Requests per day

Reset at midnight UTC

Response Headers

Header	Description
X-RateLimit-Limit	Maximum requests allowed per minute
X-RateLimit-Remaining	Remaining requests in current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait before retrying (only on 429)

Users

Users represent individual accounts in the EliteCircle platform. Each user can have one or more memberships and subscriptions.

GET /users List all users

Returns a paginated list of all users. Use query parameters to filter and sort results.

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Number of results (1–100, default 20)
cursor	string	No	Pagination cursor from previous response
status	string	No	Filter by: `active`, `paused`, `canceled`
created_after	datetime	No	Filter users created after this date

Example Request

Bash

curl https://api.elitecircle.com/v2/users?limit=10&status=active \
  -H "Authorization: Bearer ec_live_sk_4f8a2b..."

Example Response

JSON

{
  "data": [
    {
      "id": "usr_8f3k2m9n1p",
      "email": "sarah.chen@example.com",
      "name": "Sarah Chen",
      "avatar_url": "https://cdn.elitecircle.com/avatars/usr_8f3k2m9n1p.jpg",
      "status": "active",
      "member_since": "2024-01-15T10:30:00Z",
      "membership_tier": "professional",
      "metadata": {},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2025-06-10T14:22:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6InVzcl8..."
}

POST /users Create a new user

Creates a new user account in your EliteCircle organization.

Request Body

Parameter	Type	Required	Description
email	string	Yes	User's email address (must be unique)
name	string	Yes	Full display name
membership_tier	string	No	Auto-enroll tier: `starter`, `professional`, `enterprise`
metadata	object	No	Custom key-value pairs (max 20 keys)

JSON Request Body

{
  "email": "newuser@example.com",
  "name": "Marcus Rodriguez",
  "membership_tier": "professional",
  "metadata": {
    "source": "api",
    "team_id": "team_abc123"
  }
}

Response

JSON — 201 Created

{
  "id": "usr_3m7k9p2q5r",
  "email": "newuser@example.com",
  "name": "Marcus Rodriguez",
  "status": "active",
  "membership_tier": "professional",
  "created_at": "2025-06-15T08:00:00Z"
}

GET /users/{user_id} Retrieve a user

Retrieves the details of an existing user.

ℹ️ Note Returns a 404 error if the user ID does not exist. The {user_id} is a path parameter.

JSON Response

{
  "id": "usr_8f3k2m9n1p",
  "email": "sarah.chen@example.com",
  "name": "Sarah Chen",
  "status": "active",
  "membership": {
    "id": "mem_x7y2w4z8",
    "tier": "professional",
    "current_period_start": "2025-06-01T00:00:00Z",
    "current_period_end": "2025-07-01T00:00:00Z",
    "trial_ends_at": null
  },
  "created_at": "2024-01-15T10:30:00Z"
}

PUT /users/{user_id} Update a user

Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

JSON Request Body

{
  "name": "Sarah Chen-Chang",
  "metadata": {
    "department": "engineering"
  }
}

DELETE /users/{user_id} Delete a user

Permanently deletes a user and all associated data. This action cannot be undone.

🚨 Destructive Action Deleting a user also removes their membership, subscription history, course progress data, and any content they've created. A user.deleted webhook will be triggered.

JSON Response — 200 OK

{
  "id": "usr_8f3k2m9n1p",
  "deleted": true
}

Memberships

Memberships define a user's access tier and entitlements within the EliteCircle platform. Each user can have at most one active membership at a time.

GET /memberships List all memberships

Example Response

JSON

{
  "data": [
    {
      "id": "mem_x7y2w4z8",
      "user_id": "usr_8f3k2m9n1p",
      "tier": "professional",
      "status": "active",
      "current_period_start": "2025-06-01T00:00:00Z",
      "current_period_end": "2025-07-01T00:00:00Z",
      "trial_ends_at": null,
      "entitlements": {
        "unlimited_courses": true,
        "live_sessions": "weekly",
        "mentorship": true,
        "ai_paths": true,
        "certifications": true
      },
      "created_at": "2025-06-01T00:00:00Z"
    }
  ],
  "has_more": false
}

POST /memberships Create a membership

Request Body

JSON

{
  "user_id": "usr_8f3k2m9n1p",
  "tier": "professional",
  "billing_cycle": "monthly",
  "coupon_code": "LAUNCH2025",
  "trial_days": 14
}

GET /memberships/{membership_id} Retrieve a membership

Returns the full membership object including entitlements, billing info, and subscription details.

PUT /memberships/{membership_id} Update a membership

Used to change membership tier (upgrade/downgrade). Changes to tier take effect at the next billing cycle.

JSON Request Body

{
  "tier": "enterprise",
  "effective_date": "next_billing_period"
}

DELETE /memberships/{membership_id} Cancel a membership

Cancels the membership at the end of the current billing period. The user retains access until the period expires.

💡 Tip Use Cancellation-Reason header to track why the membership was canceled.

Subscriptions

Subscriptions handle recurring billing for memberships. Each subscription is tied to a specific membership and includes payment details, invoices, and usage metrics.

POST /subscriptions Create a subscription

Request Body

Parameter	Type	Required	Description
membership_id	string	Yes	ID of the membership to subscribe
payment_method_id	string	Yes	Stripe payment method token
billing_cycle	string	No	`monthly` or `yearly` (default: `monthly`)
coupon_code	string	No	Discount coupon code
metadata	object	No	Custom metadata for the subscription

Example Response

JSON — 200 Created

{
  "id": "sub_m4n7p2q9r3",
  "membership_id": "mem_x7y2w4z8",
  "status": "active",
  "tier": "professional",
  "amount": 4900,
  "currency": "usd",
  "billing_cycle": "monthly",
  "next_payment_date": "2025-07-01T00:00:00Z",
  "payment_method": {
    "id": "pm_1N2o3p4q5r",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2027
  },
  "created_at": "2025-06-01T10:00:00Z"
}

PUT /subscriptions/{subscription_id} Update a subscription

Updates payment method, billing cycle, or applies a coupon to an existing subscription.

JSON Request Body

{
  "billing_cycle": "yearly",
  "payment_method_id": "pm_new_card_token",
  "coupon_code": "SAVE20"
}

POST /subscriptions/{subscription_id}/pause Pause a subscription

Pauses the subscription, keeping the user's data intact. The pause can last up to 90 days. The user retains access to their content during the pause period.

POST /subscriptions/{subscription_id}/cancel Cancel a subscription

Cancels the subscription. The user's access continues until the end of the current billing period. No further charges are made.

GET /subscriptions/{subscription_id}/invoices List invoices

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by: `paid`, `pending`, `failed`
limit	integer	No	Number of invoices (default 10)

Example Invoice Response

JSON

{
  "id": "inv_k8j3m2p5q9",
  "subscription_id": "sub_m4n7p2q9r3",
  "amount": 4900,
  "currency": "usd",
  "status": "paid",
  "description": "Professional tier — June 2025",
  "due_date": "2025-06-01T00:00:00Z",
  "paid_at": "2025-06-01T10:05:23Z",
  "pdf_url": "https://cdn.elitecircle.com/invoices/inv_k8j3m2p5q9.pdf",
  "line_items": [
    {
      "description": "Professional Monthly Plan",
      "amount": 4900,
      "quantity": 1
    }
  ]
}

Courses

Access the full catalog of courses available within EliteCircle. Course data includes metadata, pricing, instructor info, and progress tracking.

GET /courses List all courses

Example Response

JSON

{
  "data": [
    {
      "id": "crs_9a2b3c4d5e",
      "title": "Advanced React Patterns",
      "description": "Master modern React with advanced hooks, patterns, and performance optimization.",
      "instructor": {
        "name": "Alex Kim",
        "title": "Senior Engineer at Vercel"
      },
      "category": "engineering",
      "level": "advanced",
      "duration_hours": 12,
      "lessons_count": 48,
      "is_published": true,
      "thumbnail_url": "https://cdn.elitecircle.com/courses/crs_9a2b3c4d5e/thumb.jpg",
      "tags": [
        "react",
        "javascript",
        "web-dev"
      ],
      "requires_tier": "professional",
      "created_at": "2025-03-15T00:00:00Z"
    }
  ],
  "has_more": true
}

GET /courses/{course_id} Retrieve a course

Returns the full course object including the complete curriculum (lessons, quizzes, assignments), instructor details, and student enrollment counts.

POST /courses Create a course (instructor only)

Only instructors and content admins can create courses. The course enters a draft state and must be published manually.

JSON Request Body

{
  "title": "Building AI-Powered Apps",
  "description": "Learn to integrate LLMs into web applications.",
  "category": "engineering",
  "level": "intermediate",
  "lessons": [
    {
      "title": "Introduction to LLMs",
      "type": "video",
      "duration_minutes": 25,
      "content_url": "https://cdn.elitecircle.com/lessons/..."
    }
  ]
}

Webhooks

EliteCircle sends webhook events to notify your server of important platform events. Configure your webhook endpoint in the Dashboard > Developer > Webhooks.

💡 Security Always verify webhook signatures using the X-EliteCircle-Signature header and your webhook secret key.

Event Types

membership.created When a new membership is created

JSON Payload

{
  "id": "evt_7k3m9p2q",
  "type": "membership.created",
  "created_at": "2025-06-01T10:00:00Z",
  "data": {
    "id": "mem_x7y2w4z8",
    "user_id": "usr_8f3k2m9n1p",
    "tier": "professional",
    "status": "active",
    "trial_ends_at": "2025-06-15T00:00:00Z"
  }
}

subscription.payment_succeeded When a payment is processed successfully

JSON Payload

{
  "id": "evt_2n5p8q3r",
  "type": "subscription.payment_succeeded",
  "created_at": "2025-07-01T00:00:00Z",
  "data":
  {
    "subscription_id": "sub_m4n7p2q9r3",
    "invoice_id": "inv_k8j3m2p5q9",
    "amount": 4900,
    "currency": "usd",
    "payment_method": "visa_4242"
  }
}

subscription.payment_failed When a payment attempt fails

JSON Payload

{
  "id": "evt_9m2p5q8r",
  "type": "subscription.payment_failed",
  "created_at": "2025-07-01T00:00:00Z",
  "data": {
    "subscription_id": "sub_m4n7p2q9r3",
    "failure_reason": "card_declined",
    "amount": 4900
  }
}

All Available Events

Event Type	Description
user.created	New user registered
user.updated	User profile updated
user.deleted	User permanently deleted
membership.created	New membership created
membership.updated	Membership tier changed
membership.canceled	Membership cancelled
subscription.created	New subscription started
subscription.payment_succeeded	Payment processed successfully
subscription.payment_failed	Payment failed
subscription.paid	Invoice paid
subscription.paused	Subscription paused
subscription.resumed	Subscription resumed after pause
subscription.canceled	Subscription cancelled
course.completed	User completed a course
certificate.issued	New certificate issued to user

Official SDKs

Official SDKs are available for the most popular languages. All SDKs are open-source and available on GitHub.

Language	Package	GitHub
Node.js	`npm install elitecircle`	github.com/elitecircle/elitecircle-node
Python	`pip install elitecircle`	github.com/elitecircle/elitecircle-python
Ruby	`gem install elitecircle`	github.com/elitecircle/elitecircle-ruby
Go	`go get github.com/elitecircle/elitecircle-go`	github.com/elitecircle/elitecircle-go
PHP	`composer require elitecircle/elitecircle-php`	github.com/elitecircle/elitecircle-php

💡 SDK Usage The SDKs provide a thin wrapper around the REST API with additional convenience methods like automatic retries, pagination helpers, and webhook verification utilities.

Postman Collection

A curated Postman collection is available with all endpoints pre-configured, including example requests and responses. Import it directly into your workspace.

▶ Import to Postman

OpenAPI Specification

The full OpenAPI 3.0 specification is available for download. Use it to generate clients, write documentation, or integrate with code generation tools.

📄 Download OpenAPI Spec (YAML)