Ferramentas

A hackÜ expõe 22 ferramentas. Todas são somente leitura, exceto uma —request_report— que encomenda um relatório e manda para o seu e-mail.

Não é preciso chamá-las pelo nome: você pergunta ao assistente em linguagem normal e ele escolhe qual usar. Esta página é a referência do que ele pode responder e com quais limites, útil para saber se algo é possível antes de perguntar.

Contexto

`get_company_overview`

Company overview

users:read somente leitura

The company’s headline numbers in one call: people, catalogue, seats, review queue.

Start here for “how are we doing” instead of paging through list_users. One call, a handful of counts.

membership.unlimited_seats true means no seat limit was ever set — the stored limit is a placeholder, so do not quote a seat number.

If segment_restriction is set, the people counts are that staff member’s slice, not the company. Say so rather than presenting them as company totals.

Parâmetros: nenhum.

`get_context`

Identify the connected company

sem permissão (identifica a conexão) somente leitura

Which company this credential reads, as whom, and with what limits.

Call this first, before answering anything about “our company”, “us”, or “the users”. Every other tool is already scoped to a single company but none of them name it, so without this the only honest answer to “what company are we?” is that you do not know — while holding a credential that knows exactly.

It also reports the limits worth stating out loud in an answer:

access.pii_available false means names, emails and phones are withheld by configuration. Rows still come back, identified by id.
access.segment_restriction, when set, means this staff member sees only one slice of the company. Every count and total is of that slice. Say so rather than presenting it as the company’s total.
access.scopes is what this credential may read. A tool that is missing from it will refuse, and that is configuration, not an error to retry.

Costs one small query and needs no arguments.

Parâmetros: nenhum.

Pessoas

`list_users`

List company users

users:read somente leitura

List the people enrolled in your company on hackU, with their current course, module and progress. Supports search and filtering, so prefer narrowing the query over paging through everyone.

Scope: returns only your own company. There is no parameter to read another company’s people — the company is fixed by the credential.

Search: search matches a name, email, phone number or document number, whole or partial. Use it when the question is about a specific person.

Filtering: status is one of not_started, in_progress, completed, no_data. min_progress / max_progress take percentages 0-100. To answer ‘who is falling behind’, filter — do not fetch everyone and sort.

Pagination: returns ONE PAGE, not everyone. When has_more is true there are further users you have not seen; pass next_cursor back as cursor to continue. Never describe one page as the full roster, and never infer a total from the number of rows returned — pass include_total=true if you need the real count.

Missing data: has_progress_data: false (status no_data) means hackU has no calculated progress for that person yet. That is NOT the same as 0% progress — report it as unknown, not as ‘has not started’.

Personal data: names, emails, phone and document numbers appear only when the deployment allows it and the credential carries the users:pii scope. Check pii_included; when it is false you have user ids only, and you should refer to people by id rather than guessing.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	rows per page. The server caps this; asking for more returns the cap.
`cursor`	`str	None`	`None`
`include_total`	`bool`	`False`	also return how many people match. Off by default because counting the whole matching set costs more than reading one page.
`search`	`str	None`	`None`
`status`	`str	None`	`None`
`min_progress`	`float	None`	`None`
`max_progress`	`float	None`	`None`

`get_user`

Get one company user

users:read somente leitura

The full profile of one person in your company — the same picture the hackU corporate dashboard shows across its tabs.

Returns: their course, module, pensum and progress; activity with contents sent, contents viewed and hours used; points with the total and a breakdown by what earned them; certificates issued; pensums enrolled in; engagement with comments, likes and replies; and extra_fields, the company’s own custom fields for that person.

Takes the user_id from a list_users result. If you only have a name, an email or a phone number, call list_users with search first — this tool does not look people up by name.

One person at a time. To compare or rank several, use list_users with filters rather than calling this in a loop.

Counts here are lifetime totals across the person’s whole history, not the current course. activity.contents_viewed can exceed what their active route contains, and that is not an error.

A user id belonging to another company returns 404, the same as one that does not exist. Do not read that as evidence the person exists elsewhere.

Personal data follows the same rule as list_users: check pii_included.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`user_id`	`int`	(obrigatório)	the `user_id` from a `list_users` row.

Cursos

`list_courses`

List courses

courses:read somente leitura

The course catalogue of your company: what is being taught, with how many modules and contents each course has.

This is about the courses themselves, not about who is taking them. For people and their progress use list_users.

Archived courses are excluded unless you pass include_archived=true. A question like ‘what courses do we have’ means the live ones, and counting archived ones silently would inflate every answer.

Courses carry both a name and an alias: the alias is what the company renamed it to for its own people, so prefer it when it is set — that is the name a staff member will recognise.

