# REST API

Institution administrators can connect HealthTasks to other systems with the REST API—for example a student information system, CRM, hospital partner portal, or custom integration.

## Overview

The REST API is a server-to-server interface for your institution’s data. You create API keys in **Settings → REST API**, then call the production base URL from your own backend or integration platform.

Full reference docs (endpoints, schemas, and examples) live at:

**https://healthtasks.apidocumentation.com**

## Before you start

- You must be an institution administrator.
- Keys should stay in a secrets manager or secure server environment—never in public repos, browser apps, or hosted “try it” tools.
- Prefer one key per integration so you can revoke access without affecting other systems.

## Set up a key

1. Open **Settings** and select the **REST API** tab.
2. Open the public docs link if you need endpoint details, and copy your institution’s API base URL.
3. Create an API key. Give it a clear label (for example “Hospital partner – North Campus”).
4. Optionally limit the key to specific clinical sites (site-scoped). Leave sites empty for institution-wide access.
5. Copy the secret when it is shown. It is displayed only once.

Authenticate requests with either:

- `Authorization: Bearer ht_…`
- or `x-healthtasks-api-key: ht_…`

## What you can access

Institution-wide keys can read curated resources such as:

- People and sites (students, preceptors, classrooms, locations)
- Clinical schedules and assignments
- Clinical logs
- Evaluations and skills checkoffs
- Clinical-site partner resources (placements, compliance status summaries, site evaluation insights)

Keys include **read** access by default. **Write** access is limited to creating, updating, and archiving **location units** under existing clinical locations (for example capacity updates from a partner scheduling system).

Site-scoped keys only see the clinical sites you selected, and only the partner-oriented resources for those sites (locations, placements, compliance status, site evaluation insights, and unit writes).

## Common uses

**School integrations**  
Sync rosters, placements, or clinical activity into your SIS, data warehouse, or reporting tools.

**Clinical site partners**  
Share a site-scoped key so a hospital can pull who is coming, check clearance summaries, and push unit capacity—without institution-wide access. Optionally add a webhook endpoint so partners get push notifications instead of tight polling.

**Operational automation**  
Run scheduled jobs on your servers that call HealthTasks and update downstream systems.

## Webhooks

Under **Settings → REST API**, add an HTTPS webhook endpoint to receive signed POSTs when placements, schedule segments, clearance, or location units change. Copy the signing secret when it is shown (once).

- Prefer webhooks to reduce polling, but still reconcile with `updated_since` on a schedule.
- Site-scoped endpoints only receive events for the selected clinical sites.
- Use **Send test ping** to verify your receiver and signature check.
- Endpoints disable automatically after many consecutive delivery failures; re-enable after fixing your receiver.

## Managing keys

- **Edit** a key’s label or site scope without rotating the secret.
- **Revoke** a key immediately when an integration ends or a secret may have leaked. Create a new key to reconnect.
- Monitor **last used** timestamps on the REST API tab to spot unused or unexpected keys.

## Managing webhooks

- **Edit** URL, events, or site scope without rotating the signing secret.
- **Rotate secret** when staff change or a secret may have leaked.
- Review **recent deliveries** for HTTP status and errors.

## Security tips

1. Store secrets server-side only; do not paste keys into browser-based API explorers or third-party docs pages.
2. Use site-scoped keys whenever you share access with an external clinical partner.
3. Rotate (revoke + recreate) keys on a regular schedule or after staff changes.
4. Treat student and clinical data according to your institution’s agreements and policies—you remain responsible for how shared keys are used.

## Troubleshooting

**Cannot see the REST API tab**  
Confirm you are signed in as an institution administrator.

**401 / unauthorized**  
Check that the secret is complete and that the key has not been revoked. Send the key in one of the supported headers.

**403 / forbidden**  
The key may be site-scoped and you requested a resource or location outside that scope. Use an institution-wide key or expand the site list.

**Rate limited (429)**  
Slow down requests and honor `Retry-After`. Heavy sync jobs should use incremental filters when available (see the public API docs).

**Need endpoint details**  
Use the hosted reference at https://healthtasks.apidocumentation.com rather than this help article.

## Related features

- **Settings**: REST API keys, notifications, MFA, and LMS connections
- **Placements**: Clinical sites and units (Locations tab) that partners may update via the API
- **Billing**: Subscription and seat management (separate from API access)

## Support

For integration questions or account access issues: support@healthtasks.ai