Course Catalog Report

Endpoint used to request the generation of the Course Catalog report for an institution. Processing is asynchronous: the API returns immediately after queueing the job; the requester receives the download link via in-app notification or email when the file is ready.

Note: This endpoint is served by Toolzz LXP API (Encore reports-api), not by the institution monolith domain. Use the LXP API base URL (e.g. https://lxp.prod.api.toolzz.media).

Warning: institutionId and userId are taken from the JWT. The report is delivered only to the authenticated user who requested it.

Request Example

curl --request GET \
  --url 'https://lxp.prod.api.toolzz.media/institution/reports/catalog?start_date=2026-01-01&end_date=2026-06-02' \
  --header 'Authorization: Bearer <token>' \
  --header 'Cache-Control: no-cache, no-store, must-revalidate'

Optional school filter:

curl --request GET \
  --url 'https://lxp.prod.api.toolzz.media/institution/reports/catalog?start_date=2026-01-01&end_date=2026-06-02&school_ids=10,20' \
  --header 'Authorization: Bearer <token>'

Response Example

{
  "results": {
    "id": "abc123-def456-ghi789"
  }
}

The results.id field is the Pub/Sub message identifier for the async job (Encore may expose it as messageId depending on version).

---

Request description

Access Token

Parameter	Type	Description	Required
Authorization	String	JWT access token (Bearer <token>). Must include institutionId, userID, and subdomain.	Yes

URL Parameters (Query)

Parameter	Type	Description	Required
start_date	string	Start of the reporting period (ISO date, e.g. 2026-01-01).	Yes
end_date	string	End of the reporting period (ISO date, e.g. 2026-06-02). Must be ≥ start_date.	Yes
school_ids	string	Optional comma-separated school IDs (positive integers). Filters courses linked to those schools.	No

---

Response description

Key	Type	Description
results	object	Async publish result from the report generation topic.
results.id	string	Message ID of the queued report job.

---

Async flow

1. Client calls this endpoint with JWT and date range.
2. Encore runs an analytical query on Redshift and publishes an event to generate-report-catalog-topic.
3. A worker generates the .xlsx, uploads it to object storage, and calls the monolith notification API with typeReport=catalog.
4. The requester receives push and/or email with the public download URL.

Typical processing time depends on institution size (often seconds to a few minutes).

---

Excel columns

Header	Description
ID	Course ID
Título	Course title
URL de Visualização (Aluno)	Student view URL
Status	Publicado or Rascunho
URL de Edição (Admin)	Admin edit URL
Visualizações	View count in the selected period
Matrículas	Enrollments in the period
Conclusões	Completions in the period
Data de Publicação	Publication date (DD/MM/YYYY)
Escola	Aggregated school names

---

Error responses

HTTP	Code	When
400	invalid_argument	Invalid dates, start_date > end_date, invalid school_ids, or invalid JWT claims
401	unauthenticated	Missing or invalid JWT
429	—	Rate limit (60 requests/minute per institution on reports-api)
500	internal	Query or worker failure (check Encore traces)

Example:

{
  "code": "invalid_argument",
  "message": "start_date must be before or equal to end_date",
  "details": null
}

---

Security

• Requires valid JWT (auth: true).
• Data is scoped to the institution from the token.
• Report file URL is sent only to the user who requested it (userId from JWT).
• HTTPS/TLS for all environments.