Paginated the same way as list_users: follow next_cursor, and pass include_total=true rather than counting the rows you got.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	rows per page. The server caps this.
`cursor`	`str	None`	`None`
`search`	`str	None`	`None`
`include_archived`	`bool`	`False`	include courses that were archived. Off by default.
`only_published`	`bool`	`False`	only courses currently published to students.
`include_total`	`bool`	`False`	also return how many courses match.

`get_course`

Get one course

courses:read somente leitura

One course with its modules in the order a student walks them, and optionally the contents inside each module.

Takes the course_id from a list_courses result. If you only have a course name, call list_courses with search first.

include_contents=true also returns every content inside every module, with its type and position. Leave it off when the question is about structure — it is a much larger answer.

position is the order the module or content is delivered in, not an id. Two courses can both have a module at position 1.

A course id from another company returns 404, the same as one that does not exist.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`course_id`	`int`	(obrigatório)	the `course_id` from a `list_courses` row.
`include_contents`	`bool`	`False`	also return the contents inside each module.

Comunicados

`list_communications`

List communications

communications:read somente leitura

The communications (campaigns) your company has prepared or sent, with what they said and when they were scheduled.

campaign_dispatched means the campaign was dispatched. It does NOT mean anyone received it — for that, use list_communication_deliveries on the campaign.

No recipient counts here on purpose: counting the audience of every campaign on a page is expensive, and capping the page does not cap their audiences.

Paginated: follow next_cursor, and pass include_total=true rather than counting the rows you got.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	rows per page; the server caps this.
`cursor`	`str	None`	`None`
`search`	`str	None`	`None`
`only_sent`	`bool`	`False`	only campaigns already dispatched.
`include_total`	`bool`	`False`	also return how many match.

`get_communication`

Get one communication

communications:read somente leitura

One communication in full: both message bodies, its buttons, its template, its channel and when it was scheduled.

Takes the communication_id from a list_communications result. For who received it and what happened to each send, use list_communication_deliveries.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`communication_id`	`int`	(obrigatório)	the `communication_id` from a `list_communications` row.

`list_communication_deliveries`

List deliveries of a communication

communications:read somente leitura

Who a communication went to, and what the messaging provider recorded for each recipient: whatsapp_sent, whatsapp_delivered, whatsapp_read, whatsapp_failed, sms_sent.

READ THIS BEFORE REPORTING ANY OF IT. These flags are evidence, not a state machine, and they are NOT mutually exclusive: the provider raises one without clearing the others, so the same recipient can be both failed and delivered after a retry. Report what is recorded; never collapse them into a single final status.

A false means no evidence of that event was stored. It is NOT proof the event did not happen — a provider that never returns read receipts looks exactly like a message nobody opened. Say ‘no read receipt’ rather than ‘nobody read it’.

send_process_closed is about hackU finishing the send attempt; some errors close it too. It is not delivery.

Filter with status: sent, delivered, read, failed, pending, no_message. Each selects the presence of one piece of evidence, never the absence of another.

Do not compute a delivery rate by subtracting failures from sends. That is the formula the dashboard uses and it does not mean successful delivery.

Personal data follows the usual rule: check pii_included. When present, sent_to_phone and sent_to_email are the addresses the message actually went to, which is what matters when asking why one did not arrive.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`communication_id`	`int`	(obrigatório)	from a `list_communications` row.
`limit`	`int`	`25`	rows per page; the server caps this.
`cursor`	`str	None`	`None`
`status`	`str	None`	`None`
`include_total`	`bool`	`False`	also return how many recipients match the filter.
`include_breakdown`	`bool`	`False`	also return the counts of every bucket for the whole campaign, regardless of `status`.

Avaliações

`list_evaluations`

List evaluations

learning:read somente leitura

Which evaluations this company’s people have actually sat.

Start here before list_evaluation_attempts, which needs an id to narrow by. attempts counts sittings and people counts people: a repeatable evaluation makes those differ, so never read attempts as a headcount. Grades are on a 0-5 scale.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—

`list_evaluation_attempts`

List evaluation attempts

learning:read somente leitura

Individual sittings of an evaluation, narrowed by evaluation or person.

You MUST pass evaluation_id or user_id. One company has a quarter of a million attempts, so there is no “list them all”; get an id from list_evaluations or list_users first.

include_summary=true returns averages over the whole narrowed set in one aggregate — use it instead of paging through attempts to compute an average yourself.

passed is the platform’s verdict and depends on the evaluation’s own pass mark. Somebody can get four of five right and still not pass, so do not recompute it from the question counts.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`evaluation_id`	`int	None`	`None`
`user_id`	`int	None`	`None`
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`only_completed`	`bool`	`False`	—
`passed`	`bool	None`	`None`
`include_total`	`bool`	`False`	—
`include_summary`	`bool`	`False`	—

`get_evaluation_attempt`

Get evaluation attempt

learning:read somente leitura

One sitting, question by question, with which were right.

