canonical: https://jentic.com/apis/cognisantmd.com/cognisantmd-ocean

# Cognisantmd Ocean Health Platform API

Jentic publishes the only available OpenAPI specification for Ocean Health Platform API, keeping it validated and agent-ready. Ocean by CognisantMD is a Canadian eReferral, eConsult, and patient engagement platform widely used by primary care, specialist clinics, and regional health authorities to coordinate care between providers. The API exposes 6 endpoints over ocean.cognisantmd.com/svc - a small FHIR R4 surface for Patient and ServiceRequest plus a `/api/v1/sites` lookup for clinic locations. Authentication is OAuth 2.0 client credentials, and the endpoints are designed for partner EMRs, intake portals, and triage tools that need to read patient context and create or look up referrals.

## For AI agents

Search and read Ocean patients, create and look up FHIR ServiceRequest referrals, and list clinic sites using OAuth 2.0 client credentials.

## Scope

Does not handle lab results, prescriptions, billing, or patient messaging - use for Ocean patient lookup, FHIR ServiceRequest referrals, and site directory only.

## Capabilities

- Authenticate with OAuth 2.0 client credentials at `/svc/oauth2/token` to receive a Bearer access token
- Search the Ocean patient registry via GET `/fhir/v1/Patient` using FHIR search parameters
- Retrieve a single patient's FHIR record with GET `/fhir/v1/Patient/{patientId}`
- Create an electronic referral as a FHIR ServiceRequest via POST `/fhir/v1/ServiceRequest`
- Search and retrieve existing referrals through GET `/fhir/v1/ServiceRequest` and `/fhir/v1/ServiceRequest/{referralId}`
- List Ocean clinic sites available to the authenticated client via GET `/api/v1/sites`

## Use cases

### EMR-to-Specialist eReferral Workflow

Primary care EMRs use Ocean to dispatch electronic referrals to specialist clinics across a region. The agent collects intake data inside the EMR, calls POST `/fhir/v1/ServiceRequest` with a FHIR ServiceRequest payload, and stores the returned id for status tracking. Replaces fax-based or PDF-attachment referrals with structured, auditable, FHIR-shaped data.

Example prompt: Build a FHIR ServiceRequest with patient reference, requester, performer, and category, then POST it to `/fhir/v1/ServiceRequest` and return the new referral id

### Patient Lookup for Triage

Triage and intake tools resolve a patient against the Ocean registry before opening a chart or sending a referral. The agent calls GET `/fhir/v1/Patient` with FHIR search parameters (family, given, birthdate, identifier) and disambiguates among the matches. Saves the clinician from re-entering demographics for patients already known to Ocean.

Example prompt: Call GET `/fhir/v1/Patient`?family=Smith&given=Alice&birthdate=1980-03-12 and return matches with patient id and identifiers

### Referral Status Monitoring

Care coordinators monitor outstanding referrals to make sure none stall in transit. The agent loops over GET `/fhir/v1/ServiceRequest` filtered by status and creation date, surfaces any referral older than a defined SLA, and posts a triage list to a coordinator's queue. Catches lost referrals before patients fall through the gaps.

Example prompt: Call GET `/fhir/v1/ServiceRequest`?status=active&_lastUpdated=lt-7d and return any referrals older than 7 days that are still active

### Multi-Site Clinic Directory

Health authorities publish lists of Ocean-enabled clinic sites so referring providers know who is reachable. The agent calls GET `/api/v1/sites` and renders an internal directory with clinic name, location, and supported referral types. Keeps the directory in sync with what Ocean actually advertises rather than a manually maintained spreadsheet.

Example prompt: Call GET `/api/v1/sites` and render the response as a CSV with site id, name, and address fields for the internal directory

### Agent-Driven Ocean Workflows via Jentic

An AI agent connected to Jentic can run a complete Ocean intake flow - search the patient, create a ServiceRequest, monitor status - without ever holding the OAuth client secret. Jentic stores the client credentials in its vault, mints access tokens on demand, and exposes the operations through intent search so the agent can search, load, and execute in seconds.

