Grow LMS API Documentation

Grow by Plenum — Operational Reference

The production-readiness details: rate handling, errors, async operations, and reliability.

This is the reference your engineers reach for when hardening an integration for production — how to handle errors, pace requests, deal with long-running operations, and build a delivery pipeline that doesn’t lose data. It complements the capability docs with the operational fine print.

All requests use the Pl-Client header and Authorization: Bearer <ACCESS_TOKEN> from Authentication & Access Setup. <SCHOOL_ID> is your environment.

1. Rate limits and throughput

Stated honestly: a hard published rate ceiling is not documented. Rather than quote a number we can’t stand behind, here’s what we actually know from running this in production:

  • Plenum’s own extraction and sync workloads have sustained roughly three requests per second against live environments without encountering throttling.
  • We have not hit a rate wall in normal integration use at the scale our workloads run.

Design guidance: build a well-behaved client regardless — modest concurrency, exponential backoff on errors, and a pause-and-retry rather than hammer-and-fail posture. If your use case involves unusually high-volume polling or a very large one-time backfill, tell us during integration design and we’ll size and test it with you, rather than have you discover a limit in production.

2. Error handling

Every response carries an explicit success boolean, so your client branches on it directly instead of inferring outcome from HTTP status alone. On failure, success is false and an errors array describes what happened:

{
  "errors": [
    {
      "code": 400,
      "context": "access_denied",
      "message": "The resource owner or authorization server denied the request."
    }
  ],
  "success": false
}

Each error carries a code, a context (a short machine-readable reason such as access_denied), and a human-readable message.

Recommended handling:

  • Branch on success first; treat success: false as a failure even if the transport looked fine.
  • On access_denied, re-mint your access token (see Authentication) and retry once. If it fails again, surface the error rather than looping.
  • On transient/5xx-class failures, back off and retry with increasing delay; cap the attempts.
  • Log context and message so operational issues are diagnosable without guesswork.

3. Pagination

Collection endpoints are paginated; responses include a meta block (page, totalItems, totalPages, itemsPerPage). Page from 1 until page reaches totalPages, and read totalPages from the response rather than assuming a fixed count. Full detail and an example are in Pull-Based Data Access.

4. Asynchronous operations

Some operations — particularly bulk actions — don’t complete inline. Instead of holding the connection open, the API returns an asynchronous-action handle, and you poll a status endpoint until the action reports complete.

Pattern:

  1. Submit the operation; receive an async handle.
  2. Poll the action’s status on a sensible interval (seconds, not milliseconds).
  3. Proceed when it reports done; handle a failure status the same way you’d handle any error.

Design batch jobs around submit-then-check, so a large enrollment or update run doesn’t depend on every call finishing synchronously.

5. Webhook delivery reliability

For the real-time path (see Webhooks), build the receiver for the realities of networked delivery:

  • Acknowledge fast. Return a 2xx as soon as you’ve verified the signature and durably queued the payload; do downstream work asynchronously.
  • Be idempotent. A delivery can arrive more than once (e.g. after a transient failure on your side). Process by event identity so a duplicate is a no-op, not a double-count.
  • Verify every payload. Reject anything whose Pl-Webhook-Signature doesn’t validate.
  • Reconcile. Webhooks are the real-time path, not the system of record. Pair them with periodic event-log replay (see Pull-Based Data Access) so any delivery missed during downtime is recovered. Push keeps you current; the event log guarantees completeness.

6. Versioning and change management

  • Payloads are versioned. Webhook payloads carry a version field — branch on it so a future format change can’t silently break your parser.
  • Changes are communicated. Material changes to the integration surface for your environment are communicated by Plenum ahead of time through your engagement lead, so you can adapt on a known timeline rather than reactively.

7. Support and escalation

  • Integration design and issues route through your Plenum engagement lead — Plenum operates the environment, so support is a single channel rather than a vendor-handoff chain.
  • Environment specifics (exact endpoint paths, credentials, webhook secret, any per-environment limits) are confirmed during onboarding and documented for your team.
  • Bring your questionnaire. For a formal technical or security review, send your actual questionnaire and we’ll answer it directly rather than pointing you at generic docs.

8. Where to go next

  • Authentication & Access Setup — token lifecycle and the re-mint flow referenced in Section 2.
  • Pull-Based Data Access — pagination and the event-log reconciliation pattern.
  • Webhooks — the delivery model behind Section 5.

Prepared by Plenum Solutions for your evaluation. “Grow by Plenum” is operated and supported by Plenum on your behalf. Operational specifics are confirmed for your environment during onboarding. For integration design support, contact your Plenum engagement lead.