EduAlign API Integration Guide
Guide for integrating EduTAP data into external systems via the EduAlign API
Getting Started
The EduAlign API (Ops API) is a backend REST API that lets partners query EduTAP data from their own systems. Use it to load learner sessions, messages, and usage counts into your BI tools or data lake.
Available APIs
| Domain | API | Description |
|---|---|---|
| Auth | POST /ops/v1/auth/signin | Sign in and issue tokens |
| Auth | POST /ops/v1/auth/refresh | Refresh tokens (rotation) |
| Session | GET /ops/v1/sessions | Session list (paginated) |
| Session | GET /ops/v1/sessions/{session_id}/messages | Session messages (paginated) |
| Session | GET /ops/v1/sessions/dumps | Bulk session dump for a date range |
| Session | GET /ops/v1/sessions/dumps/since-last | Incremental session dump since the last call |
| Session | GET /ops/v1/sessions/messages/dumps | Bulk message dump for a date range |
| Session | GET /ops/v1/sessions/messages/dumps/since-last | Incremental message dump since the last call |
| Dashboard | GET /ops/v1/dashboard/user-count | User count for a date range |
| Dashboard | GET /ops/v1/dashboard/message-count | Message count for a date range |
| Users | GET /ops/v1/users | Per-learner activity summary |
| Client | GET /ops/v1/clients/children | Child client list |
The base URL is https://opsapi.edutap.ai. See Common for shared conventions such as pagination and date formats.
Authentication
Every API except sign-in and token refresh requires the Authorization: Bearer {access_token} header.
- Only client member accounts can sign in.
- Token refresh uses rotation. Refreshing invalidates both the previous access token and refresh token, so store the new token pair from the response.
- If a refresh returns 401
InvalidRefreshToken, automatic refresh is no longer possible. Sign in again.
Use the access_token from the signin response as-is. Appending suffixes such as | to the token string results in a 401.
Querying Child Client Data
If your client has child clients, every query API accepts the client_identity and include_descendants parameters to set the query scope.
| Request | Scope |
|---|---|
| (no parameters) | Signed-in client only |
| include_descendants=true | Signed-in client + all child clients |
| client_identity=acme_kr | acme_kr only |
| client_identity=acme_kr&include_descendants=true | acme_kr + all of acme_kr's child clients |
- Use List Child Clients to find the
client_identityvalues you can specify. - Pass
client_identityandinclude_descendantsto the query API. - When querying multiple clients, use each item's
client_identityto tell which client it belongs to. Count APIs return the sum.
Specifying a client_identity that is not under the signed-in client or does not exist returns 403 OuterClientScopeForbidden. The last-call timestamp for incremental dumps is tracked separately for each client_identity and include_descendants combination.
Integration Scenarios
Daily usage sync
- Get tokens with Sign in.
- Query User Count and Message Count with
start_dateandend_date. - Load the results into your BI system.
Loading session and message data
- For the initial load or reprocessing, fetch a date range with Session Dump and Message Dump.
- After that, fetch only new data since the last call with Incremental Session Dump and Incremental Message Dump.
- If ingestion fails, request the same window again with
retry=true.
Learner activity summary
- Use User Activity List to get each learner's session count, question count, and last question time.
- Search for a specific learner with a partial match on
user_id. - Specify both
start_dateandend_dateto count only activity within that period.