Example prompt: Search Jentic for 'create Ocean referral', execute POST `/fhir/v1/ServiceRequest` with the assembled FHIR payload, and return the new referral id and status

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/fhir/v1/Patient` | Search patients in the Ocean registry |
| GET | `/fhir/v1/Patient/{patientId}` | Get a patient's FHIR record |
| POST | `/fhir/v1/ServiceRequest` | Create a referral as a FHIR ServiceRequest |
| GET | `/fhir/v1/ServiceRequest` | Search referrals |
| GET | `/fhir/v1/ServiceRequest/{referralId}` | Get a referral's FHIR record |
| GET | `/api/v1/sites` | List Ocean clinic sites |

## Key resources

- **Patient** — Search and retrieve FHIR R4 Patient resources from the Ocean registry
- **ServiceRequest** — Create, search, and retrieve FHIR ServiceRequest resources representing eReferrals
- **Sites** — List Ocean-enabled clinic sites available to the authenticated client

## Why Jentic

- **Setup:** Wiring the Ocean Health Platform API by hand means running the OAuth 2.0 client-credentials flow against `/svc/oauth2/token`, minting short-lived access tokens, targeting ocean.cognisantmd.com/svc, and refreshing them yourself. Through Jentic you install once, import the Ocean Health Platform API from the API Directory, store the client credentials once, and your agent calls it while Jentic handles the tokens.
- **Permission scoping:** Ocean puts the resource id in the URL path (`/fhir/v1/Patient/{patientId}` and `/fhir/v1/ServiceRequest/{referralId}`), so a rule can pin your agent to one patient or referral. You choose the operations it may call, so creating a new referral is only in the allowed set if you add it, letting reads of a patient or the site directory stay separate.
- **Credential handling:** Your Ocean OAuth 2.0 client credentials are stored once, encrypted, by your own Jentic One instance, and Jentic mints short-lived access tokens at execution time. The client secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an Ocean referral' or 'search Ocean patients', and Jentic returns the matching FHIR operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Epic FHIR API** — Pair with Epic to read source EMR data before submitting an Ocean referral
- **athenahealth API** — Pull patient and appointment data from athenahealth EMRs before creating an Ocean ServiceRequest
- **DrChrono API** — Use DrChrono as the source EMR and Ocean for community referrals out of the practice

## FAQ

### Why is there no official OpenAPI spec for Ocean Health Platform API?

CognisantMD does not publish an OpenAPI specification - only HTML API docs. Jentic generates and maintains this spec so that AI agents and developers can call Ocean Health Platform API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Ocean Health Platform API use?

Ocean uses OAuth 2.0 client credentials. Exchange your client_id and client_secret at https://ocean.cognisantmd.com/svc/oauth2/token for a Bearer access token, then send it as Authorization: Bearer {token}. Through Jentic the credentials are stored in the vault and tokens are minted on demand.

### Can I create electronic referrals through the Ocean API?

Yes. POST `/fhir/v1/ServiceRequest` accepts a FHIR R4 ServiceRequest payload containing patient reference, requester, performer, and category. The endpoint returns the created ServiceRequest with its assigned id, which the agent can use to track status via `/fhir/v1/ServiceRequest/{referralId}.`

### What are the rate limits for the Ocean Health Platform API?

CognisantMD does not publish a public rate limit. Treat the API as best-effort, back off on HTTP 429 responses, and avoid sustained high-volume polling. For status monitoring, query referrals on a schedule with _lastUpdated filters rather than polling individual ids.

### How do I search patients through Jentic?

Search Jentic for 'search Ocean patients', load the GET `/fhir/v1/Patient` schema, and execute it with the FHIR search parameters (family, given, birthdate, identifier). Jentic mints an OAuth access token from the vaulted client credentials and returns the parsed FHIR Bundle.

### Does the Ocean API expose lab results or clinical notes?

No. The current spec covers Patient, ServiceRequest, and a sites lookup only. For lab results, encounters, or clinical notes, integrate directly with the EMR's FHIR endpoint; Ocean focuses on the eReferral and patient engagement use cases.

### Can I limit what my agent is allowed to do with the Ocean Health Platform API?

Yes. Jentic One is self-hosted, so you run it and your own rules decide which Ocean operations and credentials the agent may use. You choose the allowed set of operations, so reading patients with GET `/fhir/v1/Patient` or listing clinic sites with GET `/api/v1/sites` can be permitted while POST `/fhir/v1/ServiceRequest` to create a referral stays excluded unless you add it. Because Ocean puts the resource id in the path, a rule can also pin the agent to a single patient or referral via `/fhir/v1/Patient/{patientId}` or `/fhir/v1/ServiceRequest/{referralId}.`