# Math API endpoint catalog

Base URL: https://math-api.qmindlabs.ai

Every operation below requires a scoped API key. Follow an endpoint link for its complete operation contract and referenced schemas; fetch only the operations you need.

Full OpenAPI 3.1 contract: https://math-api.qmindlabs.ai/api/openapi.json

## Authentication

Check your authenticated identity and scopes.

### GET /api/auth/session

[Inspect your API identity](https://math-api.qmindlabs.ai/docs/api-reference/tag/authentication/GET/api/auth/session.md)

**Required scope:** `read`. **Roles:** Reviewer, Owner, Admin.

Returns the effective member role and API-key scopes. Internal environment names retain dev; this is the main Math deployment.

## Seeds & topics

Find imported topics and their tasks.

### GET /api/math/seeds

[List visible seeds](https://math-api.qmindlabs.ai/docs/api-reference/tag/seeds-topics/GET/api/math/seeds.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Groups imported tasks by source question ID. Counts and search results are restricted to your visible tasks.

### GET /api/math/seeds/{question_id}

[Get a seed summary](https://math-api.qmindlabs.ai/docs/api-reference/tag/seeds-topics/GET/api/math/seeds/{question_id}.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.



### GET /api/math/seeds/{question_id}/tasks

[List tasks for a seed](https://math-api.qmindlabs.ai/docs/api-reference/tag/seeds-topics/GET/api/math/seeds/{question_id}/tasks.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

The path fixes the question ID. All other task filters apply. Includes archived tasks by default.

### GET /api/math/topics

[List latest imported run per topic](https://math-api.qmindlabs.ai/docs/api-reference/tag/seeds-topics/GET/api/math/topics.md)

**Required scope:** `read`. **Roles:** Owner, Admin.

Whole-run research is restricted to operators. q searches topic titles, IDs, run IDs and problem text. Reviewers should use /api/math/seeds.

## Tasks & review

Read, assign and review tasks with version checks.

### GET /api/math/tasks

[List tasks](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/GET/api/math/tasks.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Includes archived tasks by default. Counts describe the filtered result, not just the current page. Reviewers see only tasks currently assigned to them.

### GET /api/math/tasks/{task_id}

[Get task research details](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/GET/api/math/tasks/{task_id}.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Returns the imported problem, report mapping and a compact workflow summary. Use the /workflow endpoint for version, assignment and history.

### POST /api/math/tasks/{task_id}

[Apply a workflow action](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/POST/api/math/tasks/{task_id}.md)

**Required scope:** `write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Read the current version first. Each success increments it and returns the updated task/history. Reviewers may start, add feedback or submit a verdict on assigned tasks. Other actions require Owner/Admin. feedback, verdict and reopen require a nonblank comment. Assign/client accept null to clear the assignment. Restore an archived task before other changes. Reopen a completed review before reassignment or another verdict. Feedback moves ASSIGNED tasks to IN_REVIEW. A stale version returns 409; reread before retrying. Examples use synthetic IDs and versions.

### GET /api/math/tasks/{task_id}/workflow

[Get task workflow and history](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/GET/api/math/tasks/{task_id}/workflow.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Returns the current version, assignment, decision, allowed reviewer/client choices, and latest 200 events.

### GET /api/math/tasks/{task_id}/notes

[List task notes](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/GET/api/math/tasks/{task_id}/notes.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Nonempty comments from workflow events, newest version first. No total is returned; a short page marks the end.

### POST /api/math/tasks/{task_id}/notes

[Add a task note](https://math-api.qmindlabs.ai/docs/api-reference/tag/tasks-review/POST/api/math/tasks/{task_id}/notes.md)

**Required scope:** `write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Uses the feedback workflow action and increments the version. Can move an ASSIGNED task to IN_REVIEW. Returns full workflow detail rather than a standalone note.

## Research & reports

Read reports, verified evidence and storage locations.

### GET /api/math/runs

[List imported runs](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/runs.md)

**Required scope:** `read`. **Roles:** Owner, Admin.

All matching imported runs, newest first. These are completed import records, not live scheduler jobs.

### GET /api/math/runs/{run_id}

[Get an imported run](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/runs/{run_id}.md)

**Required scope:** `read`. **Roles:** Owner, Admin.

Run details, associated tasks, reports and aggregate review status.

### GET /api/math/reports

[List task report mappings](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/reports.md)

**Required scope:** `read`. **Roles:** Owner, Admin.

Includes tasks with a null report mapping. mapped_reports counts mappings; it is not a count of unique file objects.

### GET /api/math/workflow/tasks/{task_id}/evidence

[Get verified task evidence](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/workflow/tasks/{task_id}/evidence.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Returns a JSON projection of the permitted task’s rubric, review and quality gate. Source-defined evidence fields vary by report and may be null. Private sibling-task data and raw provenance files are not exposed.

### GET /api/math/tasks/{task_id}/paths

[Get task report storage locations](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/tasks/{task_id}/paths.md)

**Required scope:** `paths:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Private source/imported identifiers for the task’s current primary report. Reviewers must be assigned to every task sharing the report. Use download_url for authenticated file retrieval.

### GET /api/math/runs/{run_id}/paths

[Get run storage locations](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/runs/{run_id}/paths.md)

**Required scope:** `paths:read`. **Roles:** Owner, Admin.

Excludes PRIVATE and PROVENANCE artifacts. Returns 404 when no permitted paths exist.

### GET /api/math/artifacts/{artifact_id}/download

[Download a verified report or artifact](https://math-api.qmindlabs.ai/docs/api-reference/tag/research-reports/GET/api/math/artifacts/{artifact_id}/download.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

The service verifies size and SHA-256 before returning bytes. Reports are Markdown, checkpoints gzip, and public inputs/tasks JSON. Reviewers may download only their current mapped primary reports, including checks for all shared mappings. PRIVATE and PROVENANCE objects cannot be downloaded here.

## Attachments

Upload and download supplementary task files.

### GET /api/math/tasks/{task_id}/attachments

[List task attachments](https://math-api.qmindlabs.ai/docs/api-reference/tag/attachments/GET/api/math/tasks/{task_id}/attachments.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Up to 200 active attachments, newest first. Removed attachments are excluded.

### POST /api/math/tasks/{task_id}/attachments

[Upload a task attachment](https://math-api.qmindlabs.ai/docs/api-reference/tag/attachments/POST/api/math/tasks/{task_id}/attachments.md)

**Required scope:** `files:write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Send raw file bytes with Content-Type application/octet-stream. Minimum 1 byte, maximum 16 MiB; 200 active files per task. Archived tasks are read-only. Uploads are supplementary files and do not replace imported reports.

### GET /api/math/tasks/{task_id}/attachments/{attachment_id}

[Get attachment metadata](https://math-api.qmindlabs.ai/docs/api-reference/tag/attachments/GET/api/math/tasks/{task_id}/attachments/{attachment_id}.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.



### DELETE /api/math/tasks/{task_id}/attachments/{attachment_id}

[Remove an attachment](https://math-api.qmindlabs.ai/docs/api-reference/tag/attachments/DELETE/api/math/tasks/{task_id}/attachments/{attachment_id}.md)

**Required scope:** `files:write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Reviewers can remove only their own uploads while still assigned. Owner/Admin can remove any permitted attachment. Archived tasks must be restored first. Removal hides the file and retains its bytes for audit/recovery.

### GET /api/math/tasks/{task_id}/attachments/{attachment_id}/download

[Download an attachment](https://math-api.qmindlabs.ai/docs/api-reference/tag/attachments/GET/api/math/tasks/{task_id}/attachments/{attachment_id}/download.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Returns the file only after verifying its receipt and rechecking task access.

## Monitoring

Inspect imported data, activity and review analytics.

### GET /api/math/monitor

[Get import and review status](https://math-api.qmindlabs.ai/docs/api-reference/tag/monitoring/GET/api/math/monitor.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Assignment-scoped counts and freshness timestamps for imported dashboard data. Does not include unimported seeds, active AWS/Vast scheduler jobs, or job start/stop control.

### GET /api/math/activity

[List workflow activity](https://math-api.qmindlabs.ai/docs/api-reference/tag/monitoring/GET/api/math/activity.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Visible task/client audit events, newest first. Counts and results are scoped by assignment for reviewers.

### GET /api/math/analytics

[Get review analytics](https://math-api.qmindlabs.ai/docs/api-reference/tag/monitoring/GET/api/math/analytics.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Review state, decisions, workload, trend and recent activity. Model pass rates are not available.

## Clients & members

Organize clients and inspect permitted members.

### GET /api/math/clients

[List clients and task counts](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/GET/api/math/clients.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Reviewers see only clients linked to their assigned tasks. Includes enabled/disabled status and updated_at for conflict-safe edits.

### POST /api/math/clients

[Create a client](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/POST/api/math/clients.md)

**Required scope:** `write`. **Roles:** Owner, Admin.

Names are trimmed, 2–100 characters and case-insensitively unique. Duplicate names return 409. Read the client list afterward to obtain updated_at for future edits.

### POST /api/math/clients/{client_id}

[Update a client](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/POST/api/math/clients/{client_id}.md)

**Required scope:** `write`. **Roles:** Owner, Admin.

All four fields are required. Supply the exact current updated_at; stale values return 409. The new timestamp is returned.

### GET /api/reviewers

[List reviewer choices](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/GET/api/reviewers.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Reviewers see their own member record. Operators see member choices excluding the primary admin. Check enabled before assignment.

### GET /api/users

[List Math members](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/GET/api/users.md)

**Required scope:** `read`. **Roles:** Admin.

Read-only local member projections. Account creation and membership changes belong to the central identity service.

### GET /api/auth/audit

[Read identity audit events](https://math-api.qmindlabs.ai/docs/api-reference/tag/clients-members/GET/api/auth/audit.md)

**Required scope:** `read`. **Roles:** Admin.

Latest 100 local identity audit records. detail is event-specific JSON.

## API keys

Issue, inspect and revoke scoped keys.

### GET /api/keys

[List API keys](https://math-api.qmindlabs.ai/docs/api-reference/tag/api-keys/GET/api/keys.md)

**Required scope:** `keys:manage`. **Roles:** Reviewer, Owner, Admin.

Up to 500 keys, newest first, including expired/revoked metadata. Non-admins see only their keys; Admin sees workspace keys. Secrets and hashes are never returned.

### POST /api/keys

[Create an API key](https://math-api.qmindlabs.ai/docs/api-reference/tag/api-keys/POST/api/keys.md)

**Required scope:** `keys:manage`. **Roles:** Reviewer, Owner, Admin.

Returns the secret once. Save it privately. Non-admins issue only for themselves; Admin may specify an enabled Math member. Role and scopes cannot exceed the issuer or target member. Default expiry 90 days, maximum 365; 50 active keys per member. Defaults inherit issuer role/scopes.

### GET /api/keys/{key_id}

[Get key metadata](https://math-api.qmindlabs.ai/docs/api-reference/tag/api-keys/GET/api/keys/{key_id}.md)

**Required scope:** `keys:manage`. **Roles:** Reviewer, Owner, Admin.

Own key only unless Admin. The secret cannot be retrieved.

### DELETE /api/keys/{key_id}

[Revoke an API key](https://math-api.qmindlabs.ai/docs/api-reference/tag/api-keys/DELETE/api/keys/{key_id}.md)

**Required scope:** `keys:manage`. **Roles:** Reviewer, Owner, Admin.

Own key only unless Admin. Revocation takes effect across both API processes. Repeated revocation preserves the original revoked_at. Revoking your current key prevents subsequent requests.

### GET /api/keys/{key_id}/events

[List key audit events](https://math-api.qmindlabs.ai/docs/api-reference/tag/api-keys/GET/api/keys/{key_id}/events.md)

**Required scope:** `keys:manage`. **Roles:** Reviewer, Owner, Admin.

Latest 100 creation, revocation and write-request events. Own key only unless Admin; an unavailable key produces an empty list. Read requests are reflected by last_used_at rather than individual events.

## Bug reports

Submit issues and optional screenshots.

### GET /api/bug-reports

[List bug reports](https://math-api.qmindlabs.ai/docs/api-reference/tag/bug-reports/GET/api/bug-reports.md)

**Required scope:** `read`. **Roles:** Reviewer, Owner, Admin.

Latest 50 reports. Reviewer/Owner see their own submissions; Admin sees all.

### POST /api/bug-reports

[Submit a bug report](https://math-api.qmindlabs.ai/docs/api-reference/tag/bug-reports/POST/api/bug-reports.md)

**Required scope:** `write + files:write`. **Roles:** Reviewer, Owner, Admin.

Multipart form with a description and optional screenshot. Both scopes are required even without a screenshot. picture accepts PNG/JPEG/WebP up to 8 MiB. page_path should be a relative path beginning with /. The response is a creation receipt; list reports to obtain the screenshot URL.

### GET /api/bug-reports/{report_id}/screenshot

[Download a bug screenshot](https://math-api.qmindlabs.ai/docs/api-reference/tag/bug-reports/GET/api/bug-reports/{report_id}/screenshot.md)

**Required scope:** `files:read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Only the report’s submitter or an Admin can retrieve the verified image.

## Dashboard compatibility

Alternate routes retained for dashboard clients.

### POST /api/math/tasks/{task_id}/workflow

[Apply a workflow action through the detail route](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/POST/api/math/tasks/{task_id}/workflow.md)

**Required scope:** `write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Alias of POST /api/math/tasks/{task_id}. Read the current version first. Each success increments it and returns the updated task/history. Reviewers may start, add feedback or submit a verdict on assigned tasks. Other actions require Owner/Admin. feedback, verdict and reopen require a nonblank comment. Assign/client accept null to clear the assignment. Restore an archived task before other changes. Reopen a completed review before reassignment or another verdict. Feedback moves ASSIGNED tasks to IN_REVIEW. A stale version returns 409; reread before retrying. Examples use synthetic IDs and versions.

### GET /api/math/workflow

[List dashboard workflow tasks](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/GET/api/math/workflow.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Same response and filters as /api/math/tasks, but defaults to the evaluations surface (archived tasks excluded).

### GET /api/math/workflow/tasks/{task_id}

[Get dashboard task workflow](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/GET/api/math/workflow/tasks/{task_id}.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.



### POST /api/math/workflow/tasks/{task_id}

[Apply a dashboard workflow action](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/POST/api/math/workflow/tasks/{task_id}.md)

**Required scope:** `write`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Read the current version first. Each success increments it and returns the updated task/history. Reviewers may start, add feedback or submit a verdict on assigned tasks. Other actions require Owner/Admin. feedback, verdict and reopen require a nonblank comment. Assign/client accept null to clear the assignment. Restore an archived task before other changes. Reopen a completed review before reassignment or another verdict. Feedback moves ASSIGNED tasks to IN_REVIEW. A stale version returns 409; reread before retrying. Examples use synthetic IDs and versions.

### GET /api/clients

[List shared client summaries](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/GET/api/clients.md)

**Required scope:** `read`. **Roles:** Reviewer (assigned tasks), Owner, Admin.

Dashboard-compatible client summary. Use /api/math/clients for descriptions and archived counts.

### GET /api/auth/viewable-users

[Inspect dashboard view capability](https://math-api.qmindlabs.ai/docs/api-reference/tag/dashboard-compatibility/GET/api/auth/viewable-users.md)

**Required scope:** `read`. **Roles:** Admin.

With API-key authentication this returns an empty users list. Keys cannot switch roles or view another identity; issue a separately scoped key instead.