Development
API Reference
Overview of the Envision Portal REST API.
Envision Portal exposes a REST API under /api/. Interactive API documentation is available via Scalar at /api-docs when the server is running.
All API routes use JSON for request and response bodies. Protected routes require an active session cookie obtained by logging in via POST /api/auth/login.
The API surface supports current platform workflows and is expected to expand as discovery, automation, and AI-assist capabilities mature.
Authentication
| Method | Path | Description |
|---|---|---|
| POST | /api/auth/signup | Register a new user (requires a valid platform invitation) |
| POST | /api/auth/login | Log in and create a session |
| POST | /api/auth/verify-email | Verify a user's email address with a token |
Datasets
| Method | Path | Description |
|---|---|---|
| GET | /api/datasets | List datasets accessible to the current user |
| POST | /api/datasets | Create a new dataset |
| GET | /api/datasets/[datasetId] | Get dataset details |
| POST | /api/datasets/[datasetId]/new-version | Create a new version of a dataset |
Dataset Metadata
Each metadata section supports GET and PUT:
| Path | Section |
|---|---|
/api/datasets/[datasetId]/metadata/general-information | General information |
/api/datasets/[datasetId]/metadata/about | About |
/api/datasets/[datasetId]/metadata/identifiers | Identifiers |
/api/datasets/[datasetId]/metadata/related-identifiers | Related identifiers |
/api/datasets/[datasetId]/metadata/access-rights | Access rights |
/api/datasets/[datasetId]/metadata/data-management | Data management |
/api/datasets/[datasetId]/metadata/team | Team / contributors |
Study Metadata
Each study metadata section supports GET and PUT:
| Path | Section |
|---|---|
/api/datasets/[datasetId]/study/metadata/about | Study summary |
/api/datasets/[datasetId]/study/metadata/design | Study design |
/api/datasets/[datasetId]/study/metadata/status | Study status |
/api/datasets/[datasetId]/study/metadata/arms | Study arms |
/api/datasets/[datasetId]/study/metadata/interventions | Interventions |
/api/datasets/[datasetId]/study/metadata/eligibility | Eligibility criteria |
/api/datasets/[datasetId]/study/metadata/contacts | Contacts |
/api/datasets/[datasetId]/study/metadata/officials | Officials |
/api/datasets/[datasetId]/study/metadata/locations | Locations |
/api/datasets/[datasetId]/study/metadata/team | Study team |
Healthsheet
Each healthsheet section supports GET and PUT:
| Path | Section |
|---|---|
/api/datasets/[datasetId]/healthsheet/motivation | Motivation |
/api/datasets/[datasetId]/healthsheet/composition | Composition |
/api/datasets/[datasetId]/healthsheet/collection | Collection |
/api/datasets/[datasetId]/healthsheet/preprocessing | Preprocessing |
/api/datasets/[datasetId]/healthsheet/distribution | Distribution |
/api/datasets/[datasetId]/healthsheet/uses | Uses |
/api/datasets/[datasetId]/healthsheet/maintenance | Maintenance |
Files
| Method | Path | Description |
|---|---|---|
| GET | /api/datasets/[datasetId]/files | List files in a dataset |
| GET | /api/datasets/[datasetId]/upload | Get upload configuration |
Publishing
| Method | Path | Description |
|---|---|---|
| GET | /api/datasets/[datasetId]/publish | Get publishing status |
| GET | /api/datasets/[datasetId]/publish/dataset-metadata | Get metadata for review |
| GET | /api/datasets/[datasetId]/publish/study-metadata | Get study metadata for review |
| GET | /api/datasets/[datasetId]/publish/readme | Get README for review |
| GET | /api/datasets/[datasetId]/publish/changelog | Get changelog for review |
| POST | /api/datasets/[datasetId]/publish/finalize | Finalize and publish |
Access Requests
| Method | Path | Description |
|---|---|---|
| GET | /api/datasets/[datasetId]/requests | List requests for a dataset |
| GET | /api/datasets/[datasetId]/requests/[requestId] | Get a specific request |
| GET | /api/requests | List all requests for the current user |
| GET | /api/requests/[requestId] | Get a specific user request |
Discover (Public)
| Method | Path | Description |
|---|---|---|
| GET | /api/discover/dataset | List public datasets |
| POST | /api/discover/dataset/external | Register an external dataset |
| GET | /api/discover/dataset/[datasetid] | Get a public dataset |
| GET | /api/discover/dataset/[datasetid]/datasetIndex | Get the dataset file index |
| POST | /api/discover/dataset/[datasetid]/access/public | Submit a public access request |
| GET | /api/discover/dataset/[datasetid]/access/public/[requestid] | Check public request status |
| POST | /api/discover/dataset/[datasetid]/access/request-controlled | Submit a controlled access request |
As the platform evolves, discovery APIs are expected to support richer filtering and indexing metadata for ophthalmic modalities, disease focus, and interoperability signals.
Notifications
| Method | Path | Description |
|---|---|---|
| GET | /api/notifications | List notifications for the current user |
| POST | /api/notifications/[notificationId] | Mark a notification as read |
| DELETE | /api/notifications/[notificationId] | Delete a notification |
Contact
| Method | Path | Description |
|---|---|---|
| POST | /api/contact | Submit a contact form message |