The answer each person typed comes back only when the connection may show personal data. Question text is course material and always comes back.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`attempt_id`	`int`	(obrigatório)	—

Pesquisas

`list_surveys`

List surveys

learning:read somente leitura

The surveys used by this company’s courses.

A survey is a SHARED object: the same one is attached to the courses of several companies. These are the ones your courses use. Response counts are not here for that reason — ask get_survey_results, which filters to your own people and says so.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`search`	`str	None`	`None`
`only_active`	`bool`	`False`	—
`include_total`	`bool`	`False`	—

`get_survey_results`

Get survey results

learning:read somente leitura

How this company’s people answered one survey, question by question.

Every percentage counts ONLY this company’s responses. The payload also reports responses_all_companies, which is larger because the survey is shared. Report the first number as the company’s result; never quote the second as theirs.

Free-text answers are counted but never returned.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`survey_id`	`int`	(obrigatório)	—

Pensums

`list_pensums`

List pensums

learning:read somente leitura

The company’s programmes: ordered sets of courses people move through.

A pensum is not a course. list_courses is the catalogue; this is how courses are bundled into a path with an expected pace.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`search`	`str	None`	`None`
`only_active`	`bool`	`False`	—
`only_published`	`bool`	`False`	—
`include_total`	`bool`	`False`	—

`get_pensum`

Get pensum

learning:read somente leitura

One programme: its courses in order, and how enrolment is going.

To answer “are they on track?”, compare enrolment.average_progress against enrolment.average_theoretical_progress — the second is what the schedule expected by now. The gap is the answer; neither number alone is.

Before reading a 0% as “has not started”, check pensum.courses: a pensum with no courses keeps its last stored progress rather than being recomputed, so a zero there means nothing is configured.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`pensum_id`	`int`	(obrigatório)	—

`list_pensum_enrolments`

List pensum enrolments

learning:read somente leitura

Who is in one programme and how far along each person is.

Returns ONE PAGE. To answer “how many are behind”, prefer get_pensum’s aggregate over paging through everyone and counting.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`pensum_id`	`int`	(obrigatório)	—
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`only_active`	`bool`	`False`	—
`include_removed`	`bool`	`False`	—
`include_total`	`bool`	`False`	—

Desafios

`list_challenges`

List challenges

learning:read somente leitura

Challenges people handed in, and what is still waiting on a reviewer.

reviewed and approved are NOT the same thing. Reviewed means a person looked at it; approved means they passed it. A reviewed but not approved challenge is a rejection and is finished — counting it as pending overstates the queue.

For “what do I owe my team”, use reviewed=false, or include_summary=true which returns the whole breakdown in one query.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`reviewed`	`bool	None`	`None`
`approved`	`bool	None`	`None`
`include_total`	`bool`	`False`	—
`include_summary`	`bool`	`False`	—

Ranking

`list_ranking`

List ranking

users:read somente leitura

The company’s leaderboard by points, in rank order.

Paged by offset, because a leaderboard is read from the top. Each row carries its own stored position, computed over the whole company, so it stays correct whichever slice you asked for — never renumber rows from their order in the page.

The ranking is produced by a separate job. This reads the stored result, so it is as fresh as that job’s last run, not as of this moment.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—
`offset`	`int`	`0`	—
`include_total`	`bool`	`False`	—

Cargas em massa

`list_bulks`

List bulk uploads

users:read somente leitura

Spreadsheet uploads of people, and whether any got stuck.

The flags are stages, not one status: a file is validated, then processed, then its messages go out.

stuck: true is the one that matters — the file was accepted and never processed, so those people were never enrolled and nobody was told. Use stuck_only=true to answer “did anything fail to load?”.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—
`cursor`	`str	None`	`None`
`stuck_only`	`bool`	`False`	—
`include_total`	`bool`	`False`	—

Relatórios

`list_reports`

List generated reports

reports:generate somente leitura

Spreadsheets this staff member has asked for, and whether they are ready.

download_url needs their own hackU login. It is not public and you cannot fetch it — give them the link, do not try to read the file.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`limit`	`int`	`25`	—

`request_report`

Request a report

reports:generate grava dados

Ask hackU to build a spreadsheet of this company’s data.

THE ONLY TOOL HERE THAT IS NOT A READ. It starts a background job and emails the staff member a download link. Ask them before calling it, and call it once: the job is heavy and takes minutes.

You will not see the contents. That is deliberate — the personal data goes to the person’s own inbox and their own authenticated download, not through this conversation. Do not offer to read the file back.

report_type is one of: users, users_csv, evaluations, evaluations_detail, surveys, ssaa, point_logs, pensum_users, finished_courses.

If it answers that one is already being built, that is not an error and not a reason to retry — tell them to wait for the one in flight.

Parâmetros

Parâmetro	Tipo	Padrão	Descrição
`report_type`	`str`	(obrigatório)	—